1. Overview

The CBA Live Assist Chat Server provides a means for an application to mediate chat sessions between the end user of the application and an agent within CBA Live Assist.

An application can determine the availability of an agent, and make chat requests. Both of these operations can be constrained to an agent skill.

Once a chat request has been submitted, the session is monitored by the application. The application then acts as a relay between its end users and the CBA Live Assist agent via the service.

Notes

Replace REGION with na1 (for North America), eu1 (for EMEA and South America) or ap1 (for APAC) depending on your CRM region.

  • All operations specify an account ID as part of the resource path. This is the Live Assist account ID.

  • The service requires an authorization header to be provided in each request. The value of the token in the header must match that configured for the service through the Live Assist Admin Portal.

For further details see https://support.liveassistfor365.com/hc/en-us/articles/360062299733-Chat-Server-API

1.1. Version information

Version : 0.1.0

1.2. URI scheme

Schemes : HTTPS

2. Paths

2.1. GET /{account}/availability

2.1.1. Description

Gets information on availability of CBA Live Assist agents. Note; the use of the skill query is deprecated. Please use the skill based availability operation.

2.1.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Query

skill
optional

The skill requested. If supplied, the query is constrained to those agent that possess that skill. Note that using a skill that is unknown to the system will result in an error. Note; the use of the skill query is deprecated. Please use the skill based availability operation.

string

2.1.3. Responses

HTTP Code Description Schema

200

Response to an availability request.

Availability

400

The values of the parameters to the operation were not usable.

No Content

2.1.4. Produces

  • application/json

2.2. GET /{account}/skills

2.2.1. Description

For each given skill, determines the availability of CBA Live Assist agents with that skill.

2.2.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Query

name
required

The skill(s) requested. The query is constrained to those agent that possess that skill.

< string > array(multi)

2.2.3. Responses

HTTP Code Description Schema

200

Response to a skills availability request.

SkillsAvailability

400

The values of the parameters to the operation were not usable.

No Content

2.2.4. Produces

  • application/json

2.3. GET /{account}/skills/{skill}

2.3.1. Description

For a given skill, gets information on availability of CBA Live Assist agents with that skill.

2.3.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

skill
required

The skill requested. The query is constrained to those agent that possess that skill.

string

2.3.3. Responses

HTTP Code Description Schema

200

Response to a skill availability request.

SkillAvailability

400

The values of the parameters to the operation were not usable.

No Content

2.3.4. Produces

  • application/json

2.4. GET /{account}/availableCapacity

2.4.1. Description

Gets information on the number of free chat places available at the current time. This is the number of new chats that could be accepted by agents now. Note; the use of this endpoint is deprecated. Please use the availability operation or the skill based availability operations.

2.4.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Query

skill
optional

The skill requested. If supplied, the query is constrained to those agent that possess that skill. Note that using a skill that is unknown to the system will result in an error. Note; the use of the skill query is deprecated. Please use the skill based availability operation.

string

2.4.3. Responses

HTTP Code Description Schema

200

Response to an availableCapacity request.

AvailableCapacity

400

The values of the parameters to the operation were not usable.

No Content

2.4.4. Produces

  • application/json

2.5. POST /{account}/sessions

2.5.1. Description

Requests a Live Assist chat session.

2.5.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Body

chatSpec
required

A specification of the chat required.

ChatSpec

2.5.3. Responses

HTTP Code Description Schema

201

Response to a chat request.

ChatInfo

400

The values of the parameters to the operation were not usable.

No Content

2.5.4. Consumes

  • application/json

2.5.5. Produces

  • application/json

2.6. GET /{account}/sessions/{sessionId}

2.6.1. Description

Once underway, a chat must be monitored and is the primary means through which a chat is driven. Monitoring a chat involves processing a stream of events over the life of the chat session. Events include messages submitted by either party, in particular the messages submitted by the agent to be relayed to the visitor, and state events such as the end of a chat.

Monitoring can be performed in one of two ways: polling and through a websocket.

This operation polls a chat session. When using this method, polling should be performed at a timely frequency, subject to processing load considerations. This is key to a smooth experience for the visitor, for example it will dictate how quickly visitors will see messages submitted by an agent.

An alternative means of monitoring chats is through websockets. The later section Websocket Chat Monitoring provides details of monitoring without polling.

The response to this request will immediately return with information about the chat. An application should stop polling once an end event has been processed.

2.6.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

sessionId
required

Chat sessionId (as returned by a successful chat request).

string

Query

state
required

State data. This must be set to the value returned by the last call to this operation, or that returned by POST /{account}/sessions if this is the first use.

string

2.6.3. Responses

HTTP Code Description Schema

200

The result of a chat poll, data related to the chat.

ChatInformation

400

The values of the parameters to the operation were not usable.

No Content

2.6.4. Produces

  • application/json

2.7. POST /{account}/sessions/{sessionId}/line

2.7.1. Description

Sends a line of chat text on behalf of the visitor.

2.7.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

sessionId
required

Chat sessionId (as returned by a successful chat request).

string

Body

line
required

A text line to be submitted.

Text

2.7.3. Responses

HTTP Code Description Schema

200

Text line has been added.

No Content

400

The values of the parameters to the operation were not usable.

No Content

2.8. POST /{account}/sessions/{sessionId}/end

2.8.1. Description

Ends a chat session.

2.8.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

sessionId
required

Chat sessionId (as returned by a successful chat request).

string

2.8.3. Responses

HTTP Code Description Schema

200

The chat end request has been submitted.

No Content

400

The values of the parameters to the operation were not usable.

No Content

2.9. PUT /{account}/sessions/{sessionId}/visitorTyping

2.9.1. Description

Sets the typing state of the visitor.

2.9.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

sessionId
required

Chat sessionId (as returned by a successful chat request).

string

Body

visitorTyping
required

The typing state of the visitor.

VisitorTyping

2.9.3. Responses

HTTP Code Description Schema

204

The visitor typing state has been set.

No Content

400

The values of the parameters to the operation were not usable.

No Content

3. Websocket Chat Monitoring

In addition to GET /{account}/sessions/{sessionId}, which can be used as the basis of a regular polling strategy for chat monitoring, the Chat Service offers a websocket interface for chat monitoring.

Websocket based chat monitoring frees the application from having to perform regular polling.

3.1. wss://<base>/${account}/sessions/${sessionId}/subscribe

3.1.1. Description

A websocket endpoint used to monitor a chat.

3.1.2. Parameters

Type Name Description Schema

Header

Authorization
required

Authorization token configured for the service.

string

Path

account
required

Live Assist account ID.

string

Path

sessionId
required

Chat sessionId (as returned by a successful chat request).

string

Query

state
required

State data, this must be set to: the value returned within the ChatInformation message through a previous websocket connection; or the state value within the ChatInformation returned by GET /{account}/sessions/{sessionId}; or the value within ChatInfo returned by POST /{account}/sessions (see below).

string

3.1.3. Messages

Direction Description Schema

From service

Information about the chat

ChatInformation

When information regarding the chat is available, the service will send a ChatInformation message. This is the same data returned by GET /{account}/sessions/{sessionId} and should be processed in the same way.

3.1.4. Websocket Closing

A websocket connection can immediately be closed by the service if it detects unauthorized access (close status 1008) or bad sessionId/state data (close status 1007).

When the application has not closed the websocket, and a close event with a status other than the above is detected, the closure should be considered abnormal (see below).

3.1.5. State

A chat gives rise to a sequence of events that grows as the chat progresses. When monitoring a chat, the state data contains a marker indicating a position in the sequence. Supplying a state value causes all events since the event indicated by that value to be returned, together with an updated state value reflecting an updated position within the sequence based on the events returned.

All forms of chat monitoring (explicit polling or websocket based), require a state value on which to base the event collation. The different cases are described.

An initial state value is returned by the chat request operation POST /{account}/sessions and must be the first value used in subsequent monitoring requests.

Explicit polling

For GET /{account}/sessions/{sessionId}, the normal use case is for the initial call to use the initial state value returned the chat request operation. Subsequent calls will then use the state value returned in the previous call.

Websocket based monitoring

Here, the normal use case is to open the websocket with the state value returned by the chat request operation. In normal circumstances this is all that would be needed.

However, if a situation arises where the service resource handling the websocket is no longer able to do so, the websocket may close abnormally even though the chat may still be progressing.

To cater for this situation, the latest value of the state (continually updated by the ChatInformation messages written by the service) should be maintained. Then, should an abnormal closing of the websocket occur, the latest state value can be used to re-open a websocket connection, monitoring from the point just before the anomaly.

The application should close the websocket when an end state is processed.

4. Definitions

4.1. Availability

Information about the availability of agents to handle chats.

Name Description Schema

availability
required

Whether or not at least one agent (with the required skill if specified) is online. Whether or not an agent is immediately available to take a chat can be inferred by estimatedWaitTime or availableCapacity (assuming availability is true).

boolean

estimatedWaitTime
optional

Only when availability is true. Unless where specified, the estimated number of seconds before a chat can begin.

-1 - The system is unable to predict the wait time.

0 - An agent is immediately available to accept the chat.

integer

availableCapacity
optional

Only when availability is true. The number of free chat places available at the current time.

integer

4.2. AvailableCapacity

Information on the number of free chat places available at the current time.

Name Description Schema

availableCapacity
required

The number of free chat places available at the current time.

integer

4.3. ChatData

Chat monitoring data.

Name Description Schema

events
optional

A list of events, possibly empty, that consists of the events that have occurred since the last poll.

< events > array

info
optional

This is information related to the chat, which may change over the life of the chat.

info

events

Name Description Schema

type
required

The type of event, defines the further properties available. State events describe the state of the conversation, line events represent messages that have been submitted by any party within the chat.

enum (state, line)

time
required

The date and time (ISO-8601, with timezone info) at which the event occurred with respect to the chat server.

string

state
optional

Only for state events.

waiting - the visitor is waiting for an agent to answer the chat request.

chatting - the visitor is chatting with an agent.

ended - the chat has ended (note that this will occur whether the visitor or the agent ended the chat).

enum (waiting, chatting, ended)

text
optional

Only for line events, the text of the message.

string

textType
optional

Only for line events, the type of the text of the message.

plain - the message text is in plain text.

html - the message text contains html.

enum (plain, html)

source
optional

Only for line events, indicates the party that submitted the message.

system - this is a message from the chat system (as opposed to any of the participants).

agent - a message submitted by the agent.

visitor - a message submitted by the visitor.

enum (system, agent, visitor)

sentBy
optional

Only for line events, the name of the party that submitted the message. Note that where the source of the message is system, the value of this property may be descriptive and not reflect the name of an agent.

string

info

Name Description Schema

agentName
required

The name of the agent with whom the visitor is chatting.

string

isAgentTyping
required

Will be true if the agent is currently typing and false otherwise.

boolean

lastUpdate
required

The last time that any request was sent to the chat session.

string

chatTimeout
required

The time in seconds from the last update time, after which the chat times out and must be updated again before this timeout.

integer

startTime
required

The time (ISO-8601, with timezone info) the chat started (request was made).

string

4.4. ChatInfo

Information about a requested chat.

Name Description Schema

sessionId
required

The ID for the chat session. This is to be used in subsequent operations relating to this chat.

string

contextId
required

This can be used to associate context data with this chat.

string

state
required

The initial state of the chat. This must be the initial value used in chat monitoring operations.

string

4.5. ChatInformation

Chat monitoring data.

Name Description Schema

data
required

The actual data.

ChatData

state
required

State data. This must be retained and used in further API calls for this chat.

string

4.6. ChatSpec

The specification of the chat to start.

Name Description Schema

skill
optional

If present, the property skill expresses a desire for an agent with a specific skill. Note that using a skill that is unknown to the system will result in the request being routed to any available agent, otherwise if no agent with the given skill is available an error will occur (availability can be used to prevent this).

string

transcript
optional

A transcript object recording text lines designated as having occurred before the agent chat began. If omitted, no transcript will be submitted.

< TranscriptLine > array

visitorName
optional

The name to give the visitor/end user. If omitted, no visitor name will be set and the non-specific default name will apply.

string

language
optional

If present, the property language expresses a desire for the chat to be conducted in the specified language. If omitted, the language will default to English. The language specification must be of the form <lang>-<country>. Support for the specified language must have been configured in the Live Assist account, otherwise Live Assist will use the default language. See List of Supported Languages for the list of supported languages and their values.

string

4.7. SkillAvailability

Information about the availability of agents to handle chats.

Name Description Schema

availability
required

Whether or not at least one agent (with the required skill if specified) is online. Whether or not an agent is immediately available to take a chat can be inferred by estimatedWaitTime or availableCapacity (assuming availability is true).

boolean

estimatedWaitTime
optional

Only when availability is true. Unless where specified, the estimated number of seconds before a chat can begin.

-1 - The system is unable to predict the wait time.

0 - An agent is immediately available to accept the chat.

integer

availableCapacity
optional

Only when availability is true. The number of free chat places available at the current time.

integer

4.8. SkillsAvailability

Information about the availability of agents with specific skills to handle chats. Each entry maps a skill name to the availability information for that skill.

Type : < string, SkillAvailability > map

4.9. Text

A line of text (message).

Name Description Schema

line
required

The line of text.

string

4.10. TranscriptLine

A line of transcript.

Name Description Schema

timestamp
required

The time (ISO-8601, with timezone info) the line was entered. Eg "2018-07-19T04:35:39.665-04:00", "2018-07-19T04:35:39+04:30", "2018-07-19T04:35:39.665Z", "2018-07-19T04:35:39Z".

string

isBot
optional

Indicates if the line was sourced from the application. If omitted or anything other than true, it will be taken that the line was sourced from the visitor.
Default : false

boolean

srcName
required

A string representing a name for the source of the line (eg ‘shopper’ or ‘shoppingApp’).

string

line
required

A string representing the line of text entered.

string

4.11. VisitorTyping

The typing state of the visitor.

Name Description Schema

visitorTyping
required

True if the visitor is typing, false if not.

boolean

5. Chat Server and Context Data

The Live Assist Chat Server can be used in conjunction with the Live Assist Context Service for submitting data about the chat being handled.

5.1. Context Data Service

The Context Data service provides an HTTP API through which context data can be POSTed.

5.1.1. Context Data Server URL discovery

A description of the service, together with the steps to follow to discover the URL to be used, can be found in the Context Service Developer Guide (for the purposes of this article, please ignore references to the BOT Escalation SDKs; what is relevant is the URL discovery and the supported data attributes).

5.1.2. Constructing the Context Data to submit

In the following discussion, let’s denote the URL by <url> and the context data by <data>. With reference to the above mentioned guide, an example of <data> might be

{
  customer: {
    id: {
      value: "ACustomerId",
      isAsserted: true
    }
  }
}

As described, the context data is submitted in the form of a signed JWT. Once the URL and the data have been determined, the signing and POSTing of the data can be done.

5.2. Constructing the Information to POST

5.2.1. Construct the JWT Payload

First, the payload for the JWT is constructed. This is of the form

{
  contextId: <contextId>,
  contextData: <data>
}

where <data> is as already described, and <contextId> is an identifier uniquely associated with a chat session. It is through the <contextId> identifier that the Chat Service and the Context Data Service work in conjunction.

When a chat session is requested through the Chat Service (POST /{account}/sessions), a successful response will return, in addition to the sessionId and state strings, a contextId string. It is this value that should be used as <contextId>.

5.2.2. Signing the Payload

The constructed payload is now signed using the private key corresponding to the public key configured through the Admin Portal. How this is done will depend on your implementation language and any libraries used. As examples, if you are implementing your client in Java, you might use the Jose4j library. If you are implementing in Node.js, you might use the jws package.

5.2.3. Construct the entity to POST

However the information is signed, the product is a string representation of the JWT, let’s denote this <jwt>. It is this string that forms part of the entity that is POSTed to the Context Data Service. The entity to POST, let’s denote this <entity>, is JSON of the form

{
  accountId: <accountId>,
  contextData: <jwt>
}

where <accountId> is the same as that used when interacting with the Chat Service.

5.3. Posting the Entity

The constructed entity must now be POSTed to the Context Service, using the form

  POST <url> (<entity>)

where <entity> is the body of the request.

5.4. Flow outline

Putting all the above together, the flow to create a chat session with authenticated context data is as follows:

  1. Discover the URL to use → <url>, and decide how and what data attributes to define and submit (this is mainly a pre-coding exercise). See Context Data Server URL discovery.

  2. Request a chat through the Chat Service → <contextId>. See POST /{account}/sessions.

  3. Construct <data> as required → <data>, See Constructing the Context Data to submit.

  4. Construct the JWT payload (<contextId>, <data>) → <payload>. See Construct the JWT Payload.

  5. Sign the payload with your private key (<payload>, <key>) → <jwt>. See Signing the Payload.

  6. Construct the entity to be POSTed (<accountId>, <jwt>) → <entity>. See Construct the entity to POST.

  7. POST the entity using the designated URL (<url>, <entity>). See Posting the Entity