REST API for Chat in B2C Service

Get system messages

post

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

This operation implements the polling get loop functionality for the client. When the client issues the 'Get system messages' request, the chat server tries to query for any system messages that might be available for that particular chat engagement. If system messages are available, the messages are packaged into the response and sent back to the client. 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 client. If no system messages become available, the server returns an empty collection back to the client.

The chat app should have a separate retrieval thread for handling a request to this endpoint. The chat 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 'systemMessages' response field:

RNEngagementActivityChangedMessage - This message is used to inform the end user of the agent's interaction activity. The allowed values of the interaction activity are NONE, AWAY, LISTENING, RESEARCHING, and RESPONDING. The format of this message type is as follows:
{ "messageName": "RNEngagementActivityChangedMessage", "clientId": 0L, "clientIdString": "string", "mode": "string", "engagementId": 0L, "engagementIdString": "string", "sneakPreviewState": "string", "sneakPreviewInterval": 0L, "sneakPreviewIntervalString": "string", "sneakPreview": "string", "sneakPreviewFocus": "boolean", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementConcludedMessage - This message is used to inform the end user that the agent has concluded the chat engagement. The format of this message type is as follows:
{ "messageName": "RNEngagementConcludedMessage", "reason": "string", "role": "string", "contactId": 0L, "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementConfigurationChangedMessage - This message is used to inform the client 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 client 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:
{ "messageName": "RNEngagementConfigurationChangedMessage", "name": "string", "domain": "string", "port": "string", "pool": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementConsumerErrorOccurredMessage - This message is used to inform the client application that an error has occurred within the chat server for the current chat engagement. The text describing the error condition is returned in this message. The format of this message type is as follows:
{ "messageName": "RNEngagementConsumerErrorOccurredMessage", "errorType": "string", "errorCode": "string", "errorText": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementMessagePostedMessage - This message contains the message that the agent sent to the end user. This message text is part of the chat engagement transcript. The format of this message type is as follows:
{ "messageName": "RNEngagementMessagePostedMessage", "body": "string", "clientId": 0L, "clientIdString": "string", "messageId": "string", "richText": false, "messageDataMap": null, "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementParticipantAddedMessage - This message informs the end user that another agent has joined the chat engagement in either the conference or transfer process. The format of this message type is as follows:
{ "messageName": "RNEngagementParticipantAddedMessage", "name": "string", "greeting": "string", "messageDataMap": null, "clientId": 0L, "clientIdString": "string", "role": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementParticipantConnectionStateChangedMessage - This message is used to inform the client application that the participant in the engagement with the specified role has had a connection state change to one of the following values: NONE, ABSENT, ACTIVE, or DISCONNECTED. The format of this message type is as follows:
{ "messageName": "RNEngagementParticipantConnectionStateChangedMessage", "role": "string", "clientId": 0L, "clientIdString": "string", "connectionState": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementParticipantLeftMessage - This message is used to inform the client application that the participant in the chat engagement with the specified role is no longer a participant. The format of this message type is as follows:
{ "messageName": "RNEngagementParticipantLeftMessage", "clientId": 0L, "clientIdString": "string", "disconnectReason": "string", "role": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementRoleChangedMessage - This message is used to inform the client application that the agent with the specified client ID is now the lead agent in the chat engagement. This message is usually the result of the chat engagement being transferred to another agent. The format of this message type is as follows:
{ "messageName": "RNEngagementRoleChangedMessage", "leadClientId": 0L, "leadClientIdString": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementWaitInformationChangedMessage - This message is used to inform the end user of their current position in the queue and the expected wait time before being assigned to an agent. The format of this message type is as follows:
{ "messageName": "RNEngagementWaitInformationChangedMessage", "position": 0L, "positionString": "string", "expectedWaitTimeSeconds": 0L, "expectedWaitTimeSecondsString": "string", "averageWaitTimeSeconds": 0L, "averageWaitTimeSecondsString": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementPropertyChangedMessage - This message is used to inform the end user of a property change on the engagement. The property map keys are "ACCOUNT_ID" or "CONTACT_ID". The format of this message type is as follows:
{ "messageName": "RNEngagementPropertyChangedMessage", "propertyMap": {"key", "value"}, "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }
RNEngagementSurveyInformationMessage
{ "messageName": "RNEngagementSurveyInformationMessage", "sendSurveyId": 0, "sendSurveyAuth": "string", "sendSurveyDelay": 0, "completedSurveyId": 0, "completedSurveyAuth": "string", "cancelledSurveyId": 0, "cancelledSurveyAuth": "string", "createdTime": "string", "sequenceNumber": 0L, "sequenceNumberString": "string" }

Note: The format for 'createdTime' is yyyy-MM-dd'T'HH:mm:ssXXX.

Request

Supported Media Types

application/json; charset=utf-8

Path Parameters

fqSiteName: string

The name of the site returned by the call to establish a session.

Query Parameters

pool: string

The pool ID specified in the Establish Sessions response or provided in an RNEngagementConfigurationChangedMessage system message.

Header Parameters

SessionId: string

The unique identifier of the consumer session.

The object containing the request information.

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

Type: object

Show Source

clientRequestTime(optional): string

The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
clientTransactionId(optional): integer(int64)

The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses.
startingSequenceNumber(optional): integer(int64)

The optional system message starting sequence number. If a value is present in the request, the messages returned in the response will start with this sequence number. If the value is omitted or null, all unsent messages will be returned in the response.

{
    "properties":{
        "clientRequestTime":{
            "type":"string",
            "description":"The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientTransactionId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses."
        },
        "startingSequenceNumber":{
            "type":"integer",
            "format":"int64",
            "description":"The optional system message starting sequence number.  If a value is present in the request, the messages returned in the response will start with this sequence number.  If the value is omitted or null, all unsent messages will be returned in the response."
        }
    }
}

Response

Supported Media Types

application/json; charset=utf-8

200 Response

The request completed successfully.

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

Type: object

Show Source

clientId(optional): integer(int64)

The unique identifier of the client.
clientIdString(optional): string

The unique identifier of the client as a String.
clientRequestTime(optional): string

The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
clientTransactionId(optional): integer(int64)

The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses.
clientTransactionIdString(optional): string

The unique identifier of the client transaction as a String.
errorMessages(optional): array errorMessages

The list of Errors.
serviceFinishTime(optional): string

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

The time when the request processing started in yyyy-MM-dd'T'HH:mm:ssXXX format.
systemMessages(optional): array systemMessages

The list of system messages from the chat cloud.

{
    "properties":{
        "errorMessages":{
            "type":"array",
            "description":"The list of Errors.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.consumer_api.model.messages.v1.RNEngagementConsumerErrorOccurredMessage"
            }
        },
        "systemMessages":{
            "type":"array",
            "description":"The list of system messages from the chat cloud.",
            "items":{
                "$ref":"#/definitions/com.rightnow.chat.rest.common.model.messages.v1.EngagementBaseSystemMessage"
            }
        },
        "clientRequestTime":{
            "type":"string",
            "description":"The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientTransactionId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses."
        },
        "clientTransactionIdString":{
            "type":"string",
            "description":"The unique identifier of the client transaction as a String."
        },
        "serviceStartTime":{
            "type":"string",
            "description":"The time when the request processing started in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceFinishTime":{
            "type":"string",
            "description":"The time when the request processing completed in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client."
        },
        "clientIdString":{
            "type":"string",
            "description":"The unique identifier of the client as a String."
        }
    }
}

Nested Schema : errorMessages

Type: array

The list of Errors.

Show Source

Array of: object com.rightnow.chat.rest.consumer_api.model.messages.v1.RNEngagementConsumerErrorOccurredMessage

{
    "type":"array",
    "description":"The list of Errors.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.consumer_api.model.messages.v1.RNEngagementConsumerErrorOccurredMessage"
    }
}

Nested Schema : systemMessages

Type: array

The list of system messages from the chat cloud.

Show Source

Array of: object com.rightnow.chat.rest.common.model.messages.v1.EngagementBaseSystemMessage

{
    "type":"array",
    "description":"The list of system messages from the chat cloud.",
    "items":{
        "$ref":"#/definitions/com.rightnow.chat.rest.common.model.messages.v1.EngagementBaseSystemMessage"
    }
}

Nested Schema : com.rightnow.chat.rest.consumer_api.model.messages.v1.RNEngagementConsumerErrorOccurredMessage

Type: object

Show Source

errorCode(optional): string

Allowed Values: [ "BAD_REQUEST", "CONFLICT", "FEATURE_NOT_IMPLEMENTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "ITEM_NOT_FOUND", "NOT_ACCEPTABLE", "NOT_ALLOWED", "NOT_AUTHORIZED", "RECIPIENT_UNAVAILABLE", "RESOURCE_CONSTRAINT", "SERVICE_UNAVAILABLE", "UNDEFINED_CONDITION", "UNEXPECTED_REQUEST", "SERVLET_SESSION_NOT_FOUND", "CX_SESSION_LOGOUT" ]

The error code returned by the chat server in case of an error.
errorText(optional): string

The text returned by the chat server in case of an error.
errorType(optional): string

Allowed Values: [ "AUTH", "CANCEL", "MODIFY", "WAIT" ]

The error type returned by the chat server in case of an error.

{
    "properties":{
        "errorType":{
            "type":"string",
            "description":"The error type returned by the chat server in case of an error.",
            "enum":[
                "AUTH",
                "CANCEL",
                "MODIFY",
                "WAIT"
            ]
        },
        "errorCode":{
            "type":"string",
            "description":"The error code returned by the chat server in case of an error.",
            "enum":[
                "BAD_REQUEST",
                "CONFLICT",
                "FEATURE_NOT_IMPLEMENTED",
                "FORBIDDEN",
                "INTERNAL_SERVER_ERROR",
                "ITEM_NOT_FOUND",
                "NOT_ACCEPTABLE",
                "NOT_ALLOWED",
                "NOT_AUTHORIZED",
                "RECIPIENT_UNAVAILABLE",
                "RESOURCE_CONSTRAINT",
                "SERVICE_UNAVAILABLE",
                "UNDEFINED_CONDITION",
                "UNEXPECTED_REQUEST",
                "SERVLET_SESSION_NOT_FOUND",
                "CX_SESSION_LOGOUT"
            ]
        },
        "errorText":{
            "type":"string",
            "description":"The text returned by the chat server in case of an error."
        }
    }
}

Nested Schema : com.rightnow.chat.rest.common.model.messages.v1.EngagementBaseSystemMessage

Type: object

Show Source

createdTime(optional): string

The time when the system message was created in yyyy-MM-dd'T'HH:mm:ssXXX format.
messageName(optional): string

Allowed Values: [ "RNEngagementActivityChangedMessage", "RNEngagementConcludedMessage", "RNEngagementConfigurationChangedMessage", "RNEngagementConsumerErrorOccurredMessage", "RNEngagementMessagePostedMessage", "RNEngagementParticipantAddedMessage", "RNEngagementParticipantConnectionStateChangedMessage", "RNEngagementParticipantLeftMessage", "RNEngagementRoleChangedMessage", "RNEngagementWaitInformationChangedMessage" ]

The name of the system message type.

{
    "properties":{
        "messageName":{
            "type":"string",
            "description":"The name of the system message type.",
            "enum":[
                "RNEngagementActivityChangedMessage",
                "RNEngagementConcludedMessage",
                "RNEngagementConfigurationChangedMessage",
                "RNEngagementConsumerErrorOccurredMessage",
                "RNEngagementMessagePostedMessage",
                "RNEngagementParticipantAddedMessage",
                "RNEngagementParticipantConnectionStateChangedMessage",
                "RNEngagementParticipantLeftMessage",
                "RNEngagementRoleChangedMessage",
                "RNEngagementWaitInformationChangedMessage"
            ]
        },
        "createdTime":{
            "type":"string",
            "description":"The time when the system message was created in yyyy-MM-dd'T'HH:mm:ssXXX format."
        }
    }
}

400 Response

The validation of the request object failed.

Root Schema : schema

Type: object

403 Response

The consumer 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 by submitting a POST request using cURL:

cURL Command Example

curl -X POST https://chat_rest_server_domain.com/engagement/api/consumer/day119_181100_sql_238h/v1/getMessages?pool=297:1 -H 'Content-Type: application/json; charset=UTF-8' -H 'SessionId: 192hyto5qomm8r8rpzzmuzsa6' -d '{}'

Request Body Example

The following shows an example of the request body in JSON format. For this operation it is an empty payload.

{}

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.

{
    "errorMessages": [],
    "systemMessages": [
        {
            "position": 2,
            "expectedWaitTimeSeconds": 0,
            "averageWaitTimeSeconds": 0,
            "messageName": "RNEngagementWaitInformationChangedMessage",
            "createdTime": "2018-10-23T10:06:51.900Z",
            "positionString": "2",
            "expectedWaitTimeSecondsString": "0",
            "averageWaitTimeSecondsString": "0"
        },
        {
            "position": 2,
            "expectedWaitTimeSeconds": 0,
            "averageWaitTimeSeconds": 0,
            "messageName": "RNEngagementWaitInformationChangedMessage",
            "createdTime": "2018-10-23T10:06:52.962Z",
            "positionString": "2",
            "expectedWaitTimeSecondsString": "0",
            "averageWaitTimeSecondsString": "0"
        }
    ],
    "clientRequestTime": null,
    "clientTransactionId": 0,
    "clientTransactionIdString": "0",
    "serviceStartTime": "2018-10-23T10:06:55.852Z",
    "serviceFinishTime": "2018-10-23T10:06:55.863Z",
    "clientId": 34,
    "clientIdString": "34"
}