Chatbot API

Use Chatbot API to integrate any chatbot with Hybrid Chat. Connector for Rasa, DialogFlow, and Articulate bot is available out of the box. Integration with other chatbots may also be developed using the same Chatbot API.

Integration Steps

Establish a socketIO connection with the Chat server on the 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 where the Chat socket server is listening on.
By default, the Chat server listens on 8080 (HTTP) or 443 (HTTPS).
Register bot-connector by emitting registerBot event to Chat Server
Subscribe to initConversation, once the new conversation is initiated, the Chat Server will notify the bot-connector on initConversation. Join the conversation by emitting joinConveration for bidirectional communication.
Implement sendMessage and messageArrived for sending and receiving messages from the Chat server.
Subscribe to conversationList event for failover support. Once the failover happens the Chat Server sends a list of all active conversations to the bot-connector.
Subscribe to updateTracker in order to update the tracker object of Rasa bot for chosen suggestion by an agent.

Events

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

Event Name	Description
registerBot	The registerBot event is used to register the bot-connector as a participant with the chat-server.
initConversation	The initConversation is received once the 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. Bot-connector needs to subscribe to this event.
sendMessage	The sendMessage event is used to send a message to a conversation. Bot-connector needs to emit this event.
endConversation	The endConversation is received when a conversation is ended.
conversationList	The conversationList event is used to receive all conversations list, this is specific to the bot-connector.
updateTracker	The updateTracker event is used to update the EF's custom Rasa tracker with the chosen Bot suggestion.

registerBot

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

Protocol	Websockets
Event Name	registerBot
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "id": "bot", "name": "EF bot", "type": "Rasa" }`
Payload Parameters	id: the primary bot is always bot name: Name of the bot type: Type of the bot
Event Triggered

initConversation

The initConversation event is received once the new conversation is started.

Protocol	Websockets
Event Name	initConversation
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "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	CODE `{ "botId":"bot" "conversationId": "5ae01d346c25be4319a9df95", "participant": { "id":"bot", "name":"bot", "type": "Rasa" }, "timestamp": "2018-05-07T06:52:21.661Z" }`
Payload Parameters	botId: Id of the bot conversationId: Id of the conversation to join participant.id: Id of the bot participant.name: Name of participant to display in conversation participant.type: type of the bot
Event Triggered	messageArrived type: ActivityMessage activityType: participantJoined

messageArrived

The messageArrived event is used to receive messages from other participants. Bot-connector needs to subscribe to this event.

Protocol	Websockets
Event Name	messageArrived
Source	Server
Input/Output Format	JSON
Event Payload (for ChatMessage)	CODE { "conversationId": "7g5639ju987g", "messageId":"LeIunRQ_L", "messageType":"ChatMessage", "timestamp": "2018-05-07T06:52:21.661Z", "from": { "id":"maxP8DcLXI", "name":"Andreas Stuber", "firstName":"Andreas", "lastName":"Stuber", "type":"Customer" }, "to": [ { "id": "yferdt5", "name":"Alice" }, { "id": "4ty678gu", "name":"Bob" } ], "language":"en", "channel":"web", "refId":"00923011234567", "text": "Hello, what is the status of my request", "tag":"", "processByBot":false, "attachments": [], "buttons":[], "structuredData":{}, "botResponseType":"simple" }
Payload Parameters	conversationId: The id of conversation to which message is being sent messageId: The id of message to differentiate the message messageType: Type of message, see ChatMessage and ActivityMessae for details. from: Sender of the message to: Receiver of the message language: Language of message channel: The channel used by customer text: Customer message
Event Triggered

sendMessage

The sendMessage event is used to publish messages to the conversation. Bot-connector 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)	CODE { "conversationId": "7g5639ju987g", "messageId":"LeIunRQ_L", "type": "ChatMessage", "from": { "id":"maxP8DcLXI", "name":"Andreas Stuber", "firstName":"Andreas", "lastName":"Stuber", "type":"Customer" }, "bot": { "id":"bot", "name":"bot", "type": "Rasa" }, "timestamp": "2018-05-07T06:52:21.661Z", "input": "Hello, what is the status of my request", "attachments": [], "intents": [{"name":"intent_name","confidence":0.9999716282}], "entities": [], "output": [ { "name": "your request is in processing", "confidence": "0.98", "data": "Structure message object" } ], "status":200 }
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 received when a conversation is ended.

Protocol	Websockets
Event Name	endConversation
Source	Server
Input/Output Format	JSON
Event Payload	CODE `{ "conversationId": "7g5639ju987g" }`
Payload Parameters	conversationId: Id of the ended conversation
Event Triggered

conversationList

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

Protocol	Websockets
Event Name	conversationList
Source	Server
Input/Output Format	Array
Request Payload	CODE `[ { "conversationId": "conversationId" }, { "conversationId": "conversationId" } ]`
Payload Parameters	convesationList: conversationlist contains objects of the conversation containing conversationId
Event Triggered

updateTracker

This event is received when the agent gadget chooses one of the suggestions from the list or in the case of Bot to Customer mode first suggestion is sent to updateTracker.

Protocol	Websockets
Event Name	updateTracker
Source	Server
Input/Output Format	Array
Request Payload	CODE `{ "conversationId": "conversationId", "actionName": "utter_greet", "actionConfidence": 0.86, "actionPolicy": "policy_0_MemoizationPolicy", "text": "Hello How may I help you" "structuredData": "Structure message object" }`
Payload Parameters	conversationId: Id of the conversation to update. It also acts as an ID of the Rasa Tracker actionName: Name of the action chosen by the agent actionConfidence: Confidence of the chosen action actionPolicy: Policy of the chosen action text: Utterance of bot (Text of the action) structuredData: Structure message data including buttons, image,
Event Triggered