{
  1. Introduction
  2. Sending messages
  3. Receiving messages
  4. Control routing
    1. Mutation requests
      1. Hand-over
      2. Take-over
      3. Hand-back
    2. Position request

Conversational and Bot API (ALPHA)

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 an different URL endpoint instead of https://gw.cmtelecom.com/v1.0/message:

https://api.cm.com/conversational/bmproxy/v1/accounts/{BotRouterAccountId}

  • Only text messages are supported at this moment
  • 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.

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

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.

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

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

Position request

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.