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.  

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 metadataentities 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.  

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

{
  "conversation": "1234",
  "type": "intent",
  "message": "CHANNEL_STARTED_STARTED",
  "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:

Bot Actions

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

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

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