{

Conversational and Bot API (BETA)

Introduction

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.

Concepts and Terminology

Bot: Software making automated replies to messages
Human Agent: Human responsible for replying to messages. Often a customer support employee.
BotRouter: This virtual switchboard between multiple connected software implementations of Bots and Human Agent software.
BotRouterAccountId: Account GUID provided to you to connect with this API.
Component: Specific software technology provided by CM.com or 3rd parties, available within this API.
Customer contact: Software application that allows human agents to interact with consumers chats. CM.com's Customer Contact (capitalized) is a specific software by CM.com which integrates with and is available in this API.
CmBot: Scripted bot solution provided by CM.com, which is one of the available bots in this API.
Channel: Specific protocol (WhatsApp, Apple Business Chat) being used for communication
Clients: Receivers and Senders of messages on a channel, identified by an ID.
Chat: Unique combination of the sender and receiver clients on a Channel.
Session: Related individual messages within a Chat. Sometimes called a conversation.
Flow: Set of logic steps inside a bot
Step: Specific point within a Flow

Sending messages

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}

These types of messages are supported: ListPicker, Location, Media and Text (including the OpenUrl suggestion)
Channel fallback is not supported (first channel will always be used)
Additional fields with information specific to this API might be added in the short future.
This type of integration is called the BMProxy component.

An additional message format is also available for internal use. Read more about TwoWay

Receiving messages

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.

Supported messages

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	WhatsApp	ABC	Viber	RCS	SMS	Twitter	Facebook Messenger	Google Business Messages	Instagram Messaging
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	-	-	-
- Rich card carousel	x	x	x	√**	x	x	√**	√**	x
Location	√	x	x	√	x	x	x	x	x
Contact	-	x	x	x	x	x	x	x	x
Template	-	x	x	x	x	x	x	x	x
List picker	x	√	x	x	x	x	x	x	x
Time picker	x	-	x	x	x	x	x	x	x
OAuth2	x	-	x	x	x	x	x	x	x
Custom app	x	-	x	x	x	x	x	x	x
Payment	x	√	x	x	x	x	x	x	x
Suggestions	x	√	√	√	x	√	√	√	√
- OpenUrl	x	√	√	√	x	x	√	√	x
- Create Calendar Event	x	x	x	√	x	x	x	x	x
- Dial	x	x	x	√	x	x	√	√	x
- ViewLocation	x	x	x	√	x	x	x	x	x
- Reply	x	x	x	√	x	√	√	√	√
- Login	x	x	x	x	x	x	-	x	x
- Logout	x	x	x	x	x	x	-	x	x
- ViewProduct	x	x	x	x	x	x	-	x	x

√: full support in the bot router/scripted chatbot
-: supported in the channel but not in the bot router/scripted chatbot
x: not supported in the channel

** Carousel suggestions are currently not supported when using BMProxy

Control routing

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.

Mutation requests

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.

POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/routing/mutationrequests

{
    "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:

BMProxy
CmBot
CustomerContact

Hand-Over example

The hand-over functionality is applied in following situations:

Your bot has no answer to the question
Your bot has identified all recurring information required for the human agent to start the dialogue effectively

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.

POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/routing/mutationrequests

{
    "ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "Mutations": [{
        "$type": "disableComponent",
        "ComponentId": "CmBot"
    }]
}

Take-Over example

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.

POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/routing/mutationrequests

{
    "ChatId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "Mutations": [{
        "$type": "disableComponent",
        "ComponentId": "CmBot"
    }]
}

Hand back example

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.

POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/routing/mutationrequests

{
    "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

Skilled based routing

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"
    }
}

Command request

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

Position request

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.

Routing reset request

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.

POST https://api.cm.com/conversational/control/v1/accounts/{BotRouterAccountId}/chats/{ChatId}/routing/reset

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