Documentation

DigitalGenius Headless Chat SDK

Suggest Edits

The DigitalGenius Chat SDK allows you to build customised experiences powered by the DigitalGenius bot. It is built using JavaScript and is intended for use in a web browser environment.

Getting Started

In order to use the SDK you need to include the SDK script in your html just before the closing body tag:

<!DOCTYPE html>
<html>
  <head>
    <title>DigitalGenius Headless Chat</title>
  </head>
  <body>
    <script src="https://chat-assets.digitalgenius.com/dgchatsdk/sdk.vx.x.x.min.js"></script>
  </body>
</html>

The SDK exposes a global DGChatSDK object on the browser window object.

In order to initialise the SDK you need to call the init method:

 window.DGChatSDK.init({
  id: 'f0c07546-af4c-4963-9e23-3e9343eaf13b',
  env: 'eu',
});

Your customer success manager will be able to provide you with values for the id and env properties.

Once inited you will need to subscribe to the sdk's onReady callback. Once this callback has been fired you can start interacting with the SDK:

window.DGChatSDK.onReady(() => {
   console.log('DG Chat SDK is ready');
});

Methods

init

Initialises the widget SDK:

 window.DGChatSDK.init({
  id: string,
  env: string,
  metadata: object
});
  • id - the widget id
  • env - which env the widget is running in
  • metadata - pass optional data to the Flow

sendEvent

Send an event to DG systems from the SDK. Must be called after the onReady event has fired.

window.DGChatSDK.sendEvent(() => ({ type: string }))

Possible types are:

start

Starts the chat conversation.

window.DGChatSDK.sendEvent(() => ({ type: 'start' }))

end

End the chat conversation

window.DGChatSDK.sendEvent(() => ({ type: 'end' }))

restart

Restarts the chat conversation

window.DGChatSDK.sendEvent(() => ({ type: 'restart' }))

message

Send a message to the chat conversation. If you want to initialise the conversation with a message from the user be sure to call sendEvent with a type of message before sending the start event.

window.DGChatSDK.sendEvent(() => ({ type: 'message', payload: string }))

csat score

Send a csat score

window.DGChatSDK.sendEvent(() => ({ type: 'csat_provided', score: number }))

csat comment

Send a csat comment - must be called after csat score has been set

window.DGChatSDK.sendEvent(() => ({ type: 'csat_comment', message: string }))

Events

onReady

Fired when the SDK is ready to be interacted with.

  window.DGChatSDK.onReady(() => {
    console.log('DG Chat SDK is ready');
  });

onMessage

Fired when a message is sent by the DG bot

window.DGChatSDK.onMessage((message: object) => {
  addMessageToDom(message: object);
});

The shape of the message object will depend on the type of message being sent. See this documentation for full details on the types of payloads and all possible properties: https://docs.digitalgenius.com/docs/flow-messages

onSystemEvent

Fired when the DG bot sends a system message. The bot will send system messages to inform the SDK about the following events

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

The possible event types are:

  • timeout The widget timed out (by default this is set to timeout after 24 hours - this can be configured)
  • system_message - The flow send a generic system message
  • uploadFileRequest The flow has requested the user upload an file
  • uploadPictureRequest The flow has requested the user upload an image
  • error - An error has occured somewhere in the Flow
  • helpdesk_handover - The Flow has begun the process to hand over to the configured helpdesk
  • handover_error - There was an error in the handover process
  • agent_joining - A helpdesk agent is joining the chat
  • agent_transferred - The helpdesk agent transferred the end user to another agent
  • queue_update - The end users queue position to talk to a helpdesk agent has updated
  • csat_request - The flow has requested that the end user provide csat feedback
  • unassigned - The helpdesk agent unassigned themselves from the chat

Salesforce specific event types:

  • idle_timeout_countdown - If handover via Salesforce is enabled then Salesforce will sending a warning when the end user has been inactive. Use this to display a message to the user that they need to send a message in x seconds to avoid the chat timing out
    idle_timeout - Salesforce will send this event when the idle timeout countdown has been reached. In this context you should end the chat
  • file_transfer_request - The Saleforce agent has requested the user upload a file
  • file_transfer_cancel - The Saleforce agent has cancelled the request for the user to upload a file

Updated 7 months ago