NOTE: This is preliminary documentation and the API is not yet stable
This documentation is written for companies that offer Bot technologies. Implementation of this API offers you the possibility to offer your customers the CM.com customer contact software, called Customer Contact. This is used when the bot has no answer or finished its' preliminary work, and a human agent needs to complete the conversation.
The foundation of this integration is based upon the CM.com Business Messaging API, where messages are send both inbound, and outbound. Either your bot answers the incoming messages, or after a hand- or take-over a human agent can do this.
All API requests are JSON and require the HTTP header Content-Type: application/json. The contents are always utf-8 encoded unicode.
Sending and receiving messages through the botrouter can be done just as with the Business Messaging API, but you have to use a different URL endpoint instead of https://gw.cmtelecom.com/v1.0/message:
https://api.cm.com/conversational/bmproxy/v1/accounts/{BotRouterAccountId}/adapters/{AdapterId}
BMProxy component.An additional message format is also available for internal use. Read more about TwoWay
In order to receive messages from the bot router, you must implement a JSON webhook. This webhook needs to implement the same format as CM.com's MO webhooks.
These messages are expanded upon with a conversationalRouter property. This property contains fields with information specific to the conversation and bot router, like the chatId. An example is given below:
{
"from": {
"number": "+316012345678",
"name": null
},
"to": {
"number": "+316012345678",
"name": null
},
"message": {
"text": null,
"media": {
"mediaUri": null,
"contentType": null,
"title": null
},
"custom": {}
},
"reference": "2f2d42ac-3809-40fb-bce5-dc720e400000",
"groupings": [],
"timeUtc": "2020-09-16T08:23:32.8981621+00:00",
"channel": "WhatsApp",
"conversationalRouter": {
"chatId": "47e755ad-69a2-4139-a610-c53d0c8deb4b",
"accountId": "e17acdef-c918-423d-a01b-1000cd084f6a",
"adapterId": "b23a77ad-2fc3-4edd-b3d7-35b206b6b48e"
}
}The webhook must return 200 OK to indicate it has received the message (and an error status code if it didn't). Please provide the exact address of this webhook to your CM.com contact.
The bot router control commands allow you to influence and switch the behavior of the traffic routing of messages between the different components. Each type of component has a ComponenentId.
Use a mutation request to disable or enable specific components. Please note that multiple components can be active at the same time. In order to make a mutation call the following API.
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"Mutations": [{
"$type": "disableComponent",
"ComponentId": "CmBot"
},{
"$type": "enableComponent",
"ComponentId": "CustomerContact"
}]
}| Field | Description | Required |
|---|---|---|
| BotRouterAccountId | The id of the Bot Router connection as provided to you. | Yes |
| ChatId | The hash of the channel + from + to fields transposed to a guid. You should have received this in earlier communication between the router and your component. | Yes |
| FlowId | The element name of the template that will be used, will be provided to you after the template is approved | Yes |
| StepId | Specifies the language, see below for object definition | Yes |
| Mutations | Array of mutation objects | Yes |
| Context | Array of mutation objects | Yes |
Mutation Object
| Field | Description | Required |
|---|---|---|
| $type | The type of mutation to execute. Can be either: disableComponent or enableComponent | Yes |
| ComponentId | The Id of the component to enable or disable. |
Currently known ComponentIds are:
The hand-over functionality is applied in following situations:
For this mutation you disable the CmBot component. The other connected components are notified of the mutation. Notice how we are not enabling the Human agent software Customer Contact in this example. This is because Customer Contact always receives all conversations, it just lies dormant until CmBot is disabled.
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"Mutations": [{
"$type": "disableComponent",
"ComponentId": "CmBot"
}]
}The action from a take-over lies with the human agent in Customer Contact. He/She identifies that a chat needs attention. After taking over, we need to let the bot know it no longer needs to respond. That is done with this API call. Switching the bot off will make sure the bot won’t send a reply.
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"Mutations": [{
"$type": "disableComponent",
"ComponentId": "CmBot"
}]
}Re-enable the CmBot a.k.a. hand back to CmBot. Use this when you want the bot to actively respond again. Follow up this call with a PositionRequest directly afterwards, to direct the conversation to a specific point in the CmBot.
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"Mutations": [{
"$type": "enableComponent",
"ComponentId": "CmBot"
}]
}Let the bot do the work We have also identified situations where the agent helped the customer further, but where the bot can work effectively again. This is applies in situations where: You have assisted and found the right context (ie. order number) The conversation has finalized and you want to round-up the conversation Your customer has another request, but for a different team You want to look-up order information in external systems and the integration and validation is done within the bot
When you want to make your processes more effective, you can apply routing towards a specific team that works in Customer Contact. In Customer Contact the EXACT SAME values are configured against teams. When those values are recognized/matched the conversation is assigned to that specific team. When no match can be made, no worries, we will transfer the full conversation to the generic inbox. From the generic inbox any agent can take it from there, and still has the full context. Information about the values we expect you can find here { Link to to be made help center }.
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"Mutations": [{
"$type": "XXXX",
"ComponentId": "CmBot"
}],
"Context": {
"Var1": "Value1",
"Var2": "Value2"
}
}Request CmBot to move to a specific point in it's scripts.
POST http://url/conversational/control/v1/accounts/{BotRouterAccountId}/sessions/positionrequests
{
"ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
"FlowId": "chat_flow_you_want_to_continue",
"StepId": "step_within_that_flow_you_want_to_continue"
}| Field | Description | Required |
|---|---|---|
| BotRouterAccountId | The id of the Bot Router connection as provided to you. | Yes |
| ChatId | The hash of the channel + from + to fields transposed to a guid. You should have received this in earlier communication between the router and your component. | Yes |
| FlowId | The Id of a flow in the CmBot component to which you want to position to. | Yes |
| StepId | The Id of a step inside the FlowId in the CmBot component to which you want to position to. | Yes |
Please note that there is currently no way to enumerate a list of flowid/stepid values to choose from. You need to know them upfront.
Make a request to the conversational router to reset the routing back to the default settings. This cancels out any mutations that components have requested.
This request doesn't require a request body
| Field | Description | Required |
|---|---|---|
| BotRouterAccountId | The id of the Bot Router connection as provided to you. | Yes |
| ChatId | The hash of the channel + from + to fields transposed to a guid. You should have received this in earlier communication between the router and your component. | Yes |