API Responses
All Digital Channels API responses contain:
- An HTTP status code
- Either an API statusCode or one or more API error codes.
The following sections provide more details about these responses.
HTTP 200
| 200 OK | |
| Response Body (JSON content) | |
| Name | Description |
|---|---|
statusCode
|
In all responses with an HTTP status code of 200:
|
Digital Channels Chat V2 Response Format
The positive response (HTTP status 200) from the GMS node is identical for any Chat V2 API request. It includes some fields that you can use in subsequent requests such as alias, userId, chatId, securekey, nextPosition, as well as chat transcripts available in the messages array. The Chat transcript may be empty or include one or more events.
| 200 OK | ||
| Response Body (JSON content) | ||
| Name | Type | Description |
|---|---|---|
statusCode
|
Integer
|
|
| alias | string | Identifies the Chat Server instance that served this request. When provided, use it in subsequent API requests. This alias may change several times within the same session. |
| chatEnded | boolean
|
If true, indicates that the current chat session has ended. If false, the chat session is still ongoing. |
| chatId | string | Identifies current Chat Session id. When provided, use it in subsequent API requests. This value doesn't change during the chat session. |
| messages | array of Chat transcripts | Contains full or partial chat transcript. See the Chat Transcript section below. |
| nextPosition | integer | Indicates which event index to use to request a transcript in the next operation (used in Refresh Chat, and other requests) |
| secureKey | string | Secured key for this session; use this key (valid only for this session) in each request. Make sure to protect this key. |
| userId | string | Identifies this chat party (self). When provided, use it in subsequent API requests. |
Party Resource
The from field of the chat event describes the party who generated this event. This resource matches the following format:
| Name | Type | Description |
|---|---|---|
| nickname | string | The preferable calling [nick] name of the chat participant. |
| participantId | integer
|
Identifier of this chat party. This identifier differs from the userId. The same party can join and leave several times the chat session. Each time that the party joins, it is assigned a new partyId even if it is the same agent. |
| type | string
|
|
Chat Transcript
The Chat Transcript consists of a list of chat events. Each chat event has an index assigned to the event when it happens that defines the order of events. You can request full or partial transcripts using the Chat Refresh operation. Note that you do not receive all of the Chat events, so the index difference between two events in the transcript can exceed one. Each chat event is generated by some chat party.
Important
Semantics of event text and userData in the event may vary, depending on the event type. For further details, see the query description in your Digital Channel API (Chat, Email, or Open Media).| Field | Type | Description |
|---|---|---|
| from | Party object | Describes the chat party who generated this event. |
| index | integer | Identifies serial number of this event within chat session, starts with 1 for the first event. |
| text | string | If available, contains the text associated with this event. |
| type |
|
Identifies the chat event type. |
| utcTime | integer | Indicates the event timestamp. |
| userData | map<string,string> | If available, contains additional information for this event. |
Example
200 OK
{
'alias': '117',
'chatEnded': False,
'chatId': '00001aCY6K8U003T',
'messages': [{'from': {'nickname': 'FirstStep',
'participantId': 1,
'type': 'Client'},
'index': 1,
'type': 'ParticipantJoined',
'utcTime': 1509117363000},
{'from': {'nickname': 'TestName',
'participantId': 2,
'type': 'Agent'},
'index': 2,
'type': 'ParticipantJoined',
'utcTime': 1509117368000},
{'from': {'nickname': 'FirstStep',
'participantId': 1,
'type': 'Client'},
'index': 3,
'text': 'First message',
'type': 'Message',
'utcTime': 1509117368000
}],
'nextPosition': 4,
'secureKey': 'e4071047872b7820630f',
'statusCode': 0,
'userId': '007559F34DB30001'
}
HTTP 400
Validation errors with an HTTP status code of 400 happen when any of the values necessary to complete an operation is missing. They have two different formats, depending on which release you are using:
GME version 8.5.103.08 and lower
{
error: "validationError"
fields:
{
nickname: "either nickname or firstName and
lastName should be supplied"
tenantName: "invalid"
}
}GME version 8.5.103.09 and higher
// array of all validation errors
{ "errors" : [
// missing required parameter _firstName_
{"code":102},
// missing required parameter _lastName_
{"code":103},
// total file size exceeded,configured value of 300kB
{"code":202,"advice":"300000"},
// attempt to upload file of incorrect type
{"code":203,"
advice":"jpg,zip,txt,pdf,exe,bmp,gif,dll,png,doc"}
]}Web API Validation Error Codes
| code | description | chat | openmedia | |
|---|---|---|---|---|
| 100-199 | Error messages in this range indicate that a required parameter is missing from a request. | |||
| 100 | RESERVED | |||
| 101 | tenant is missing. | |||
| 102 | firstName is missing. | x | x | |
| 103 | lastName is missing. | x | x | |
| 104 | subject is missing. | x | x | |
| 105 | userData is missing. | x | ||
| 151 | alias is missing. | x | ||
| 152 | userId is missing. | x | ||
| 153 | secureKey is missing. | x | ||
| 154 | chatId is missing. | x | ||
| 161 | nickname is missing. | x | ||
| 162 | message is missing. | x | ||
| 163 | pushUrl is missing. | x | ||
| 181 | fromAddress is missing. | x | ||
| 182 | text is missing. | x | ||
| 191 | mediaType is missing. | x | ||
| 192 | interactionType is missing. | x | ||
| 193 | interactionSubtype is missing. | x | ||
| 200-299 | Error messages in this range indicate that one or more of the parameters specified in a request is outside of the range configured in the Genesys Mobile Engagement application options. These errors include an advice field that displays the allowable range or limit. | |||
| 200 | RESERVED | |||
| 201 | The total number of uploaded files is too high | x | x | |
| 202 | The total size of the uploaded files is too large | x | x | |
| 203 | The uploaded file has an incorrect filetype | x | x | |
| 240 | An unexpected error occurred. The advice field includes the ReferenceID that helps to identify the error cause in the GMS log file. | x | x | x |
| 241 | The specified file is not present in the current session. | x | ||
| 248 | The interaction with the specified ID was not found. | x | ||
| 249 | The Media Server was not able to execute the request. | x | ||
| 250-299 | Error messages in this range are not generated by Genesys Mobile Engagement but are provided directly by the connected Media Server (for example, Chat Server). | x | ||
| 250 | RESERVED | |||
| 261 | File Upload is not possible until an agent joins the session. | x | ||
| 264 | File was already deleted. | x | ||
| 300-399 | Error messages in this range indicate that a request parameter is malformed or invalid (for example, an invalid email address). | |||
| 300 | RESERVED | |||
| 306 | serviceName URL parameter is invalid (that is, not configured in the Genesys Mobile Engagement application). The HTTP status will be set to 404 - Not Found instead of 400 - Bad Request. | x | x | |
| 364 | emailAddress contains an invalid email address. | x | ||
| 381 | fromAddress contains an invalid email address. | x | ||
| 383 | mailbox contains an invalid email address. | x | ||
This page was last edited on March 28, 2024, at 06:54.
Comments or questions about this documentation? Contact us for support!