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.

1149 — Click on the TwoWay adapter type to create a new 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.

1583 — Fill out the URL to your message webhook here.

If your application is used in a context where handovers occur an URL can be appointed to which notifications of these handovers are sent.

1577 — Fill out the URL to your handover webhook here.

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.

Fill out the URL to your events webhook here.

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.

1112 — Clicking the button will put the URL in your clipboard.

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.