Chatbot API

Use Chatbot API to integrate any chatbot with Hybrid Chat. Connector for Rasa bot is available out of the box. Integration with DialogFlow and IBM Watson has also been tested but not yet generally available. Integration with other chatbots may be developed using the same Chatbot API.

Integration Steps

  1. Establish a socketIO connection with the Chat server on the chat server public URL https://<FQDN-CHAT-SERVER>:PORT where FQDN-CHAT-SERVER is the Chat server domain name or IP address accessed directly or via reverse proxy and PORT is the port number the Chat socket server is listening on. 
    By default, the Chat server listens on 8080 (HTTP) or 443 (HTTPS).
  2. Register bot-connector by emitting registerBot event
  3. subscribe for initConversation, once new conversation is initiated, chat server will notify bot on initConversation, join the conversation by emitting joinConveration for bidirectional communication.
  4. Implement Send and Receive messages for sending and receiving messages from the Chat server.
  5. subscribe for conversationList event for failover support

Events

Here is the list of all possible events which can be used as a command sent to server and events received from the server. Origin of each event is specified by Source.

Event Name

Description

registerBotThe registerBot event is used to register bot-connector as participant with the chat-server
initConversationThe initConversation is received once new conversation is initiated.

joinConversation

The joinConversation event is used to join the conversation to send and receive messages.

messageArrived

The messageArrived event is used to receive messages from other participants. Client needs to subscribe to this event.

sendMessage

The event used to send a message to a conversation. Client needs to emit this event.

endConversation

The endConversation event is used to end an active conversation.

conversationListThe conversationList event is used to recieve all converrsations list, this is specific for the bot-connector
updateTrackerUpdate Bot-connector with the chosen Bot suggestion

registerBot

The registerBot event is emitted by the client after socket-connection is successfully established with the chat-server.

Protocol

Websockets

Event Name

registerBot

Source

Client

Input/Output Format

JSON

Request Payload

{ 
"id": "bot",
"name": "bot",
"type": "bot"
 }

Payload Parameters

id: primary bot is is always bot

name: name of the bot

type: type is always set to bot

Event Triggered

conversationList

initConversation

The initConversation event is received once new conversation is started.

Protocol

Websockets

Event Name

initConversation

Source

Client

Input/Output Format

JSON

Request Payload

{ 
 "conversationId": "conversationId",
 "customerInfo": "customer object"
}

Payload Parameters

conversationId: Id of the conversation

customerInfo: customer object containing customer information

Event Triggered


joinConversation

The joinConversation event is used to join the conversation to send and receive messages.

Protocol

Websockets

Event Name

joinConversation

Source

Client

Input/Output Format

JSON

Request Payload

{
 
"conversationId": "5ae01d346c25be4319a9df95",
 
"participant": {
 
  "id":"bot",
  "name":"bot",
  "type": "Rasa"
 },
 
"timestamp": "2018-05-07T06:52:21.661Z"
 
}

Payload Parameters

conversationId: Id of the conversation to join

id: Id of the bot

name: Name of participant to display in conversation

Event Triggered

messageArrived

type: ActivityMessage

messageArrived

The messageArrived event is used to receive messages from other participants. Client needs to subscribe to this event.

Protocol

Websockets

Event Name

messageArrived

Source

Server

Input/Output Format

JSON

Event Payload (for ChatMessage)

{

"conversationId": "7g5639ju987g",

"type": "ChatMessage",

"requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6",

"timestamp": "2018-05-07T06:52:21.661Z",

"from": {

  "id": "abcdedf",

  "name": "Kashif Sohail"

},

"to": [

  {

    "id": "yferdt5",

    "name":"Alice"

  },

  {

    "id": "4ty678gu",

    "name":"Bob"

  }

],

"refId":"00923011234567",

"language":"en",

"text": "Hello, what is the status of my request",

"attachments": [],

}

Payload Parameters

conversationId: The id of conversation to which message is being sent

type: Type of message, see ChatMessage and ActivityMessae for details.

Event Triggered

sendMessage

The sendMessage event is used to publish messages to the conversation. Client needs to emit this event. Its format is similar to messageArrived.

Protocol

Websockets

Event Name

sendMessage

Source

Client

Input/Output Format

JSON

Event Payload (for ChatMessage)


{

"conversationId": "7g5639ju987g",

"type": "ChatMessage",

"requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6",

"timestamp": "2018-05-07T06:52:21.661Z",

"from": {

  "id": "abcdedf",

  "name": "Kashif Sohail"

},
"bot": {     "id":"bot",    "name":"bot",
    "type": "Rasa"},"input": "Hello, what is the status of my request",

"intents": [],
"entities": [],
"output": [{"name": "your request is in processing", "confidence": "0.98"}]

}

Payload Parameters

conversationId: The id of conversation to which message is being sent

type: Type of the message, i.e. botMessage 

from: The sender participant

input: the text content of the message.

Event Triggered


endConversation

The endConversation event is used to end an active conversation.

Protocol

Websockets

Event Name

endConversation

Source

Server

Input/Output Format

JSON

Event Payload

{

"conversationId": "7g5639ju987g",

"requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6",

"timestamp": "2018-05-07T06:52:21.661Z"

}

Payload Parameters

conversationId: Id of the conversation to end

Event Triggered


conversationList

This event is received when bot-connector registers with the chat-server, list of all the active conversations is received on conversationList event.

Protocol

Websockets

Event Name

conversationList

Source

Server

Input/Output Format

Array

Request Payload

[
  { "conversationId": "conversationId" },
  { "conversationId": "conversationId" }
]

Payload Parameters

convesationList: conversationlist contains object of conversation containing conversationId

Event Triggered