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.
Note: please whitelist the IP 34.141.248.107
we use for sending these messages to you (if necessary)
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 integrates with the Business Messaging API and therefore shares much of the functionality. For a complete list of all messages that the Business Messaging API supports and more details about channel specific behaviour. Please refer to the Business Messaging API's documentation.
The following messages are supported in the bot router/scripted chatbot:
Conversation item type | ABC | Viber | RCS | SMS | Facebook Messenger | Google Business Messages | Instagram Messaging | Telegram Messenger | ||
---|---|---|---|---|---|---|---|---|---|---|
Text | √ | √ | √ | √ | √ | √ | √ | √ | √ | √ |
- Text formatting | √ | x | x | x | x | √ | √ | √ | √ | √ |
- URL previews | √ | √ | x | x | x | √ | √ | √ | √ | √ |
Media | √ | √ | √ | √ | x | √ | √ | √ | √ | √ |
- Image | √ | √ | √ | √ | x | √ | √ | √ | √ | √ |
- Video | √ | √ | x | √ | x | √ | √ | x | x | √ |
- Audio | √ | √ | x | √ | x | x | √ | x | x | √ |
- Rich card | x | x | - | - | x | x | - | - | - | x |
- Rich card carousel | x | x | x | √** | x | x | √** | √** | x | x |
Location | √ | x | x | √ | x | x | x | x | x | x |
Contact | - | x | x | x | x | x | x | x | x | x |
Template | - | x | x | x | x | x | x | x | x | x |
List picker | x | √ | x | x | x | x | x | x | x | x |
Time picker | x | - | x | x | x | x | x | x | x | x |
OAuth2 | x | - | x | x | x | x | x | x | x | x |
Custom app | x | - | x | x | x | x | x | x | x | x |
Payment | x | √ | x | x | x | x | x | x | x | x |
Suggestions | x | √ | √ | √ | x | √ | √ | √ | √ | x |
- OpenUrl | x | √ | √ | √ | x | x | √ | √ | x | x |
- Create Calendar Event | x | x | x | √ | x | x | x | x | x | x |
- Dial | x | x | x | √ | x | x | √ | √ | x | x |
- ViewLocation | x | x | x | √ | x | x | x | x | x | x |
- Reply | x | x | x | √ | x | √ | √ | √ | √ | x |
- Login | x | x | x | x | x | x | - | x | x | x |
- Logout | x | x | x | x | x | x | - | x | x | x |
- ViewProduct | x | x | x | x | x | x | - | x | x | x |
** Carousel suggestions are currently not supported when using BMProxy
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 | The context of the mutation request that can be used for skill based routing. | No |
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"
}
}
NOTE: This feature is still in active development
Commands are a group of preconfigured mutation requests that are capable of disabling or enabling specific components as well as perform handovers and takeovers.
In order to use commands they first have to be configured for your bot router account.
POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/commands
{
"Name": "Handover",
"Origin": "test",
"Context": {
"Var1": "Value1",
"Var2": "Value2"
}
}
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 |
Name | The name of the command that's configured for the associated Bot Router account. | Yes |
Origin | The origin of the command request used in analytics. Please provide the name of your app or company in this field. | Yes |
Context | The context of the command request that can be used for skill based routing. | No |
Request CmBot to move to a specific point in its 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",
"Context": {
"Var1": "Value1",
"Var2": "Value2"
}
}
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 |
Context | The context of the command request that can be used to override session variables already defined in chat script. | No |
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 |
Constructs the ChatId belonging to the provided properties passed to this call.
Note: this endpoint requires the X-Cm-Producttoken
header to be present
Field | Description | Required |
---|---|---|
BotRouterAccountId | The id of the Bot Router connection as provided to you | Yes |
Channel | The channel you're sending the message(s) with | Yes |
ClientId | The client identifier you send the message(s) with | Yes |
HostId | The host identifier you send the message(s) to | Yes |
These client and host identifiers correspond to the identifiers of the channel you're sending with. For WhatsApp that's the phone number, for Twitter it's the Twitter ID, etc.