Jump to: navigation, search

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
required

In all responses with an HTTP status code of 200:

  • An API statusCode value of 0 indicates that the operation was successful and all fields in the response have valid values.
  • An API statusCode value of 1 indicates that there was an error and the client can keep trying until it receives a statusCode of 0 or until it decides to give up.
    Note: When you receive this response, you cannot assume that the values of any other fields are valid.
  • An API statusCode value of 2 indicates that:
    • There was an error
    • Repeating requests will not be successful
    • The chat may have ended—read the value of the chatEnded flag.
      Note: When you receive this response, you cannot assume that the values of any other fields are valid.


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
required
Integer
0,1,2
  • 0 indicates that the operation was successful and all fields in the response have valid values.
  • 1 indicates that there was an error and the client can keep trying until it receives a statusCode of 0 or until it decides to give up.
    Note: When you receive this response, you cannot assume that the values of any other fields are valid.
  • 2 indicates that there was an error.
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
false, true
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:

Party Resource
Name Type Description
nickname string The preferable calling [nick] name of the chat participant.
participantId integer
1,2...
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
"Agent"
"Client"
"External"
Describes the type of participant.
"External" means that the event was not generated by a customer or an agent, but rather by an ESP request, received for example from the routing strategy.

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).
Chat Transcript Resource
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
ParticipantJoined
ParticipantLeft
Message
TypingStarted
TypingStopped
NicknameUpdated
PushUrl
FileUploaded
FileDeleted
CustomNotice
Notice
IdleAlert
IdleClose
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 email 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  

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on 11 April 2018, at 10:31.