Documentation
Start typing to search…

Genius Chat Headless Chat SDK

The Genius Chat SDK allows you to build customised chat experiences powered by DigitalGenius.

Getting Started

Include your configuration and the SDK script in your HTML just before the closing body tag:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <script>
      window.DG_SDK_CONFIG = {
        widgetId: 'your-widget-id',
        env: 'eu', // 'eu', 'us', or 'dev.us'
      }
    </script>
    <script src="https://chat.digitalgenius.com/init-sdk.js"></script>
  </body>
</html>

Once the script loads, ensure to subscribe to events before initialising the SDK.

Example

// Wait for the SDK Script to load
window.addEventListener('onDGSDKScriptLoaded', async () => {
  // Subscribe to messages
  window.DGChatSDK.onMessage((message) => {
    console.log(message)
  });

  // Subscribe to system events such as typing start / stop
  window.DGChatSDK.onSystemEvent((event) => {
    console.log(event)
  });

  // Initialise the SDK, must be awaited
  await window.DGChatSDK.init();
});

Methods

init

The init method sets up the SDK by establishing all required connections. It returns a promise that resolves once everything is fully initialised, and it must be awaited to ensure that no other SDK methods are used before the SDK is ready.

An end usersname and email can be passed to the init method, as well as a freeform metadata object.

Ensure you have subscribed to any event listeners before calling the init method.

await window.DGChatSDK.init({
  name: 'John Doe',
  email: '[email protected]',
  metadata: {
    locale_code: 'en-GB',
  },
});

sendMessage

Sends a user message,

window.DGChatSDK.sendMessage({ type: "message", payload: "Hello!"  });
window.DGChatSDK.sendMessage({ type: "message", payload: selectedQuickReply.id  });
window.DGChatSDK.sendMessage({ type: "listSelection", payload: selectedListItem  });

Supported types are currently: message and listSelection.

startConversation

Initiates a new conversation with the bot.

Only use this is if conversations start with messages from the bot. Otherwise start the conversation with a user message.

window.DGChatSDK.startConversation();

endConversation

Ends the current conversation, disconnects WebSocket, and clears session data.

window.DGChatSDK.endConversation();

restartConversation

Restarts the current conversation, returning to the beginning of the flow.

window.DGChatSDK.restartConversation();

Event Listeners

onMessage

Fired when the bot sends a message.

window.DGChatSDK.onMessage((message) => {
  console.log('Received message:', message);

  switch (message.type) {
    case 'message':
      // handle text messages
      break;
    case 'quick_reply':
      // handle quick reply buttons
      break;
  }
});

Possible Message Types:

  • message - Text messages
  • carousel - Product carousels
  • select_dropdown - Dropdown selections
  • quick_reply - Quick reply buttons
  • calendar - Calendar picker
  • form - Form inputs
  • list - List selections
  • attachment - File attachments
  • crm_handover - CRM integration handover
  • batch - Batch messages
  • order_tracker - Order tracking information
  • video - Video messages
  • return_overdue - Return process messages
  • advanced - Advanced message

onSystemEvent

Fired when the bot sends system events for chat state changes.

window.DGChatSDK.onSystemEvent((event) => {
  console.log('System event:', event);
});

System Events

The SDK emits various system events to inform you about chat state changes:

General Events

  • typing_start - Bot / Agent started typing
  • typing_stop - Bot / Agent stopped typing
  • joined - Helpdesk agent joined
  • disconnect - Helpdesk agent disconnected
  • agent_joining - Helpdesk agent is joining
  • agent_transferred - Helpdesk agent transferred user to another agent
  • timeout - Chat session timed out (default: 24 hours)
  • system_message - Generic system message from the flow
  • uploadFileRequest - Flow requests file upload
  • uploadPictureRequest - Flow requests image upload
  • error - Error occurred in the flow
  • helpdesk_handover - Handover to helpdesk initiated
  • handover_error - Error during handover process
  • queue_update - Queue position updated
  • csat_request - CSAT feedback requested
  • unassigned - Agent unassigned from chat

Salesforce-Specific Events

  • idle_timeout_countdown - Warning before idle timeout
  • idle_timeout - Idle timeout reached
  • file_transfer_request - Agent requests file upload
  • file_transfer_cancel - Agent cancels file upload request

Updated about 16 hours ago