Customer Channel API

You can use Customer API to develop customer channel applications such as web widget, an SMS client, a Facebook, telegram, WhatsApp or similar connector for the Chat solution. The integration app may be embedded in a mobile or a web app.

Live Chat, Web Callback, and integration with Twilio (for SMS) is available out of the box.

Communication Flow

Customer API exchanges messages with the Chat server in the following sequence.

Integration Steps

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).
Initiate a chat request and get a sessionID for this connection.
Using the generated sessionId, call joinConveration for bidirectional communication.
Implement Send and Receive messages for sending and receiving messages from the Chat server.

On this page

Register Connector

You need to register you connector with Chat Server, in order to receive third-party messages which will be forwarded to customers directly via your connector like in case of SMS, any third party will request chat server to send campaign SMS to customer, the chat server will deliver this message along with customer contact number to the connector and the connector will send this message directly to the customer

When the client is connected, (socket received connect event), emit this event.

Protocol	Websockets
Event Name	registerConnector
Source	Client
Input/Output Format	JSON
Request Payload	CODE `{ "id": "sms", "name": "ExpertFlow SMS Connector", "channel": "sms" }`
Payload Parameters	id: Connector id used to identify in Chat Server, must be same as the channel name. name: Friendly name of the connector to display channel: Name of the channel
Event Triggered

Initiate a chat request

The Init REST API is used to initiate a chat request to the server. The client application sends a chat request (containing requesting customer information).

The server responds with a chat conversationId. This conversationId is used to join a room using Customer Channel API#joinConversation in order to send and receive chat messages.

Protocol	HTTP
URL	http://<FQDN>/api/customer/init
Content Type	Application/JSON
HTTP Method	POST
Input/Output Format	JSON
Request Body	Following are the allowed parameters in the Request body. firstName - customer first name lastName - (optional) customer last name Email - (optional) customer email address Phone - customer phone number Channel - any of web, fb, sms, twitter Language - language of the customer refId - normally phone number is used as refId, but it can be different Url - (optional) url of the current page, where customer gadget is loaded Comment -(optional) Subject : This is skill group. Used for MRE Queue. reqestId - (optional) GUID representing a unique chat request timestamp - in the ISO 8601 format
Sample Request Body	Sample Request body CODE `{ "firstName": "Kashif", "lastName":"" "email": "kashif@ef.com", "phone": "+1343122554", "channel": "web", "language": "en", "subject": "ADSL", "refId":"00923011234567", "comment":"Comment portion is optional", "url":"http://localhost:3001", "requestId": "99397bf7-a4fb-41c3-8292-a021b44262a6", "timestamp": "2018-05-07T06:52:21.661Z" }`
Request Parameters	Request parameters can be defined by developers, with at least one identifier parameter. Channel parameter is required.
HTTP Response	200: Success 500: Internal Server Error 503: Service Unavailable
Response Body	Returns the following parameters: conversationId - the ID that the client application should use to join the conversation Participant - customer identification as a participant for the conversation requestId - the same requestId the client submitted in the request Timestamp - the time in ISO 8601 format
Sample Response Body (in case of success)	Sample Response CODE `{ "conversationId": "5ae01d346c25be4319a9df95", "participant": { "id":"d346c25", "name":"Kashif" }, "requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6", "timestamp": "2018-05-07T06:52:21.661Z" }`
Sample Response Body (in case of failure)

Subject attribute in initiate chat API is used for Media Routing Engine (MRE) queue.

Send and Receive messages

Send messages	Sending a message is quite similar to receiving messages. To send a message, the client needs to emit sendMessage event with payload ChatMessage and ActivityMessage as per need.
Receive messages	Client needs to implement messageArrived event for the conversation. Payload for this event is a message. Message is the parent class of ChatMessage and ActivityMessage. The payload contains property type in the JSON root, which can be either ChatMessage or ActivityMessage.

Request Transcript

This request is used to get the chat transcript of a particular chat session. The transcript can be requested only after the chat session is ended. In the case of an ongoing chat session, the response will be Error 404.

Protocol	HTTP
URL	http://<FQDN>/api/customer/transcript/ID/Type
Content Type	Application/JSON
HTTP Method	GET
Input/Output Format	JSON
HTTP Request	-
Request Parameters	ID: The ID of the session Type: Type of Transcript (email or pdf)
HTTP Response	200: Success 404: Not found 500: Internal Server Error 503: Service Unavailable
Example Response	The response will be different based on different Type. For Type “pdf”, the response will be a pdf file For Type “email”, the response will be empty

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
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.
conversationInfo	The conversationInfo event is used to receive complete details of the conversation

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 `{ "conversationId": "5ae01d346c25be4319a9df95", "participant": { "id":"d346c25", "name":"Alice" }, "requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6", "timestamp": "2018-05-07T06:52:21.661Z" }`
Payload Parameters	conversationId: Id of the conversation to join id: Participant id, supplied in response of initiate chat request name: Name of participant to display in conversation
Event Triggered	messageArrived type: ActivityMessage activityType: greetings

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)	CODE `{ "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 ActivityMessage 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)	CODE `{ "conversationId": "7g5639ju987g", "type": "ChatMessage", "requestId":"99397bf7-a4fb-41c3-8292-a021b44262a6", "timestamp": "2018-05-07T06:52:21.661Z", "from": { "id": "abcdedf", "name": "Kashif Sohail" }, "text": "Hello, what is the status of my request", "language": "en", "tag": "", "attachments": [] }`
Payload Parameters	conversationId: The id of conversation to which message is being sent type: Type of the message, see ChatMessage and ActivityMessage for details from: The sender participant text: the text content of the message. tag : (optional) possible values are whisper and “”. Whisper messages are not sent to the customer.
Event Triggered

endConversation

The endConversation event is used to end an active conversation.

Protocol	Websockets
Event Name	endConversation
Source	Client
Input/Output Format	JSON
Event Payload	CODE `{ "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

conversationInfo

The conversationInfo event is received once customer joins the conversation.

Protocol	Websockets
Event Name	conversationInfo
Source	server
Input/Output Format	JSON
Request Payload	CODE `{ "conversation": "conversation", "messages": "[]", "participant": "[]", "role": "<string>" }`
Payload Parameters	conversation: conversation object containing conversation information messages: contains list of all the messages participant: list of participants role: role of the user in the conversation
Event Triggered

Schema

Schema defines the object and its properties that your client application can use to communicate with the server.

Object	Description
ChatMessage Object	Defines a text message that is exchanged between the server and client application.
ActivityMessage Object	Defines an activity message that is exchanged between the server and client application.
Participant object	Defines a bot or user account in the conversation.
Attachment Object	Array of Attachment objects that defines additional information to include in the message. Each attachment may be a media file (e.g., audio, video, image, file).
ActivityTypes	Types of activity messages

ChatMessage object

Defines a message that is exchanged between server and client.

Property	Type	Description
conversationId	String	The ID that identifies the conversation. The ID is unique per conversation. This conversationId is generated from the service side and sent to the client when the client request initiate chat
type	String	Type of message. ChatMessage in this case.
from	Participant	A Participant object that specifies the sender of the message
to	Participant[]	Array of Participant objects that specifies the recipients of the message. If the list is empty, the message will be broadcasted in the conversation.
text	String	Text of the message that is sent from user to bot or bot to user
refId	String	Account Id of the receiving account. (Phone no, in case of SMS)
attachments	Attachment[]	Array of Attachment objects that defines additional information to include in the message. Each attachment may be a media file (e.g., audio, video, image, file)

ActivityMessage object

Defines an activity message that is exchanged between server and client.

Property	Type	Description
conversationId	String	The ID that identifies the conversation. The ID is unique per conversation. This conversationId is generated from the service side and sent to the client when the client request initiate chat
type	String	Type of Message. ActivityMessage in this case
from	Participant	A Participant object that specifies the sender of the message
to	Participant[]	Array of Participant objects that specifies the recipients of the message. If the list is empty, the message will be broadcasted in the conversation.
activityType	String	Type of activity. One of these values: greetings, typing, participantAdded, participantRemoved, participantJoined, participantLeft, endOfConversation For details about activity types, see AcitivityTypes
info	Object	Notification data.

Participant object

Defines a bot or user account in the conversation.

Property	Type	Description
id	String	ID that uniquely identifies the bot or user in the conversation.
name	string	Name of the bot or user.

Attachment object

Array of Attachment objects that defines additional information to include in the message. Each attachment may be a media file (e.g., audio, video, image, file).

Property	Type	Description
type	String	The media type of the content in the attachment. For media files, set this property to known media types such as image/png, audio/wav, and video/mp4
name	String	Name of the attachment.
contentUrl	String	URL for the content of the attachment. For example, if the attachment is an image, set contentUrl to the URL that represents the location of the image. Supported protocols are: HTTP, HTTPS, File, and Data.
thumbnailUrl	String	URL to a thumbnail image that the channel can use if it supports using an alternative. For example, if you set type to application/word and set contentUrl to the location of the Word document, you might include a thumbnail image that represents the document. The widget could display the thumbnail image instead of the document. When the user clicks the image, the channel would open the document.

ActivityTypes

The following activity types are supported by the server.

ActivityType	Description
handOff	Indicates that request to assign an agent to the conversation is initiated
noAgentAvailable	Indicates that currently no agents are available
participantAdded	Indicates a participant added to the conversation
participantRemoved	Indicates a participant has removed from the conversation
participantJoined	Indicates a participant has joined the conversation
participantLeft	Indicates a participant has left the conversation