This guide is meant to provide additional context to the existing documentation on our APIs and architecture, as well as provide concrete examples of how starter kits have worked with other service desks.
To successfully create a custom integration with an existing service desk, developers will need to implement the functions listed in our API documention. In order to implement these APIs, however, the developer will first need access to certain exposed API endpoints of the service desk application, which are detailed in the following.
The service desk must support client-side integrations using a browser-based (usually WebSockets or polling) API to connect from the service desk API to within the web chat browser.
Core "must have" Functionality: startChat, endChat, sendMessageToAgent
Note: The specific parameters of the APIs are up to the service desk application to decide - as you will see in the example implementations from Genesys and Twilio Flex, their API structure, parameters, and return values vary depending on their internal code structure. At the end of the day, as long as the essential information is retrievable, how you expose these APIs is completely up to you.
Called upon escalation to execute whatever necessary steps exist to create a conversation with an agent in the service desk.
- Need: Endpoint(s) that will configure/begin a chat session with an agent. If your service allows user authentication as well, we will need endpoints that enable this. For instance, if your service desk uses a special kind of authentication token that is generated based on certain keys or IDs, we will need an endpoint/guide on how to generate those tokens, and will also need be able to set/send those tokens back to the service desk.
- Examples:
Called when the user clicks "End live chat" in the widget to end the conversation with the agent.
- Need: Endpoint that will stop a conversation with an agent.
- Examples:
- Genesys: deleteWebchatGuestConversationMember(...)
- Twilio: leave(...)
Used to relay user messages from WA chat to service desk, within a chat session with a live agent.
- Need: Endpoint for sending a message to the service desk conversation that was opened through startChat.
- Examples:
- Genesys: postWebchatGuestConversationMemberMessages(...)
- Twilio: sendMessage(...)
Lastly, we also need to be able to listen to events from the service desk, so that the WA chat widget can respond (all our available callback functions are listed and described in the API documentation).
For instance, when an "agent is typing" event is posted, we then need to let our widget know to render the typing indicator. When an agent message is received from the service desk, we need to relay the message to the user. As such, there needs to be a designated way to continuously receive events from the service desk during a conversation. The Genesys API implements this via a web socket, and Twilio Flex provides a channel on which we can listen to events. We recommend looking at their implementations for clarity.