Skip to main content
Skip table of contents

Custom Connector-Bot Communication

The custom Bot Connector sends information to the bot about a particular conversation by transmitting messages and intents. The bot responds by sending a message or bot suggestion or request for action.

Messages are customer generated events in a conversation. Intents are system events intended to convey a specific system activity e.g. CHANNEL_SESSION_STARTED. An intent also directs the bot on how to respond to the sender. Messages, Bot Suggestion and Actions are types of bot responses as a result of the intent.  

Quick Links

The request-response structure from the custom bot connector-bot is given below:

CIM Request

There are two types of request that the custom Bot connector must handle:

  1.  Message: customer message to be sent to the bot for response/action.
  2.  Intent: intent needs to be sent to the bot for response/action.

Send a Message to the Bot

Whenever a message request is received by the Bot Framework as CIM event CUSTOMER_MESSAGE, the connector must compose a request body with type = "message" indicating user message and not the intent of the message. The code example is given on the right hand side.

  • the request body also contains entities and metadata
    • entities are NULL for messages
    • metadata contains CIM Message object. The CIM Message Object can contain any type of message and the format is described here in detail.

Send an Intent to the Bot

There are multiple types of intents that needs to be sent to the bot for action. Whenever an intent is sent to the bot by the custom Bot Connector, the request body contains:

  • type = "intent" indicating that this contains the intent of the message
  • the request body also contains entities and metadata
    • entities contain the data of the intent e.g. channel session object etc. 
    • metadata for an intent is NULL

The following table gives the list of intents.  

Intent nameIntent DataFired When
CHANNEL_SESSION_STARTEDA channelSession objectA customer starts a conversation on a channel.
CHANNEL_SESSION_ENDEDA channelSession objectA chat ended on a channel
END_CONVERSATIONA channelSession object
An agent is reserved and will be added to the conversation
AGENT_SUBSCRIBEDA CcUser ObjectAn agent joins a conversation
AGENT_UNSUBSCRIBEDA CcUser ObjectAn agent leaves a conversation

Message Request

    "conversation": "1234",
    "type": "message",
    "message": "Hello how are you",
    "entities": null,
    "metadata": {<CimMessage>}

Intent Request

  "conversation": "1234",
  "type": "intent",
  "entities": {
    "channelSession": {}
  "metadata": null

Bot Response 

The custom Bot Connector should expect three types of responses from the bot at most:

  1. messages - Message types are described here in detail
  2. bot suggestion - is also a type of message
  3. action - these are described in the table Bot Actions

In all of the three cases, following is the response structure. Examples are shown in the code block on the right:

Payload PropertyTypeDescription



It contains the following information:

  1. name - String - name of the event/intent.
  2. confidence - Numeric - specifies confidence level confident the bot is about its understanding of message. For system events the confidence will be 1.0.


StringThe mode specifies whether the bot is primary or secondary (message vs. suggestion) 



It contains the following information:

  1. type - String - specifies type of message e.g. Plain, Video or Action etc. The message types are described in detail.
  2. markdownText - String - Any text from the agent/customer
  3. name - String - Name of event e.g. FIND_AGENT, END_CONVERSATION. The actions are listed below in the table.

Bot Actions

Following are the actions sent by the bot to the custom connector:

Action nameAction Data
  • reasonCode - CANCELLED
  • reasonCode - CANCELLED

Response: Message\Suggestion

 "intent": {
    "name": "Greet",
    "confidence": 0.92
  "mode": "message | suggestion",
   "body": {
     "type": "PLAIN",
     "markdownText": "Welcome"

Response: Action

  "intent": {
    "name": "TALK_TO_AGENT",
    "confidence": 0.92
  "mode": null,
  "body": {
    "type": "ACTION",
    "markdownText": "",
    "name": "FIND_AGENT",
    "data": {}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.