Jump to: navigation, search

Chat API Version 2

Use this API for Web Chat (replacement for eServices WebAPI Chat). For more information, refer to:

Request Chat

HTTP Method URI
POST /genesys/2/chat/{serviceName}
HTTP Header Value
Content-Type application/x-www-form-urlencoded
OR
multipart/form-data
Parameter Name Sample Value Description Required/Optional
nickname "JohnDoe" customer's nickname (either nickname or both firstName and lastName should be supplied) Required
firstName "John" first name of the customer (either nickname or both firstName and lastName should be supplied) Required
lastName "Doe" last name of the customer (either nickname or both firstName and lastName should be supplied) Required
subject "Help with account" subject as entered by the customer Optional
emailAddress "jdoe@gmail.com" email address of the customer Optional
userData[attachedDataKey1] value1 any attached data that the client wants to add to chat Optional
userData[importantKey2] value2 any attached data that the client wants to add to chat Optional


Important
To specify the correct time zone for the participant who initiates the chat, you must provide the TimeZone attached data in userData. The TimeZone value is measured in minutes. For example, to specify the PST time zone, userData[TimeZone]=-480.


Example

http://localhost:8080/genesys/2/chat/customer-support

Input

firstName=First
lastName=Last
subject=Subject+to

Output

{
"statusCode":0,
"alias":"117",
"userId":"007555677B20000A",
"secureKey":"4ee15d7e1c343c8e",
"messages":[
 {
  "from":{"nickname":"First Last","participantId":1,"type":"Client"},
  "index":1,
  "type":"ParticipantJoined",
  "utcTime":1432845088000
} ],
"chatId":"00048aAPEQJ8000U"
}

Send Message

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/send
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
message "I need help with account" text message to send Required
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
messageType "text" any arbitrary type that the user wants to set Optional
transcriptPosition 8 Including this parameter enables the return of the transcription and it sets the position in the transcript from where it should be retrieved. Optional

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/send

Input

userId=00755567761A0008
alias=117
secureKey=09fa6e8a8691c229
transcriptPosition=8 message=hello

Output

{
"messages":[
 {"from":{"nickname":"First
Last","participantId":1,"type":"Client"},"index":7,
"text":"hello","messageType":null,"
type":"Message","utcTime":1432845541000},
 {"from":{"nickname":"First
Last","participantId":1,"type":"Client"},"index":8,"text":"hello",
"messageType":null,"
type":"Message","utcTime":1432845548000}],
"chatEnded":false,
"statusCode":0,
"alias":"117",
"secureKey":"3e2a69d421ae2672",
"userId":"007555677CB4000D"
}

Start Typing

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/startTyping
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
message "message ..... " message if any Optional

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/startTyping

Input

userId=0075555D17270020
alias=117
secureKey=cccfa34d89441faf

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "cccfa34d89441faf"
	userId: "0075555D17270020"
}

Stop Typing

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/stopTyping
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
message "message ..... " message if any Optional

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/stopTyping

Input

userId=0075555D17270020
alias=117
secureKey=cccfa34d89441faf

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "cccfa34d89441faf"
	userId: "0075555D17270020"
}

Refresh Chat

Refresh Chat requests a transcript of events from the specified chat. The value of the transcriptPosition parameter determines which events are returned:

  • If transcriptPosition is set to 0, none of the events from the chat are returned.
  • If transcriptPosition is set to 1, all of the events from the chat are returned.
  • Otherwise, the request returns any new events that have occurred since the event at the position number indicated in the transcriptPosition parameter.
Important
Genesys recommends setting the transcriptPosition parameter in any subsequent request to the nextPosition value returned in the response of the previous request. This will ensure that your further request will fetch only newly added transcript events from the chat session.

In addition to its usefulness in returning the above information, you can use this request to let Chat Server know that the web client that sent the request is still alive.

Important
Genesys recommends waiting for at least 3 to 5 seconds between calls to the Refresh service.
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/refresh
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
transcriptPosition

0 (no messages)

1 (all messages)

2 (all messages starting from 2nd message)

index position in the transcript starting from which the messages should be retrieved

Optional (All messages are retrieved if no value is provided, which defaults to 1)

message "Text that user is typing ..."

For use with Typing Preview at the agent chat window. Text that the user has entered so far in the chat box at the time this request is being made. This text will be submitted to the chat server along with notification TypingStarted.

Property "typing_preview" must be enabled as described in Chat Services Options.

Applies only to Typing Preview

  • If no message is submitted (absent from JSON input), no TypingStarted request is submitted to the chat server
  • If message is submitted (even if it is empty/blank but present in JSON input) a TypingStarted request is submitted along with a MessageText containing this text.

Field is ignored for a regular refresh transcript call.

Sample responses

No new events

{"messages:[],
"chatEnded":false,
"statusCode":0,
"alias":"249",
"secureKey":"45327f306556129f",
"userId":"00F9568B2DA601BA",
"tenantName":"Resources",
"nextPosition":5}


New message from agent

{"messages":
[{"from":{"nickname":"AgentNick","participantId":3,"type":"Agent"},
"index":7,"text":"hello","type":"Message","utcTime":1451961875000}],
"chatEnded":false,"statusCode":0,"alias":"249",
"secureKey":"45327f306556129f","userId":"00F9568B2DA601BA",
"tenantName":"Resources","nextPosition":8}


Agent has left; session is closed
(Note that the transcript has a type of ParticipantLeft and that chatEnded is true.)

{"messages":
[{"from":{"nickname":"AgentNick","participantId":3,
"type":"Agent"},"index":9,"type":"ParticipantLeft",
"utcTime":1451961917000},{"from":{"nickname":"Maria",
"participantId":1,"type":"Client"},
"index":10,"type":"ParticipantLeft","utcTime":1451961917000}],
"chatEnded":true,"statusCode":0,"alias":"249",
"secureKey":"45327f306556129f","userId":"00F9568B2DA601BA",
"tenantName":"Resources","nextPosition":1}

Agent has left the chat session temporarily

{  "messages":[
    { "from":{"nickname":"AgentNick", "participantId":3, "type":"Agent"},
      "index":12, "type":"ParticipantLeft", "utcTime":1451961917000,
      "eventAttributes":{"general-properties":{"reason-for-leave":"HOLD"}}  }  ],
  "chatEnded":false, "statusCode":0, "alias":"249", "secureKey":"45327f306556129f", "userId":"00F9568B2DA601BA", "tenantName":"Resources", "nextPosition":14
}
Important
The reason-for-leave property will be absent when the agent leaves chat session. The reason-for-leave property is equal to TRANSFER when the agent transfers the chat interaction, and it is equal to HOLD when the agent puts the chat interaction on hold (in asynchronous chat).

Typing Preview

The message:

  • Is the entire value of the text box in which the user is typing.
  • Only needs to be sent if it has changed from the previous time it was sent.
  • Only needs to be checked for changes every 10 seconds or so. So, for example, if the Refresh service is called every 5 seconds, the text box can be checked for changes every 2 iterations.

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000W/refresh

Input

userId=007555677CB4000D
alias=117
secureKey=3e2a69d421ae2672
transcriptPosition=20

Output

{
 "messages":[
 {
  "from":{"nickname":"system","participantId":2,"type":"External"},"
  index":20,
  "text":"agent will be with you shortly ...",
  "messageType":null,
  "type":"Message","utcTime":1432845749000
 },
 {
  "from":{"nickname":"system","participantId":2,"type":"External"},
  "index":21,"text":"agent will be with you shortly...",
  "messageType":null,
  "type":"Message",
  "utcTime":1432845767000
 }
 ],
 "chatEnded":false,
 "statusCode":0,
 "alias":"117",
 "secureKey":"3e2a69d421ae2672",
 "userId":"007555677CB4000D",
 "nextPosition":22
}

Disconnect

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/disconnect
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/disconnect

Input

userId=0075555D17270020
alias=117
secureKey=cccfa34d89441faf

Output

{
	messages: null
	chatEnded: null
	statusCode: 0
	alias: null
	secureKey: null
	userId: null
}

Push URL

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/pushUrl
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
pushUrl "http://url.to.see" URL Required

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/pushUrl

Input

userId=0075555D17270020
alias=117
secureKey=cccfa34d89441faf
pushUrl=url.to.see

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "09fa6e8a8691c229"
	userId: "00755567761A0008"
}

Update Nickname

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/updateNickname
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
nickname John Doe 2 new nickname Required

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/updateNickname

Input

userId=00755567761A0008
alias=117
secureKey=09fa6e8a8691c229
nickname=newName

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "09fa6e8a8691c229"
	userId: "00755567761A0008"
}

Custom Notice

This request is used to deliver any custom notification between a custom client application and a custom agent desktop. Neither Genesys Widgets, nor Workspace use this out of the box.

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/customNotice
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
message "message ..." message, if any Optional

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/customNotice

Input

userId=00755567761A0008
alias=117
secureKey=09fa6e8a8691c229
message=custom+message

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "09fa6e8a8691c229"
	userId: "00755567761A0008"
}

Update User Data

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/updateData
HTTP Header Value
Content-Type application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
userData[key1] value1 user data to be updated Required
userData[key2] value2 user data to be updated Required


Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000S/updateData

Input

(URL encoded, raw)
userId=0075556DEA820000&alias=117&secureKey=7d1f6f3ff2e60cd6
&userData%5Bkey1%5D=value1&userData%5Bkey2%5D=value2

(Form, user input, unencoded)
userId=0075556DEA820000
alias=117
secureKey=7d1f6f3ff2e60cd6
userData[key1]=value1
userData[key2]=value2

Output

{
	messages: null
	chatEnded: false
	statusCode: 0
	alias: "117"
	secureKey: "09fa6e8a8691c229"
	userId: "00755567761A0008"
}

Read Receipt

Introduced in: 8.5.201.04

Use this operation to acknowledge that the user has read a given message or event.

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/readReceipt
HTTP Header Value
Content-Type

application/x-www-form-urlencoded

Parameter Name Sample Value Description Required/Optional
userId "007553863DC30029" user ID Required
secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
transcriptPosition "5" The index of the event that the client app acknowledges having read.

This is not the same index as nextPosition, but rather the index of the event from the "messages" array.

Required

Example

http://localhost:8080/genesys/2/chat/customer-support/00048aAPEQJ8000S/readReceipt

Input

userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117
transcriptPosition=5

Output

{
  "messages": null,
  "chatEnded": false,
  "statusCode": 0,
  "alias": "117",
  "secureKey": "799c5ff0faccd5bb",
  "userId": "00F05702F26B0006"
}

Chat Session File Management

Updated in 8.5.110.07

Starting with Release 8.5.106, the GMS Digital Channels API allows agents and customers to exchange files during their chat sessions using these requests:

  • Get Limits—Check for allowable file types and file size—or other constraints on file uploads—before sending an upload request.
  • Upload File—Upload a file.
  • Download File—Download a previously uploaded file.
  • Delete File—Delete a previously uploaded the file.


Get Limits

Use this optional request to avoid wasting network and CPU overhead by checking for allowable file types or maximum file size—or other constraints on file uploads—before sending an upload request.

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/file/limits
HTTP Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded (starting in 8.5.110.07)
Parameter Name Sample Value Description Required/Optional Source
userId "007553863DC30029" user ID Required Form
secureKey "8b31761b2154884c" secure key Required Form
alias "117" host alias Required Form


Output Parameters

Parameter Description
download-attempts Maximum number of times a specific file can be downloaded during this session
upload-max-files Maximum number of files a client can upload during this session
upload-max-file-size Maximum allowable file size of a single uploaded file
upload-max-total-size Maximum allowable file size of all uploaded files
upload-need-agent Indicates whether an agent needs to accept a chat session before an upload is allowed
upload-file-types Colon-delimited list of file extensions indicating which types of files can be uploaded
used-upload-max-files Current number of files uploaded during this session
used-upload-max-total-size Current total size of all files uploaded during this session
used-download-attempts Current number of downloaded files during this session
delete-file Indicates whether upload-max-files is decremented after a file has been deleted

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000U/file/limits

Input

userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117

Output

{
  "messages": null,
  "chatEnded": false,
  "statusCode": 0,
  "alias": "240",
  "secureKey": "799c5ff0faccd5bb",
  "userId": "00F05702F26B0006",
  "userData": {
    "download-attempts": "10",
    "upload-max-files": "10",
    "delete-file": "odd",
    "upload-max-file-size": "100000000",
    "used-download-attempts": "0",
    "used-upload-max-total-size": "0",
    "upload-need-agent": "true",
    "used-upload-max-files": "0",
    "upload-max-total-size": "500000000",
    "upload-file-types": "bmp:csv:doc:docx:exe:gif:htm:jpg:pdf:png:ppt:
pptx:tif:txt:xls:xlsx:zip"
  }
}

Upload File

Use this request to upload a file into a chat session so it can be shared with an agent or a customer. You can then use the file-id value in the response to delete or download the file, as needed.

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/file
HTTP Header Value
Content-Type multipart/form-data
Parameter Name Sample Value Description Required/Optional Source
userId "007553863DC30029" user ID Required Form
secureKey "8b31761b2154884c" secure key Required Form
alias "117" host alias Required Form
file "afile.txt" file to be uploaded into the session Required Form
userData[file-description] "March invoice" This value can be used by the agent desktop and the client UI to provide additional file info Optional Form
userData[userKey1] "User value 1" Collection of key-value pairs that provides file metadata Optional Form


Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000U/file

Input

userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117
file=<some file to upload>

Output

{
  "messages": [],
  "chatEnded": false,
  "statusCode": 0,
  "alias": "240",
  "secureKey": "77cd1c487b67fefb",
  "userId": "00F057DB0FC30001",
  "chatId": "0001KaBWNVUV000K",
  "userData": {
    "file-id": "00F057DB0FF10005"
  },
  "nextPosition": 6
}

Download File

Use this request to download a file that was uploaded into a chat session either by an agent or a customer. The fileId parameter can be retrieved from the previous transcript event (see the response for Refresh Chat request) indicating a file was uploaded.

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/file/{fileId}/download
HTTP Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded (starting in 8.5.110.07)
Parameter Name Sample Value Description Required/Optional Source
userId "007553863DC30029" user ID Required Form
secureKey "8b31761b2154884c" secure key Required Form
alias "117" host alias Required Form
fileId "00048aAPEQJ8ABCD" File to be downloaded from the session Required URL


Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD

Input

userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117

Output

If the operation is successful, the contents of the file are downloaded. In case of an error, the server returns an HTML 500 response that includes the referenceId of the request.

The following HTML snippet shows how to download a file using an HTML form:

var form = $("<form method='POST' enctype='multipart/form-data' 
target='_blank' 
action='http://GMS_HOST:GMS_PORT/genesys/2/chat/customer-
support/0001JaBUS5FD002U/file/00F057C8BFA20052/download'>
<input name='alias' value='240' type='hidden'><input name='secureKey' 
value='6b46a7a8910f21be' type='hidden'><input name='userId' 
value='00F057C8B6B7004D' type='hidden'></form>");
 
form.submit();


Delete File

Use this request to delete a file that was uploaded into a chat session by a customer if allowed by Chat Server settings. Web User has no permission to delete files uploaded by the agent.

URI HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/file/{fileId}/delete POST


HTTP Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded (starting in 8.5.110.07)


Parameter Name Sample Value Description Required/Optional Source
userId "007553863DC30029" user ID Required Form
secureKey "8b31761b2154884c" secure key Required Form
alias "117" host alias Required Form
fileId "00048aAPEQJ8ABCD" The file to be deleted from the session Required URL

Example

http://localhost:8080/genesys/2/chat/customer-support
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD/delete

Input

userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117

Output

{
  "messages": [],
  "chatEnded": false,
  "statusCode": 0,
  "alias": "240",
  "secureKey": "ad437d2338d09d09",
  "userId": "00F057DB125E000A",
  "chatId": "0001KaBWNVUV0011",
  "nextPosition": 7
}
This page was last edited on August 30, 2022, at 08:48.
Comments or questions about this documentation? Contact us for support!