Customer 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

  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. Initiate a chat request and get a sessionID for this connection.
  3. Using the generated sessionId, call joinConveration for bidirectional communication.
  4. 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

{

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

name - full customer 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
{
"name": "Kashif Sohail",
"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
{

"conversationId": "5ae01d346c25be4319a9df95",

"participant": {

  "id":"d346c25",

  "name":"Kashif Sohail"

},

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

Get loggedIn Agents count

This REST API is used to get the logged in agents count.

Protocol

HTTP

URL

http://<FQDN>/api/External/agents/list?query=count

Content Type

Application/JSON

HTTP Method

GET

Input/Output Format

JSON

Request Parameters

only request parameter is query=count

HTTP Response

200: Success

500: Internal Server Error

503: Service Unavailable

Response Body

Returns the following parameters:

count: count of the logged in agents

Sample Response Body

(in case of success)

Sample Response
{
"count": "0"
}

Sample Response Body

(in case of failure)


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

conversationInfoThe 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

{

"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)

{

"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"

},

"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

{

"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

{
"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 most common type of activity is greetings when a conversation is initiated, the client receives greetings from the server.

The following activity types are supported by the server.

ActivityType

Description

greetings

The greeting message, when a conversation is initiated, the server sends a greeting message to the client. This message is configurable and can be changed in the admin panel.

typing

Indicates that the user or bot on the other end of the conversation is compiling a response.

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

endOfConversation

Indicates the end of a conversation.