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
}

Contents

Chat API Version 2

Request Chat

Example

Send Message

Example

Start Typing

Example

Stop Typing

Example

Refresh Chat

Sample responses

Typing Preview

Example

Disconnect

Example

Push URL

Example

Update Nickname

Example

Custom Notice

Example

Update User Data

Example

Read Receipt

Example

Chat Session File Management

Get Limits

Output Parameters

Example

Upload File

Example

Download File

Example

Delete File

Example

Contact

Genesys

Customer Care

Legal