Jump to: navigation, search

fcm.body

Section: push
Default Value: No default value
Valid Values: Any string
Changes Take Effect: After restart
Introduced: 8.5.114.09

Firebase Cloud Messaging body message for an event defined at the provider level.

more...

fcm.title

Section: push
Default Value: No default value
Valid Values: Any string
Changes Take Effect: After restart
Introduced: 8.5.114.09

Firebase Cloud Messaging title for an event defined at the provider level.

more...

fcm.body

Section: push
Default Value: No default value
Valid Values: Any string
Changes Take Effect: After restart
Introduced: 8.5.114.09

Firebase Cloud Messaging body message for an event defined at the provider level.

more...

fcm.title

Section: push
Default Value: No default value
Valid Values: Any string
Changes Take Effect: After restart
Introduced: 8.5.114.09

Firebase Cloud Messaging title for an event defined at the provider level.

more...

enable_notification_mode

Section: chat.service-name
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Introduced: 8.5.109.05

Enables the notification mode for the Chat V2 CometD API. This option is defined on a media level only and is not dynamic. You cannot change this option at runtime: doing so may lead to incorrect node behavior. If you set this option to true, the GMS node will establish a persistent connection with the Chat Server(s) and enable the Chat V2 CometD API.

enable_notification_mode

Section: chat.service-name
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Introduced: 8.5.109.05

Enables the notification mode for the Chat V2 CometD API. This option is defined on a media level only and is not dynamic. You cannot change this option at runtime: doing so may lead to incorrect node behavior. If you set this option to true, the GMS node will establish a persistent connection with the Chat Server(s) and enable the Chat V2 CometD API.

Chat API Version 2 with CometD

Introduced in 8.5.109

Versions Changes
8.5.109 Genesys Mobile Enterprise supports the Digital Channels Chat API V2 over CometD channel. Most of the time, requests, responses, parameters names, and error codes are identical between the REST and CometD APIs.
8.5.110 GMS supports CometD WebSocket Transport. To enable Secure WebSocket, deploy GMS with an SSL certificate.
8.5.112
  • Digital Channels Chat API V2 over CometD now supports File Transfer operations.
  • Chat API with CometD usability is enhanced and request parameters such as alias, userId, and chatId are now deprecated. To ensure backward compatibility, GMS nodes will still include those keys with bogus values in notification events.
8.5.114
  • Chat V2 API over CometD now supports Firebase Cloud Messaging push notifications, that allow delivering notifications of new chat events in the outgoing chat session to a mobile terminal, while the main application is offline or in background.
  • Chat V2 API over CometD now supports native push notifications through Apple Push Notification Service. APNS support is limited to Legacy Binary Provider API.
8.5.201

Chat V2 API over CometD now supports Read receipt.

Prerequisites for the CometD API

Server Minimum version Configuration details
GMS 8.5.109.05+
  • GMS can run in chat only or in full mode.
  • To enable the notification mode, set to true the option enable_notification_mode in the chat section.
  • If you use a load balancer in front of several GMS nodes, enable the sticky sessions.

The option enable_notification_mode is not dynamic. You cannot modify it at runtime.

Chat Server 8.5.108+
  • All the connected Chat Server instances need to be deployed in N+1 configuration with session restoration.
  • Enable the notification mode by setting to true the option flex-push-enabled in the settings section.
  • Configure a digital channel
Important
Configuration changes to the connected Chat Server instance disable this instance for serving notifications.
  • Do all changes when GMS is offline. Note that you don't need to stop the Chat Server to process the configuration changes.
  • If you absolutely need to keep GMS online, remove the connection to the Chat Server instance from the GMS cluster, do configuration changes on the instance, and add the connection to the Chat Server again in the GMS cluster.

How to use the CometD API

When you are using the CometD API, both client and server applications exchange messages with a JSON payload. The client application can request an operation from the GMS server, and the GMS server responds with notifications. GMS also delivers unsolicited notifications when an event happens during the chat session. All operations are asynchronous, which means that notifications will respond and confirm the requested operations.

Handshake with GMS

The first step is a handshake with the GMS node, using the full GMS URI; for instance:
http://<gms-hostname>:8080/genesys/cometd

Subscribe for a channel

After a successful handshake, you need to either subscribe to or add a listener for your channel. The channel name depends on the digital channel that you created before. It includes the chat service name and is formatted as follows: /service/chatV2/<chat service>.

For instance, if you create and configure the customer-support chat service, the associated channel will be: /service/chatV2/customer-support

Example of handshake and channel listener:

var gmsCometURL = http://my.gms.host:8080/genesys/cometd
var chatChannel = /service/chatV2/customer-support
 
function handleChatEvent( message) { ... }
 
cometd.addListener( chatChannel, handleChatEvent )
cometd.configure({
    url: gmsCometURL,
    logLevel: 'debug'
});
cometd.handshake()

Example of handshake and subscription:

var gmsCometURL = http://my.gms.host:8080/genesys/cometd
var chatChannel = /service/chatV2/customer-support
 
function handleChatEvent( message ) { ... }
 
function _handleHandshake( handshake ) {
    if ( true === handshake.successfull ) {
        cometd.batch( function() { cometd.subscribe( chatChannel, handleChatEvent ); } );
    }
}
 
cometd.addListener( '/meta/handshake', _handleHandshake )
cometd.configure({
    url: gmsCometURL,
    logLevel: 'debug'
});
cometd.handshake()

Enable Push Notifications

Introduced in 8.5.114

Configure Firebase Cloud Messaging in GMS

Refer to the Push Notification Service documentation to configure your Firebase Cloud Messaging provider. You can define several different provider sections and associate any of them when starting a chat service with the requestChat and requestNotifications API queries.

  • If you do not add provider information to the user data, the system will use the default Firebase Cloud Messaging options that you configured in the push section of the GMS configuration.
  • If you specify a non-default provider in the user data of the query, the system will use the Firebase Cloud Messaging options that are configured in the [push.provider.{ProviderName}] section, where {ProviderName} is the string to provide in the push_notification_provider user data of the requestChat operation.

You can also use fcm.title and fcm.body options to extend your configuration by creating an event-level [push.provider.{ProviderName}.event] section and then, a specific service name and event. The following example shows how to configure in GMS two chat services for Bank's Saving Account and use localized messages in English and Russian:

[+] See the configuration example


If you do not configure FCM title and body options, the system will use the English default values.

Event Name title default value body default value Comments
ParticipantJoined "Chat participants changed"

"%s joined chat"

 %s is substituted with the party name
ParticipantLeft

"Chat participants changed"

"%s left chat"

Message

"%s sent new message"

The message sent by the participant.

PushUrl

"%s suggests Web page"

URL pushed by the participant.

FileUploaded

"%s suggests to download file"

"Open app for more info"

IdleAlert

"Chat will close soon"

"Please use app if you want to continue"

IdleClose

"Chat is over"

"Your chat session was ended due to inactivity"

Important
The FileDeleted, CustomNotice, and Notice events are not pushed.


Provide Firebase Cloud Messaging Parameters in User Data

When your client application submits requestChat and requestNotifications queries, the request must include the push_notification_* in its user data. These data identify the mobile terminal and your client app must provide the exact same data each time it re-establishes a CometD connection and issues the requestNotifications operation.

Important
The push_notification_* user data are detailed in this page in the requestChat and requestNotifications sections.

Firebase Push Notification Limitations

  • Only one session per client is supported. If the same user tries to login into the mobile app from two devices, only one device will be able to manage the chat session in progress.
  • The client app must create the chat session over Chat V2 with CometD in order to receive notifications. Furthermore, the client app must use Chat V2 API with CometD whenever it is sent in foreground. On background switchovers, Genesys recommends to perform a CometD disconnection or to unload the app from memory to preserve the device's battery.
  • As stated above, default notifications are submitted in English only. To support additional languages, you must provision the fcm.title and fcm.body options at the provider service event level, or intercept notifications on the terminal, process them in the background to change text, and present a new notification to the user.


Receive Notifications

To start receiving notifications, you can either:

  • Use the requestChat operation to request a new chat for your channel.
  • Request notifications for an existing chat through the requestNotifications operation. In this scenario, you must specify the channel where the chat was created.

If the requestChat operation succeeds, the client receives a notification about joining the session and, later, further notifications on each session event.

  • Your client application should read the parameters named chatId, userId, secureKey, and alias from the notification response, and reuse them with each subsequent request message.
  • Each chat event has an index matching the event order.
  • All unsolicited notifications will have exactly one event. Notifications sent as a response to a request may have one or no events. The notifications sent in response to the requestChat and requestNotifications requests may have 0, 1, or more events.

When your client application processes events, it needs to check the index of each event received and compare it with the index of the last processed event. If the index is identical or smaller, the event can be ignored. If the index of the new received event is greater than the index of the last processed event, the client application should update the UI with the new event, as appropriate, and remember the new index as the last processed event.

Important
Starting with release 8.5.112, the request parameters such as alias, userId, and chatId are deprecated.

Handling disconnections

In case of disconnection, the client application should perform a new handshake if necessary, and use the requestNotifications operation with the following information:

  • The latest known transcript position
  • Identical userId, chatId, and secureKey parameters

If the chat session is still ongoing, the client will receive a notification with a new (possibly the same) alias to use, and the list of the chat events that happened since the last known position.

Authentication

If you enable Basic Authentication for the chat service accessed through the CometD API, you must provide the authentication credentials in the auth parameter of the requestChat operation. There are two ways to provide credentials in an auth object:

  • In an open form containing the username and password fields
  • In an encoded form using encoded fields, similar to the Basic Authentication header, which is a Base64-encoded composite string of "username:password"

Here is an open-form example of a request message with authentication credentials:

var channel ="/service/chatV2/customer-support";
var requestChatData ={
    "operation": "requestChat",
    "firstName": "Joan",
    "lastName": "Smith",
    "subject": "Savings Account",
    "userData": {
        "key1": "value1",
        "key2": "value2"
    },
    "auth": {
        "username": "user1",
        "password": "pass1"
    }
}
cometd.publish( channel, requestChatData);

Here is an encoded-form example of a request message with authentication credentials:

var channel ="/service/chatV2/customer-support";
var requestChatData ={
    "operation": "requestChat",
    "firstName": "Joan",
    "lastName": "Smith",
    "subject": "Savings Account",
    "userData": {
        "key1": "value1",
        "key2": "value2"
    },
    "auth": {
        "encoded": "dXNlcjE6cGFzczE="
    }
}
cometd.publish( channel, requestChatData);

CometD API

Request Chat

Modified in 8.5.112

Use this method to request a new chat session and start receiving the associated notifications. If the requestChat operation is successful, you will receive a notification response data object that contains the parameters required for subsequent messages and operations:

  • chatId—ID for the new chat session
  • userId—User ID used for the chat session
  • secureKey—Secure key for this session
  • alias—Chat host alias used for the session

See also the Subscribe and Authentication sections for further use cases and details.

Operation

Operation requestChat
Parameter Type Mandatory Description
nickname string yes Customer's nickname. Genesys recommends that you supply either nickname or both firstName and lastName parameters. For example: "JohnDoe"
lastName string no Last name of the customer. Genesys recommends that you supply either nickname or both firstName and lastName parameters. For example: "Doe"
subject string no The subject as entered by the customer. For example: "Help with account"
emailAddress string no The email address of the customer. For example: "jdoe@gmail.com"
userData JSON-formatted string no Any attached data that the client wants to add to the chat session. For example: { "key":"value", ... }
Important
Starting in 8.5.112, the request parameters such as alias, userId, and chatId are deprecated.

Starting in 8.5.114, you can add the following user data (that must be identical in the requestNotifications query) to enable Firebase Cloud Messaging push notifications.

User Data Key Value Required Description
push_notification_deviceid ID Yes Unique deviceId or token received from FCM or APNS. Your client app must provide the exact same data each time it re-establishes a CometD connection and issues the requestNotifications operation.
push_notification_type
fcm
Yes
  • "fcm" for Google Firebase Messaging client

Your client app must provide the exact same data each time it re-establishes a CometD connection and issues the requestNotifications operation.

push_notification_debug
"true"
"false" (default)
No If true, debug mode for Firebase Cloud Messaging or Apple notification service will be used. Note if your Apple certificate is available for debug mode only, set this flag to true; otherwise, the device will not receive notifications.
push_notification_language ISO language code No Reserved for now. Defines the language for the client application. The language is en_US by default.
push_notification_provider string No Defines the name of the GMS provider configuration section to use for this chat session. If you do not provide a name, the system will use the default provider defined in the push section.
Important
Genesys recommends to use short strings that include short words and exclude any special symbols or punctuation.

Example

The following is an example of a request.

var channel ="/service/chatV2/customer-support"; 
var requestChatData ={
    "operation": "requestChat",
    "firstName": "Joan",
    "lastName": "Smith",
    "subject": "Savings Account",
    "userData": {
        "key1": "value1",
        "key2": "value2"
    }
} 
cometd.publish(channel, requestChatData);

The following is an example of the notification response.

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

Request Notifications

Modified in 8.5.112

Use this operation to request notifications to be delivered for the existing chat session, after the CometD channel has been disconnected.

Operation

Operation requestNotifications
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
Long yes Chat ID that GMS sent in response to the requestChat operation. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
Long yes User ID that GMS sent in response to the requestChat operation. For example: "007555677B20000A"
secureKey Long yes Secure key that GMS sent in response to the requestChat operation. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias.
transcriptPosition integer no The transcript event position from which the client application would like to receive the previous events. If you set this option to 0 or if you don't set this option, the client will receive all the events.
Important
Starting in 8.5.112, the request parameters such as alias, userId, and chatId are deprecated.

Starting in 8.5.114, you can add the following user data (that must be identical in the requestChat query) to enable Firebase Cloud Messaging push notifications.

User Data Key Value Required Description
push_notification_deviceid ID Yes Unique deviceId or token received from FCM or APNS. Your client app must provide the exact same data each time it re-establishes a CometD connection and issues the requestNotifications operation.
push_notification_type
fcm
Yes
  • "fcm" for Google Firebase Messaging client

Your client app must provide the exact same data each time it re-establishes a CometD connection and issues the requestNotifications operation.

push_notification_debug
"true"
"false" (default)
No If true, debug mode for Firebase Cloud Messaging or Apple notification service will be used. Note if your Apple certificate is available for debug mode only, set this flag to true, otherwise, the device will not receive notifications.
push_notification_language ISO language code No Reserved for now. Defines the language for the client application. The language is en_US by default.
push_notification_provider string No Defines the name of the GMS provider configuration section to use for this chat session. If you do not provide a name, the system will use the default provider defined in the push section.
Important
Genesys recommends to use short strings that include short words and exclude any special symbols or punctuation.

Example

Example of request:

var channel ="/service/chatV2/customer-support";
 
var requestNotificationData ={
    "operation": "requestNotifications",
    "alias": "117",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e",
    "transcriptPosition": "2"
}
cometd.publish( channel, requestNotificationData );

Example of received notification:

{
    "messages": [
        {
            "from": {
                "nickname": "Joan Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 2,
            "text": "Hello, ...",
            "messageType": "text",
            "type": "Message",
            "utcTime": 1432845541000
        },
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 2
}

Send message

Use this operation to deliver or send messages from the client application to the chat session.

Operation sendMessage
Parameter Type Mandatory Description
message string yes Text message to send. For example: "I need help with my account."
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
messageType string no Any arbitrary type that the user wants to set. For example: "text"

Example

Example of request:

var channel ="/service/chatV2/customer-support";
var sendData ={
    "operation": "sendMessage",
    "message": "Hello, ...",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, sendData );

Example of notification response:

{
    "messages": [
        {
            "from": {
                "nickname": "Joan Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 2,
            "text": "Hello, ...",
            "messageType": "text",
            "type": "Message",
            "utcTime": 1432845541000
        },
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 3
}

Read receipt

Introduced in: 8.5.201.04

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

Operation readReceipt
Parameter Type Mandatory Description
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
transcriptPosition integer yes 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.

Example

Example of request:

var channel = "/service/chatV2/customer-support"
...
var readReceiptData = {
    "operation":"readReceipt",
    "transcriptPosition" : "5",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, updateNicknameData );

Example of notification response:

{
    "messages":[],
    "chatEnded":false,
    "statusCode":0,
    "secureKey": "4ee15d7e1c343c8e"
    "nextPosition" : 9
}

Start Typing

Use this operation to indicate that the client has started typing a message. You can include a partial message, if desired, for typing preview.

Operation

Operation startTyping
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
message string no Optional preview typing message to send. For example: "I need help with my account."

Example

Example of request:

var channel ="/service/chatV2/customer-support";
var startTypingData ={
    "operation": "startTyping",
    "message": "Hello, ...",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, sendData );

Example of notification response:

{
    "messages": [
        {
            "from": {
                "nickname": "John Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 3,
            "text": "hello, I ha",
            "type": "TypingStarted",
            "utcTime": 1493509617000
        }
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 4
}

Stop Typing

Use this operation to indicate that the client has stopped typing a message. You can include a partial message, if desired, for typing preview.

Operation

Operation stopTyping
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
message string no Optional preview typing message to send. For example: "I need help with my account."

Example

Example of request message:

var channel ="/service/chatV2/customer-support";
var sendData ={
    "operation": "stopTyping",
    "message": "Hello, ...",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, sendData );

Example of notification response data object:

{
    "messages": [
        {
            "from": {
                "nickname": "John Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 4,
            "text": "hello, I have a question",
            "type": "TypingStopped",
            "utcTime": 1493509618000
        }
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 5
}

Disconnect

Use this operation to finish the chat session. The notification response does not include a secureKey or userId parameter. Your application needs to clean up chatId, userId, and secureKey values and forget about them. Any subsequent operation with these IDs will generate error notification responses.

Operation

Operation disconnect
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"

Example

Example of request message:

var channel ="/service/chatV2/customer-support";
var disconnectData ={
    "operation": "disconnect",
    "alias": "117",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, disconnectData );

Example of notification response:

{
   "messages":[],
   "chatEnded":true,
   "statusCode":0,
   "alias":"117",
   "chatId" : "00048aAPEQJ8000U",
   "nextPosition":1
}

Push URL

Use this operation to push a web page to the agent.

Operation

Operation pushUrl
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
pushUrl string yes URL to push to the agent. For example: "http://www.genesys.com"

Example

Example of request.

var channel ="/service/chatV2/customer-support";
var pushUrlData ={
    "operation": "pushUrl",
    "pushUrl": "http://www.genesys.com",
    "chatId": "00048aAPEQJ8000U",
    "userId": "007555677B20000A",
    "secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, pushUrlData );

Example of notification response:

{
    "messages": [
        {
            "from": {
                "nickname": "John Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 2,
            "text": "http://www.google.com",
            "type": "PushUrl",
            "utcTime": 1493250733000
        }
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 3
}

Update Nickname

Use this operation to update the customer's nickname.

Operation

Operation updateNickname
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
nickname string yes New nickname. For example: "John Doe 2"

Example

Example of request:

var channel = "/service/chatV2/customer-support"
...
var updateNicknameData = {
"operation":"updateNickname",
"nickname" : "MyNewNickname",
"chatId" : "00048aAPEQJ8000U",
"userId":"007555677B20000A",
"secureKey":"4ee15d7e1c343c8e"
}
cometd.publish( channel, updateNicknameData );

Example of notification response:

{
"messages":[{
     "from":{"nickname":"MyNewNickname","participantId":1,"type":"Client"},
     "index":8,
     "text":"MyNewNickname",
     "type":"NicknameUpdated",
     "utcTime":1493936549000
     }],
"chatEnded":false,
"statusCode":0,
"alias":"117",
"secureKey":"3e2a69d421ae2672",
"userId":"007555677CB4000D",
"chatId" : "00048aAPEQJ8000U",
"nextPosition" : 9
}

Custom Notice

Use this operation to send a custom notice to the agent. The agent will need a customized desktop that can process this notice.

Operation

Operation customNotice
Parameter Type Mandatory Description
chatId
Deprecated in 8.5.112
long yes The chat ID. For example: "00048aAPEQJ800U"
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
message string no Optional message.

Example

Example of request message:

var channel = "/service/chatV2/customer-support"
...
var customNoticeData = {
 "operation":"customNotice",
 "message" : "ORDER UPDATE",
 "chatId" : "00048aAPEQJ8000U",
 "userId":"007555677B20000A",
 "secureKey":"4ee15d7e1c343c8e"
}
cometd.publish( channel, customNoticeData );

Example of notification response:

{
    "messages": [
        {
            "from": {
                "nickname": "John Smith",
                "participantId": 1,
                "type": "Client"
            },
            "index": 8,
            "text": "ORDER UPDATE",
            "type": "CustomNotice",
            "utcTime": 1493510733000
        }
    ],
    "chatEnded": false,
    "statusCode": 0,
    "alias": "117",
    "secureKey": "3e2a69d421ae2672",
    "userId": "007555677CB4000D",
    "chatId" : "00048aAPEQJ8000U",
    "nextPosition": 9
}

Update User Data

Use this operation to modify or add attached data to the chat session.

Operation

Operation updateData
Parameter Type Mandatory Description
userId
Deprecated in 8.5.112
long yes The user ID. For example: "007555677B20000A"
secureKey long yes Secure key. For example: "4ee15d7e1c343c8e"
alias
Deprecated in 8.5.112
string yes Chat host alias. For example: "117"
userData JSON-formatted string no Any attached data that the client wants to add to the chat session. For example: { "key":"value", ... }

Example

Example of request message:

var channel = "/service/chatV2/customer-support"
...
var updateUDData = {
"operation":"updateData",
"chatId" : "00048aAPEQJ8000U",
"userId":"007555677B20000A",
"secureKey":"4ee15d7e1c343c8e",
"userData" : { "key3" : "value3", "key4" : "value4" }
}
cometd.publish( channel, updateUDData );

Example of notification response:

{
"messages":[],
"chatEnded":false,
"statusCode":0,
"alias":"117",
"secureKey":"3e2a69d421ae2672",
"userId":"007555677CB4000D",
"chatId" : "00048aAPEQJ8000U",
"nextPosition" : 9
}

Chat Session File Management

Updated in 8.5.112

Starting with release 8.5.112, 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.

File Management requests are all POST requests submitted to a single URL endpoint:

POST /genesys/2/chat-ntf

Each request must include at least the operation and secureKey parameters.


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 Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded


Input Parameters

Parameter Name Sample Value Description Required/Optional
operation "fileGetsLimits" user ID Required
secureKey "8b31761b2154884c" secure key Required


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-ntf
 
operation=fileGetsLimits
secureKey=8b31761b2154884c

Output

{
  "messages": [
        {
            "from": {
                "nickname": "JohnS",
                "participantId": 1,
                "type": "Client"
            },
            "text": "file-client-cfg-get",
            "type": "Notice",
            "utcTime": 1497840553000,
            "userData": {
                "download-attempts": "10",
                "upload-max-files": "3",
                "delete-file": "odd",
                "upload-max-file-size": "2097152",
                "used-download-attempts": "0",
                "used-upload-max-total-size": "0",
                "upload-need-agent": "true",
                "used-upload-max-files": "0",
                "upload-max-total-size": "5242880",
                "upload-file-types": "bmp:csv:doc:docx:gif:htm:jpg:pdf:png:ppt:pptx:tif:txt:xls:xlsx"
            }
        }
    ],
  "chatEnded": false,
  "statusCode": 0,
  "secureKey": "799c5ff0faccd5bb"
}


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 Header Value
Content-Type multipart/form-data


Input parameters
Parameter Name Sample Value Description Required/Optional Source
operation fileUpload secure key Required Form
secureKey "8b31761b2154884c" secure key 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-ntf
 
operation=fileUpload
secureKey=8b31761b2154884c
file=<some file to upload>

Output

{
  "chatEnded": false,
  "statusCode": 0,
  "secureKey": "77cd1c487b67fefb",
  "userData": {
    "file-id": "00F057DB0FF10005"
  }
}

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 that a file was upload.

HTTP Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded


Parameter Name Sample Value Description Required/Optional Source
operation fileDownload Required Form
secureKey "8b31761b2154884c" secure key Required Form
fileId "00048aAPEQJ8ABCD" File to be downloaded from the session Required URL


Example

http://localhost:8080/genesys/2/chat-ntf
 
operation=fileDownload
secureKey=8b31761b2154884c
fileId=00048aAPEQJ8ABCD


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-ntf'>
 <input name='secureKey' value='6b46a7a8910f21be' type='hidden'>
<input name='fileId' value='00F057C8B6B7004D' type='hidden'>
 <input name='operation' value='download' 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.

HTTP Header Value
Content-Type
  • multipart/form-data
  • application/x-www-form-urlencoded
Parameter Name Sample Value Description Required/Optional Source
operation "fileDelete" user ID Required Form
secureKey "8b31761b2154884c" secure key Required Form
fileId "00048aAPEQJ8ABCD" The file to be deleted. Required URL

Example

POST /genesys/2/chat-ntf
 
operation=fileDelete
fileId=007553863DC30029
secureKey=8b31761b2154884c


Output

{
  "chatEnded": false,
  "statusCode": 0,
  "secureKey": "ad437d2338d09d09"
}

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on 14 June 2018, at 05:09.