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.

Alternative

When TwoWay does not fit your needs, please get in touch with the team behind the Conversational Router (via your CM.com contact). In certain cases, it may be preferable to use our older Business Messaging API.

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.

11491149

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.

15831583

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.

15771577

Fill out the URL to your handover webhook here.

Authentication

TwoWay requires a product token to be present on each incoming request. This has to be added as a X-Cm-Producttoken header. The Business Messaging API documentation contains instructions on retrieval of this product token.

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.

11121112

Clicking the button will put the URL in your clipboard.

The generic format of such an URL is https://api.conversational.cm.com/conversational/bmproxy/v1/accounts/{technicalLinkId}/adapters/{adapterId}.

Messages sent there must adhere to the TwoWay format.

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.