Custom integration
When creating a custom integration your application has to talk to our RESTful API. We have created a format, or protocol, which we call TwoWay. In essence, it is a JSON schema to which you have to adhere when sending and receiving messages to/from the Conversational Router.
How-to
Following gives a succinct description of how to create a custom integration via TwoWay.
Starting point
The starting point of this documentation is the Scripted Chatbot configuration application. All descriptions are based on the fact you are on that page.
Creating an adapter
Messages going through the Conversational Router are sent and received by adapters. To create a custom integration you need to create a new TwoWay adapter.
After choosing the adapter type you are shown a configuration screen. To be able to receive messages you must have a publicly accessible webhook.
If your application is used in a context where handovers occur an URL can be appointed to which notifications of these handovers are sent.
Underneath a body can be defined. This is what will be passed as the request body. It can be customised, using a number of variables that will be replaced with the runtime values belonging to the running the session: $chatId
, $sessionId
, $accountId
, $channel
, $conversationHostId
, $conversationClientId
and $context
.
During a session events will come by. Events can be seen as metadata about a conversation, giving information not on the content that is shared but in what context that is being done. Being notified about these events can be achieved by filling out the events endpoint.
Sending messages
Sending messages is done by doing HTTP POST
requests to the outbound URL of an adapter. To get the outbound URL of an adapter click on the button corresponding to the adapter for which you want to send messages.
The generic format of such an URL is https://api.conversational.cm.com/conversational/twoway/v2/accounts/{technicalLinkId}/adapters/{adapterId}
.
Messages sent there must adhere to the TwoWay Format. Authentication is required when sending messages. Details concerning this can be found in the Authentication page.
Receiving messages
As already mentioned, in order to receive messages from the Conversational Router you must implement a JSON webhook. Messages sent there adhere to the TwoWay Format.
Messages will always come from IP address 34.141.248.107
.
Updated 9 months ago