REST API for Chat in B2C Service

Get system messages

post

/engagement/api/agent/{fqSiteName}/v1/getMessages

This operation implements the polling get loop functionality for the agent. When the agent issues the 'Get system messages' request, the chat server tries to query for any system messages that might be available for that particular agent session. If system messages are available, the messages are packaged into the response and sent back to the agent. If no system messages are available at the time of the request, the chat server waits for a maximum of 30 seconds to see if any messages appear. If system messages become available, they are packaged and sent back to the agent. If no system messages become available, the server returns a collection that contains a single ChatGetTimeout message back to the agent.

The chat app should have a separate retrieval thread for handling a request to this endpoint. The agent app needs to be designed such that there is only one of these retrieval threads at any given time.

The following message types may be returned in the 'getResponseTypes' response field:

ChatActivitySignal - This message is used to inform the agent of the end user's interaction activity. The allowed values of the 'interaction activity' field are NONE, LISTENING and RESPONDING. The format of this message type is as follows:
{ "ChatActivitySignal": { "engagementId": 0L, "engagementIdString": "string", "clientId": 0L, "clientIdString":"string", "mode": "string", "sneakPreviewState": "string", "sneakPreviewInterval": 0, "sneakPreview": "string", "sneakPreviewFocus": false, "destinationId": 0L, "destinationIdString": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatConfigChangeNotification - This message is used to inform the agent application that the pool ID has changed for the site. This is usually a result of the chat server migrating to a newer version. It is imperative that the agent application take action on this message by using the new pool ID in all subsequent requests. The format of this message type is as follows:
{ "ChatConfigChangeNotification": { "name": "string", "value": "string", "domain": "string", "port":"string", "pool": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatDisconnectNotification - This message is used to inform the agent that a participant has disconnected from the engagement. The allowed values of the 'reason' field are NONE, AGENT_CONCLUDED, END_USER_CONCLUDED, QUEUE_TIMEOUT, IDLE_TIMEOUT, EJECTED, TRANSFERRED_TO_QUEUE, PARTICIPANT_LEFT and NO_AGENTS_AVAILABLE. The allowed values for the 'role' field are NONE, END_USER, CONFEREE, LEAD, MONITOR and TRANSIENT. The format of this message type is as follows:
{ "ChatDisconnectNotification": { "engagementId": 0L, "engagementIdString": "string", "clientId": 0L, "clientIdString":"string", "reason": "string", "role": "string", "destinationId": 0L, "destinationIdString": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatEngagementAssignment - This message is used to inform the agent that the chat server has routed an engagement to the agent. The allowed values of the 'requestSource' field are UNKNOWN, STANDARD, CUSTOM, PROACTIVE, SPROACTIVE, WS_API, CONDITIONAL_LINK, SYNDICATED_CONDITIONAL_LINK, REST_API, INLAY_CONDITIONAL_CHAT, INLAY_EMBEDDED_CHAT, INLAY_PROACTIVE_CHAT, MESSAGING_APPLE_BUSINESS_CHAT, MESSAGING_FACEBOOK_MESSENGER, MESSAGING_GOOGLE_BUSINESS_MESSAGES, MESSAGING_INSTAGRAM_DIRECT, MESSAGING_SMS, MESSAGING_TWITTER_DIRECT, MESSAGING_WECHAT, and MESSAGING_WHATSAPP. The allowed values of the 'initiationType' field are CONSUMER_STANDARD, CONSUMER_TARGETED and AGENT_INITIATED. The format of this message type is as follows:
{ "ChatEngagementAssignment": { "contactInfo": {"customFields":[], "firstName": "string", "lastName": "string","emailAddress": "string", "interfaceId": 0, "interfaceLanguageCode": "string", "contactId": 0L, "contactIdString": "string", "orgId": 0L, "orgIdString": "string", "sessionId": "string", "question":"string", "productId": 0L, "productIdString": "string", "categoryId": 0L, "categoryIdString": "string", "queueId": 0L, "queueIdString": "string", "browser": "string", "userAgent": "string", "ipAddress": "string", "operatingSystem": "string", "coBrowseEnabled":false, "visitorId": "string", "engagementEngineId": "string", "referrerUrl": "string", "engagementEngineSessionId": "string", "coBrowsePremiumSupported": 0, "mediaList":[{"type": "string", "environmentErrorList":["string"], "autoInitiate":false}], "estaraFsguid": "string"}, "agentInfo": {"clientId": 0L, "clientIdString": "string", "name": "string", "accountId": 0L, "accountIdString": "string", "profileId": 0l, "profileIdString": "string", "groupId": 0, "status": "string", "subTypeId": 0, "mediaList":[{"type": "string", "environmentErrorList":["string"], "autoInitiate":false}]}, "engagementId": 0L, "engagementIdString": "string", "engagementCreateTime": 0L, "engagementCreateTimeString": "string", "engagementFirstEngagedTime": 0L, "engagementFirstEngagedTimeString": "string", "secondsEngaged": 0L, "secondsEngagedString": "string", "queueId": 0L, "queueIdString": "string", "type": "string", "requestSource": "string", "incidentId": 0L, "incidentIdString": "string", "initiationType": "string", "asyncRequestId": "string", "consumerId": "string", "destinationId": 0L, "destinationIdString": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatEngagementParticipantAdded - This message is used to inform the agent that a participant has been added to the engagement. The allowed values of the 'role' field are NONE, END_USER, CONFEREE, LEAD, MONITOR and TRANSIENT. The format of this message type is as follows:
{ "ChatEngagementParticipantAdded": { "name": "string", "greeting": "string", "messageDataMap": null, "engagementId": 0L, "engagementIdString": "string", "clientId": 0L, "clientIdString": "string", "role":"string", "accountId": 0L, "accountIdString": "string", "virtualAgent": false, "destinationId": 0L, "destinationIdString": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatGetTimeout - This message is used to inform the agent application that no messages are available in the message queue. The format of this message type is as follows:
{ "ChatGetTimeout":{} }
ChatPostMessage - This message is used to inform the agent that the end user has posted a message. The format of this message type is as follows:
{ "ChatPostMessage": { "body": "string", "vaResponse": "string", "offTheRecord": false, "richText": false, "messageDataMap": null, "messageId": "string", "destinationId": 0L, "destinationIdString": "string", "destinationType": "string", "senderId": 0L, "senderIdString": "string", "senderType": "string", "messageType": "string", "visibility": "string", "createdTime": 0L, "createdTimeString": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
ChatSystemError - This message is used to inform the agent of any errors that have occurred while executing any of the agent operations. The format of this message type is as follows:
{ "ChatSystemError": { "errorCondition": "string", "text": "string", "type": "string" }

The following is the list of exception codes that can be returned from this operation:

ACCESS_DENIED - Authentication failed.
UNKNOWN_EXCEPTION - An unknown error has occurred.
INTERNAL_SERVER_ERROR - An error occurred within the core server.

Request

Supported Media Types

application/json; charset=utf-8

Path Parameters

fqSiteName: string

The fully qualified site name.

Header Parameters

X-AID: string

A header element containing the agent account identifier.
X-JSESSIONID: string

A header element containing the unique session identifier returned in the create automated agent session call.

The object containing the request information.

Root Schema : com.rightnow.chat.rest.agent_api.model.requests.v1.GetMessagesRequest

Type: object

Show Source

lastGetRequestMilliseconds(optional): integer(int64)

The time of the last get messages request in milliseconds.
sequenceNumber(optional): integer(int64)

The client application defined transaction sequence number.
startingSequenceNumber(optional): integer(int64)

The optional system message starting sequence number. If the value is omitted or null, all unsent messages will be returned in the response.
timeCreated(optional): integer(int64)

The time the request was created in milliseconds.
useContinuation(optional): boolean

Indicates whether continuations should be used in processing the request. If true, then continuations will be used in processing the request. The default value is: true.

{
    "properties":{
        "useContinuation":{
            "type":"boolean",
            "description":"Indicates whether continuations should be used in processing the request. If true, then continuations will be used in processing the request. The default value is: true."
        },
        "lastGetRequestMilliseconds":{
            "type":"integer",
            "format":"int64",
            "description":"The time of the last get messages request in milliseconds."
        },
        "startingSequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The optional system message starting sequence number.  If the value is omitted or null, all unsent messages will be returned in the response."
        },
        "timeCreated":{
            "type":"integer",
            "format":"int64",
            "description":"The time the request was created in milliseconds."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        }
    }
}

Response

Supported Media Types

application/json; charset=utf-8

200 Response

The request completed successfully.

Root Schema : com.rightnow.chat.rest.agent_api.model.responses.v1.GetMessagesResponse

Type: object

Show Source

clientId(optional): integer(int64)

The unique identifier of the agent client, created to identify the agent during this agent session.
clientIdString(optional): string

The unique identifier of the agent client in string format, created to identify the agent during this agent session.
clientSendTime(optional): integer(int64)

The time when the client request was received in yyyy-MM-dd'T'HH:mm:ssXXX format.
containsDisconnect(optional): boolean

Indicates whether there is a disconnect indicator. If true, a disconnect message is present in the list of returned system messages.
getResponseTypes(optional): array getResponseTypes

The list of system messages.
responseSentMilliseconds(optional): integer(int64)

The time of the response sent in milliseconds.
responseSentMillisecondsString(optional): string

The time of the response sent in milliseconds as a string.
sequenceNumber(optional): integer(int64)

The client application defined transaction sequence number.
sequenceNumberString(optional): string

The client application defined transaction sequence number as a string.
serviceFinishTime(optional): integer(int64)

The time when the chat server completed processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
serviceStartTime(optional): integer(int64)

The time when the chat server began processing the client request in yyyy-MM-dd'T'HH:mm:ssXXX format.
sessionId(optional): string

The unique identifier of the agent session.

{
    "properties":{
        "getResponseTypes":{
            "type":"array",
            "description":"The list of system messages.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.responses.v1.results.ChatSystemResult"
            }
        },
        "containsDisconnect":{
            "type":"boolean",
            "description":"Indicates whether there is a disconnect indicator. If true, a disconnect message is present in the list of returned system messages."
        },
        "responseSentMilliseconds":{
            "type":"integer",
            "format":"int64",
            "description":"The time of the response sent in milliseconds."
        },
        "responseSentMillisecondsString":{
            "type":"string",
            "description":"The time of the response sent in milliseconds as a string."
        },
        "clientSendTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the client request was received in yyyy-MM-dd&#39;T&#39;HH:mm:ssXXX format."
        },
        "serviceStartTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server began processing the client request in yyyy-MM-dd&#39;T&#39;HH:mm:ssXXX format."
        },
        "serviceFinishTime":{
            "type":"integer",
            "format":"int64",
            "description":"The time when the chat server completed processing the client request in yyyy-MM-dd&#39;T&#39;HH:mm:ssXXX format."
        },
        "sessionId":{
            "type":"string",
            "description":"The unique identifier of the agent session."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the agent client, created to identify the agent during this agent session."
        },
        "clientIdString":{
            "type":"string",
            "description":"The unique identifier of the agent client in string format, created to identify the agent during this agent session."
        },
        "sequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The client application defined transaction sequence number."
        },
        "sequenceNumberString":{
            "type":"string",
            "description":"The client application defined transaction sequence number as a string."
        }
    }
}

Nested Schema : getResponseTypes

Type: array

The list of system messages.

Show Source

Array of:

{
    "type":"array",
    "description":"The list of system messages.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.agent_api.model.responses.v1.results.ChatSystemResult"
    }
}

400 Response

The validation of the request object failed.

Root Schema : schema

Type: object

403 Response

The agent session identifier is unknown.

Root Schema : schema

Type: object

404 Response

The resource was not found.

Root Schema : schema

Type: object

500 Response

An error occurred in the chat server while processing the request.

Root Schema : schema

Type: object

Examples

The following example shows how to retrieve system messages.

cURL Command Example

curl -X POST https://chat_rest_server_domain.com/engagement/api/agent/day001_221100_sql_001h/v1/getMessages?pool=297:1 -H 'Content-Type: application/json; charset=UTF-8' -H 'X-JSESSIONID: node01h8m13tljpm7ns8nayp0pid91' -d ' -H 'X-AID: 12' {"timeCreated" :160444022000, "sequenceNumber" : 11}'

Request Body Example

The following shows an example of the request body in JSON format.

{
  "timeCreated" :160444022000,
  "sequenceNumber" : 11
}

Response Header Example

The following shows an example of the response header.

Status: 200 OK
Content-Type: application/json;charset=utf-8

Response Body Example

The following shows an example of the response body in JSON format.

{
  "clientId": 48,
  "clientIdString": "48",
  "sequenceNumber": 11,
  "sequenceNumberString": "11",
  "sessionId": "node01eirr916pfjman1bycclscdwl1",
  "clientSendTime": "null",
  "responseSentMilliseconds": 1653509828320,
  "responseSentMillisecondsString": "1653509828320",
  "serviceStartTime": "2022-05-25T20:17:08.315Z",
  "serviceFinishTime": "2022-05-25T20:17:08.323Z",
  "containsDisconnect": false,
  "getResponseTypes": [
  {
    "ChatGetTimeout": {}
  }
  ]
}