GroupFi Chatbox SDK

GroupFi Chatbox SDK enables developers to easily integrate GroupFi's chatbox with their dApps on EVM chains, Solana through popular wallet extensions, including MetaMask, OKX Wallet, Phantom Wallet, Trust Wallet and so on.

Features

• Chatbox-dApp integration via an iframe.
• API's facilitating Chatbox-dApp interactions.

Integration examples

• React MetaMask SDK integration demo
• React Wagmi integration demo
• React RabbyKit integration demo
• Nextjs Wagmi intergration demo

Get started

For MetaMask SDK, please refer to MetaMask SDK documentation. Other wallet SDKs' work similarly as the MetaMask SDK.

Install the Chatbox SDK in your project's root directory:

pnpm add groupfi-chatbox-sdk

or

npm install groupfi-chatbox-sdk

Usage

The SDK is provided in two build formats: IIFE and ESM

To use the IIFE Build Artifacts in Pure JavaScript

1. Load the CSS:

   <link rel="stylesheet" href="<path_to_iife>/assets/style.css" />

2. Load the JavaScript:

   <script src="<path_to_iife>/index.js" async></script>

Ensure to replace <path_to_iife> with the actual path to the IIFE build artifacts of the SDK.

To use the ESM build

1. Import the CSS file:

   import 'groupfi-chatbox-sdk/dist/esm/assets/style.css';

2. Import the SDK:

   import ChatboxSDK from 'groupfi-chatbox-sdk'

API Usage

After importing the SDK, loadChatbox API can be called to embed the Chatbox interface

• loadChatbox:

  ChatboxSDK.loadChatbox(configs: {
    isWalletConnected: boolean,
    provider?: any,
    uiConfig?: {
      theme?: 'light' | 'dark',
      accent?: 'blue', 'violet' | 'red' | 'orange' | 'yellow' | 'amber' | 'grey'
      title?: string,
      subTitle?: string,
      logoUrl?: string, // The logo will be displayed in a 128px by 128px container
      bubbleIcon?: {
        url?: string, // The icon will be displayed in a 42px by 48px container
        position?: {
          left?: number,
          top?: number
        }
      }
    }
  })

  Parameters:

  • configs (required): An object containing various configuration options
    • isWalletConnected (required): Whether the wallet is connected with the Chatbox.
    • provider (required if isWalletConnected is true): A Wallet Provider is an interface that allows Chatbox to interact with the wallet. If a wallet is connected, a provider must be provided.
    • uiConfig (optional): The uiConfig object allows for customization of the Chatbox’s visual elements, including accent color, text, and logo. Each property is optional and modifies specific UI components.
      • theme (optional): specifies the theme style for Chatbox. Options include light (light theme) and dark (dark theme). Default theme light.
      • accent (optional): Defines the accent color for the Chatbox. Available options are blue, violet, red, orange, yellow, amber, and grey. The default accent color is blue.
      • title (optional): Sets a custom title for the Chatbox. The default title is GroupFi Chatbox.
      • subTitle (optional): Sets a custom subtitle for the Chatbox. The default subtitle is Decentralized Chat, Unified Community.
      • logoUrl (optional): Specifies the URL of the logo image, which will be rendered in a 128x128px container. For optimal display:
        • Use a square image (128x128px or larger) to prevent distortion.
        • Recommended formats: PNG, SVG, or JPEG for the best quality.
        • If the provided image has a different aspect ratio, it will be scaled to fit within the 128px by 128px container, which may result in cropping or resizing.
      • bubbleIcon (optional): Customizes the appearance of the chatbox bubble icon.
        • url (optional): The URL for the custom bubble icon image, displayed in a 42x48px container. Images larger or with different aspect ratios may be cropped or resized to fit. Recommended formats: PNG, SVG, or JPEG.
        • position (optional): Adjusts the icon’s position relative to its default location.
          • left (optional): Horizontal shift in pixels. Positive moves the icon left, negative moves it right.
          • top (optional): Vertical shift in pixels. Positive moves the icon up, negative moves it down.

  Note loadChatbox currently only support Chatbox embedding on a PC but not on a mobile device.

  Listen to the chatbox-ready event triggered by the chatbox to check if the Chatbox has been successfully loaded. Only then is the Chatbox ready for interaction.

  1. Using window.addEventListener:

     window.addEventListener('chatbox-ready', (event: CustomEvent<{
       chatboxVersion: string
     }>) => {
       console.log(`Chatbox is ready with version: ${event.detail.chatboxVersion}`);
     });

  2. Using ChatboxSDK.events.on:

     ChatboxSDK.events.on('chatbox-ready', (data: { chatboxVersion: string }) => {
       console.log(`Chatbox is ready with version: ${data.chatboxVersion}`);
     });
              

Additional API's after the Chatbox has been successfully loaded:

• removeChatbox: Remove Chatbox from dApp.

  ChatboxSDK.removeChatbox()

• processWallet: Notify about changes in the wallet, to be called when connecting wallet, disconnecting wallet, or switching wallet.

    ChatboxSDK.processWallet(walletData: {
      isWalletConnected: boolean,
      provider?: any
    })

  Parameters:

  • walletData (required): An object containing the wallet information.
    • isWalletConnected (required): Whether the wallet is connected with the Chatbox.
    • provider (required if isWalletConnected is true): A Wallet Provider is an interface that allows Chatbox to interact with the wallet. If a wallet is connected, a provider must be provided.

• processAccount: Specify which account to interact with, to be called on startup or after switching accounts within the same wallet.

    /**
     * @param {object} data - The data object containing the account information.
     * @param {string} data.account - The new account address to be used by Chatbox.
     */
    ChatboxSDK.processAccount(data: {
      account: string
    })

Note:

• After loadChatbox or processWallet, processAccount is required if the wallet is in a connected state.
• When connecting, disconnecting, or switching wallets, processWallet needs to be called.

Based on the above points, here are specific scenarios:

Starting the Chatbox:

• If the wallet is already connected at startup, call loadChatbox, followed by processAccount.
• If the wallet is not connected at startup, call loadChatbox with isWalletConnected = false to enter guest mode.

After the Chatbox has started, when the user performs the following actions:

• Connect wallet: call processWallet, followed by processAccount.
• Disconnect wallet: call processWallet with isWalletConnected = false.
• Switch to a different wallet (e.g. from MetaMask to OKX Wallet): call processWallet with a new provider, followed by processAccount with a new account address.
• Switch accounts within the wallet: simply call processAccount with a new account address.

Request Chatbox to perform certain operations:

• request:

  /**
    * @param {object} data - The data object containing the method and parameters for the request.
    * @param {string} data.method - The method name of the operation to be performed by Chatbox.
    * @param {Object} data.params - The parameters needed for the method.
    */
  ChatboxSDK.request(data: {
    method: string,
    params: any
  })

  Supported methods currently include:

  • setGroups: Used to specify recommended groups for a dApp

    // Interface representing a group
    interface IGroup {
      groupId: string, // Each group is represented by a unique identifier `groupId`.
      buylink?: string // Buylink is a link to purchase a token for joining the group.
    }
    
    /**
      * Request to set recommended groups for the user's Dapp.
      * @param {object} data - The data object containing the method and parameters for the request.
      * @param {string} data.method - The method name ('setGroups').
      * @param {object} data.params - The parameter object for this method.
      * @param {IGroup[]} [data.params.includes] - Groups to include in recommendations.
      * @param {IGroup[]} [data.params.announcement] - Groups to mark as announcement groups. The announcement group has a special style.
      */
    ChatboxSDK.request({
      method: 'setGroups',
      params: {
        includes?: IGroup[],
        announcement?: IGroup[]
      }
    })

    Example:

    ChatboxSDK.request({
      method: 'setGroups',
      params: {
        // Groups to include in recommendations
        includes: [
          {
            groupId: 'groupfiGTESTd2b7278595668cc19192e6d4fd0b49cb8615b5f240e00cf58c80565c5274eab7'
          }
        ],
        // Groups designated for announcements
        announcement: [
          {
            groupId: 'groupfiGTESTd2b7278595668cc19192e6d4fd0b49cb8615b5f240e00cf58c80565c5274eab7'
          }
        ]
      }
    })

GroupFi Group Lookup Tool

GroupFi provides a service to query the group ID based on the EVM chain ID and the contract address of tokens/NFTs.

    • Service URL: Group Explorer

If the token/NFT you want to add doesn't have a group yet, please contact us to create one:

    • Contact Us: GroupFi Contact

If you want to add many groups to your website, especially different groups on different pages, please use the lookup API below.

Groupfi Group Lookup API

The Groupfi Group Lookup API enables dApp developers to easily retrieve group configurations using an EVM Chain ID and Contract Address, facilitating seamless integration of the Groupfi chatbox with specific groups.

API Endpoint

• URL: https://api.config.groupfi.ai/api/groupfi/v1/dappquerygroupconfigs
• Method: POST

Request

To query the group configurations, send a POST request with the following JSON payload:

{
  "contractAddress": "0x544F353C02363D848dBAC8Dc3a818B36B7f9355e",
  "chainId": 148
}

Response

The API returns a JSON array with the group name and group ID associated with the provided Chain ID and Contract Address.

Example Response

[
    {
        "groupName": "Groupfi's test nft group",
        "groupId": "groupfiGroupfi'stestnftgroup441480db9942f0f2929dcaa365fe6f6a9362de4c5eb27daf0c1d9aaf21d198d9"
    }
]

Example Response When No Match is Found

null

Integration

1. Send Request:

   • Send a POST request to the API endpoint with the contract address and Chain ID in the JSON payload.

2. Receive Response:

   • Parse the JSON response to extract the group name and group ID.

3. Use Group ID:

   • Use the retrieved group ID to integrate the Groupfi chatbox with the specific group in your dApp.