Chat API Version 2

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

• API Responses
• Configuring the Digital Channels API

Request Chat

URI	HTTP Method
/genesys/2/chat/{serviceName}	POST

HTTP Header	Value
Content-Type	application/x-www-form-urlencoded
OR
Content-Type	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 client wants to add to chat	Optional
userData[importantKey2]	value2	any attached data that client wants to add to chat	Optional

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/send	POST

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 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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/startTyping	POST

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/stopTyping	POST

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.

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

Note: Genesys recommends waiting at least 3 to 5 seconds between calls to the Refresh service.

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/refresh	POST

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}

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/disconnect	POST

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/pushUrl	POST

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/updateNickname	POST

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/customNotice	POST

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

URI	HTTP Method
/genesys/2/chat/{serviceName}/{chatId}/updateData	POST

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"
}

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.

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

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

Input Parameters

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.

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

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 response for Refresh Chat request) indicating a file was upload.

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 file 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 downloaded 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
}