DigitalGenius Headless Chat SDK
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 idenv
- which env the widget is running inmetadata
- 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 messageuploadFileRequest
The flow has requested the user upload an fileuploadPictureRequest
The flow has requested the user upload an imageerror
- An error has occured somewhere in the Flowhelpdesk_handover
- The Flow has begun the process to hand over to the configured helpdeskhandover_error
- There was an error in the handover processagent_joining
- A helpdesk agent is joining the chatagent_transferred
- The helpdesk agent transferred the end user to another agentqueue_update
- The end users queue position to talk to a helpdesk agent has updatedcsat_request
- The flow has requested that the end user provide csat feedbackunassigned
- 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 chatfile_transfer_request
- The Saleforce agent has requested the user upload a filefile_transfer_cancel
- The Saleforce agent has cancelled the request for the user to upload a file
Updated 9 months ago