En GMS 8.5.2 API Book

This PDF is generated from authoritative online content, and
is provided for convenience only. This PDF cannot be used

for legal purposes. For authoritative understanding of what
is and is not supported, always use the online content. To
copy code samples, always use the online content.
Genesys Mobile Services API

Reference
Genesys Mobile Engagement 8.5.2
4/25/2022
Table of Contents
Genesys Mobile Services API Reference 3
New in This Document 6
Storage API 7
Storage API HTML Sample 14
Node API 18
Notification API 20
Chat APIs 29
Chat API Version 1 30
Chat API Version 1 Push Notification and Background State 71
Pattern Matcher API 94
Service API 99
Calendar Service API 114
Capacity API 117
Callback Services API 131
Digital Channels API 202
Chat API Version 2 via CometD 221
Email API Version 2 253
Open Media API 256
API Responses 264
Phone Number Validation API 272
Stat Service API 278
Push Notification Service 326
Callback Push Notifications for Android 338
Callback Push Notifications for iOS 344
Localization File 351
Genesys Mobile Services API Reference

Genesys Mobile Services contains multiple APIs, each dedicated to performing certain tasks as
described below. Select the API name for a more detailed examination of the operations and
responses they use.
• Storage API — Storage is a general-purpose API that allows users to temporarily store arbitrary data.
Data may consist of key/value pairs of strings or binary objects.
• Node API — This is a base ping API implementation which will be used by load balancers to determine
the health of a given GMS node to determine if it can use this GMS node when it loads balancing API
requests across the set of GMS nodes.
• Notification API — This set of event-driven APIs is used to manage notifications between applications
and Genesys systems. Users subscribe to an event and provide an indication of how the notification
should be delivered, then events are published to the system.
Important
This API is only intended to be used with Orchestration Server-based Services, not
from external mobile applications.
• Chat APIs — This API is used by customer-facing applications to create and manage a chat session
associated with a contact center–related service. A single service is associated with a single chat.
• Email API — This API is used by customer-facing applications to create and manage an email message
associated with a contact center–related service. A single service is associated with a single email.
• Service API — This API is used by customer-facing applications to manage different types of contact
center-related services.
• Callback Services API — This API handles call back services, such as initiating, canceling, rescheduling,
and queries. Other Callback-related APIs are the following:
• Calendar Service API — The Calendar Service API queries for all office hours so that your mobile app
can make an intelligent first offer to the user based on what's available in the next couple days, or
with an explanatory hint such as "Our offices are open from 8:00 am to 5:00 pm, please enter the
desired time.".
• Capacity API — The Capacity Service enables you to define the number of scheduled callbacks that
are allowed for Callback for a given time slot in the week. Then, your Callback service refers to your
Capacity service and to your Office Hours service to adjust the agent availability and the number of
scheduled callbacks.
• Digital Channels API — These APIs allow Genesys Mobile Engagement to work with Genesys digital
channels such as chat, email, and open media.
• Chat API Version 2
• Chat API Version 2 for CometD

• Email API
• Open Media API
• Stat Service API — This API is used to interact with the Genesys Statistics Server (Stat Server). The API
provides the request so an application can get statistics related to the Contact Center.
• Pattern Matcher API — This API allows you to create and manage pattern lists that you can use to check
parameter values and define exceptions in your GMS service.
• Phone Number Validation API — This API wraps Google's common Java, C++, and JavaScript library for
the purposes of parsing, formatting, and validating international phone numbers.
Additional Information
• Push Notification Service — Contains useful information about the Push Notification service.
• Localization File — The localization file enables you to customize the way you send a message to
subscribers.
• New in This Document — Provides a document change history.
Authentication Header
The following services require Authentication Header.
Service Requires Authentication Header?

Statistic Service Yes.
Only for queries to /genesys/admin/1/node/
Node Service
status.
Callback Service Depends on the configuration.
Storage Service Depends on the configuration.
Notification Service Depends on the configuration.
Learn about Templates, Scenarios, and APIs

Available templates, scenarios, and APIs
Template Name Detailed Built-in Related API(s)
Node API to check GMS nodes
Get Service (get.zip) Get and Basic Get Services health and manage your nodes:
start, suspend, stop.
• Service API to check that a

Match Interaction (match- voice call with an existing
Match interaction
interaction.zip) GMS service is associated
with the access number.

Template Name Detailed Built-in Related API(s)
• Storage API to allow users to

temporarily store arbitrary
data. Data may consist of
key/value pairs of strings or
binary objects.
Calendar Service API to create

Office Hours Office-hours and manage office hours, special
events, and more.
Request Access Request-access Service API to request resources.
Create a chat session in the Chat
Request Chat
Server using the Chat API v1.
Simple Voice Inbound–Immediate
Request Interaction See the scenario page.
Call
Stat Service API to query URS
URS Statistic (urs-stat.zip)
Stat.
Query to create an inbound
User Originated Immediate
immediate service.
Query to create an inbound delay
User Originated Delayed
service.
Chat Immediate Chat APIs
Callback (callback.zip) Chat Delayed Chat APIs
User Terminated Immediate Callback Services API
User Terminated Delayed Callback Services API
User Terminated Scheduled Callback Services API.
User Terminated Delayed Agent
Callback Services API
Preview
Capacity API to manage Agent
Capacity (capacity.zip) Capacity
availability.

Genesys Mobile Services API Reference New in This Document
New in This Document

The following topics have been added or changed in the GMS 8.5.201.04 release:
• The Delete Callback query has been added to support the Forget Me (GDPR) Scenario.
• The Read Receipt query has been added to the Chat v2 and Chat v2 Comet D APIs.
The following topics have been added or changed in the GMS 8.5.200.07 release:
• The Start or Schedule Callback query can now redial a COMPLETED callback by submitting its ID.
• The Callback Services and Stat Service API query now return detailed information in errors.
• The EWT APIs have been modified.

Genesys Mobile Services API Reference Storage API
Storage API
Overview
The Storage API is a general purpose API that allows users to temporarily store arbitrary data. Data
may consist of key/value pairs of strings or binary objects.
For security reasons, if you plan using the GMS Storage API, you can define a list of supported mime
types in the allowed-mime-types option and configure allow-file-control = true to enable file control.
API
Create
Allows the creation of a new storage area in Genesys Mobile Services (GMS).
Starting 8.5.103.xx, this operation requires the gms_user header to be passed to associate the
custom_id to the customer. To retrieve the stored value, you also need to pass the gms_user header.
Operation
Method POST
URL /genesys/1/storage/custom/{customId}/{ttl}
Parameter Type Mandatory Description
URI Parameters
Custom ID of the
{customId} string yes storage. Available
starting 8.5.103.xx
The time to live for this
data, specified in
seconds. The data is
automatically deleted
after it has been stored
{ttl} number yes for {ttl} seconds. The
ttl must be greater than
zero (0). If an incorrect
value is specified, a
default of 30 seconds is
defined.
Body: A MultiPart form or a URL encoded form consisting of different items representing the key/value
pairs to store.

Response
A JSON object with the property id, identifying the assigned id for this storage request.
HTTP code 200

HTTP message OK
Example
The following example stores:
• Key1, Key2, Key3 and FileKey
The time-to-live of the data is 1 hour.
Operation
Request URL:
http://localhost:8080/genesys/1/storage/3600
Request Method:POST
Status Code:200 OK
Request Headersview source
Accept:*/*
Accept-Charset:ISO-8859-1,utf-8;q=0.7,*;q=0.3
Accept-Encoding:gzip,deflate,sdch
Accept-Language:en-US,en;q=0.8
Connection:keep-alive
Content-Length:13028
Content-Type:multipart/form-data;
boundary=----WebKitFormBoundaryy16qocbN6tmPORZL
Host:localhost:8080
Origin:http://localhost:8080
Referer:http://localhost:8080/genesys/resources/storagetest.html
User-Agent:Mozilla/5.0 (Windows NT 6.1; WOW64)
AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Request Payload
------WebKitFormBoundaryy16qocbN6tmPORZL
Content-Disposition: form-data; name="Key1"
Value1
Value2
Value3
Content-Disposition: form-data; name="FileKey"; filename="MyPic.png"
Content-Type: image/png
------WebKitFormBoundaryy16qocbN6tmPORZL--
Result
The above data is now stored up to 1 hour with an id of 39a98e24-b03b-4191-b756-1efe8f3b16b8.
HTTP 200 OK
{ "id":"39a98e24-b03b-4191-b756-1efe8f3b16b8" }

Update
Updates a storage area that has already been created in GMS.
Operation
Method POST
URL /genesys/1/storage/{id}/{ttl}
URI Parameters
The id of the allocated
{id} string yes
storage to be updated.
The time to live for this
data, specified in
seconds. The data is
automatically deleted
after it has been stored
{ttl} number yes for {ttl} seconds. The
ttl must be greater than
zero (0). If an incorrect
value is specified, a
default of 30 seconds is
defined.
Body: A MultiPart form consisting of different items representing the key/value pairs to store. This may
be string values or files.
Response
HTTP code 200

HTTP message OK
Example
The following example updates the keys:
• Key1, Key2, Key3 and FileKey
The time-to-live for all of the keys in this update is 1 hour.
Operation
Request URL:
http://localhost:8080/genesys/1/stor
age/b8e8eb60-3f14-493d-90da-0034aca34b55/3600
Request Method:POST
Status Code:200 OK
Accept:*/*

boundary=----WebKitFormBoundaryPu8S1YopPtZq8Z54
Host:localhost:8080
Referer:http://localhost:8080/genesys/resources/storagetest.html
AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Request Payload
------WebKitFormBoundaryPu8S1YopPtZq8Z54
Value6
Value7
Value8
Content-Disposition: form-data; name="FileKey"; filename="0016_001.pdf"
Content-Type: application/pdf
------WebKitFormBoundaryPu8S1YopPtZq8Z54--
Response Headersview source
Cache-Control:no-cache
no-store
Content-Length:2
Content-Type:application/json
Date:Sat, 04 Feb 2012 02:06:43 GMT
Pragma:no-cache
Server:Apache-Coyote/1.1
Result
The above data is now stored for up to 1 hour with an id of
39a98e24-b03b-4191-b756-1efe8f3b16b8.
HTTP 200 OK
Query (all keys)

Queries all of the keys in a storage area that has already been created in GMS.
Operation
Method GET
URL /genesys/1/storage/{id}
URI Parameters
{id} string yes
Body: Not used

Response
HTTP code 200

HTTP message OK
Example
The following example queries all of the keys associated with id

b8e8eb60-3f14-493d-90da-0034aca34b55
Operation
Request URL:
http://localhost:8080/genesys/1/storage
/b8e8eb60-3f14-493d-90da-0034aca34b55
Request Method:GET
Result
{"Key2":"Value7","Key1":"Value6","Key3":"Value8",
"FileKey":"http://127.0.0.1:8080/genesys/1/storage/binary/
b8e8eb60-3f14-493d-90da-0034aca34b55/FileKey"
}
Query (one key)

Queries one of the keys in a storage area that has already been created in GMS.
Operation
Method GET
URL /genesys/1/storage/{id}/{key}
URI Parameters
{id} string yes
The key of the
{key} string yes specifically requested
value
Body: Not used
Response
HTTP code 200

HTTP message OK
Example
The following example queries the value of Key1 from the data associated with id

b8e8eb60-3f14-493d-90da-0034aca34b55
Operation
Request URL:
/b8e8eb60-3f14-493d-90da-0034aca34b55/Key1
Request Method:GET
Result
Value1
Query (one binary key)

Queries one of the keys in a storage area that has already been created in GMS.
Operation
Method GET
URL /genesys/1/storage/binary/{id}/{key}
URI Parameters
{id} string yes
The key of the
value
Body: Not used
Response
HTTP code 200

HTTP message OK
Body The file that was stored for the specified key
Example
b8e8eb60-3f14-493d-90da-0034aca34b55
Operation
Request URL:
http://localhost:8080/genesys/1/storage/binary
/b8e8eb60-3f14-493d-90da-0034aca34b55/FileKey
Request Method:GET

Delete
Deletes all of the keys in a storage area that has already been created in GMS.
Operation
Method DELETE
URL /genesys/1/storage/{id}
URI Parameters
{id} string yes
storage to be deleted.
Body: Not used
Response
HTTP code 200

HTTP message OK
Example
The following example deletes all of the keys associated with id

b8e8eb60-3f14-493d-90da-0034aca34b55
Operation
Request URL:
/b8e8eb60-3f14-493d-90da-0034aca34b55
Request Method:DELETE
Samples
Storage API HTML Sample
Notes
Keys may not begin with an underscore (_).

Storage API HTML Sample

<meta http-equiv="content-script-type" content="text/javascript">

<script src="http://code.jquery.com/jquery-1.7.1.min.js"
type="text/javascript"></script>
<script type="text/javascript">
jQuery.support.cors = true;
var storageId = "";

var defaults = {
Key1: 'Value1',
Key2: 'Value2',
Key3: 'Value3',
FileKey: 'FileKey',
ttl: 3600,
CreateData: '{ "a":"valuea", "b":"valueb", "c":"valuec" }',
UpdateData: '{ "a":"new_valuea", "d":"new_valued" }'
};
function doPost( url, callback )
{
var data = new Object();
data[ 'a' ] = $("#Key1").val();
data[ 'b' ] = $("#Key2").val();
data[ 'c' ] = $("#Key3").val();
$.post( url, data, callback );

return;
}
function query() {
$.get( '/genesys/1/storage/' + storageId, function(data) {
$("#query_result_label").text( JSON.stringify( data ) );
});
}
function create() {
doPost('/genesys/1/storage/' + $("#ttl").val(), function( result ) {
storageId = result.id;
$("#storage_id_label").text( storageId );
});
}
function update() {
if ( storageId == '' ) return;
doPost('/genesys/1/storage/' + storageId + "/" + $("#ttl").val() );
}
function del() {

$.ajax({
type: 'DELETE',
url: '/genesys/1/storage/' + storageId
});
}
$(function(){
$("#Control input").each(function () {
$(this).val(defaults[this.id]);
});
$("#create").click(function () {
create();
});
$("#query").click(function () {
query();
});
$("#update").click(function () {
update();
});
$("#delete").click(function () {
del();
});
});
</script>
<b>GSG Storage Test Controls</b>
<div id="Control">
<div>
<label for="ttl">TTL</label><input id="ttl">
</div>
<div>
<label for="Key1">Key1</label><input id="Key1">
</div>
<div>
</div>
<div>
</div>
</div>
<button id="create">Create</button>
<button id="update">Update</button>
<button id="query">Query</button>
<button id="delete">Delete</button>
<p />

<div>Storage id:</div>
<div id="storage_id_label"></div>
<div>Query results:</div>
<div id="query_result_label"></div>
<div></div>

Genesys Mobile Services API Reference Node API
Node API
This is a base ping API implementation, which load balancers will use to check the health of a given
GMS node to determine if it can use this particular GMS node when it load balances API requests
across the set of GMS nodes.
Query Status
This API queries the status of a given GMS node. The application (load balancer) querying the nodes
must have their explicit host addresses and port.
Operation
Important
You need an Authentication header for this query.
GET /genesys/1/admin/node/status
URI Parameters
None
Response
HTTP code 200

HTTP message OK
The response is a string representing the status of
Body GMS ONLINE/OFFLINE (OFFLINE means that GMS
will stop in the next few seconds.
Example
$ curl -v -u default:password
http://localhost:8080/genesys/1/admin/node/status
< HTTP/1.1 200 OK
< Expires: Thu, 11 Aug 2016 10:59:27 GMT
< Set-Cookie: JSESSIONID=1nglubvlfu69bzw6lvksz6jo2;
Path=/genesys;HttpOnly
< Cache-Control: max-age=300
< Content-Type: text/plain;charset=ISO-8859-1
< Content-Length: 6

Genesys Mobile Services API Reference Node API
<
ONLINE
Change Node Status

This API allows you to change the status of a GMS Node to offline or online. If a load balancer queries
the node, it will get the new GMS status and will load balance the request accordingly.
If you set the GMS Node status to OFFLINE, the node's status will be Suspended in Solution Control
Server.
Query
Important
You need an Authentication header for this query.
POST /genesys/1/admin/node/changestatus/{status}
URI Parameters
Status String yes ONLINE/OFFLINE
Response
HTTP code 200

HTTP message OK
Example
POST /genesys/1/admin/node/changestatus/OFFLINE HTTP/1.1
Host: 127.0.0.1:8080
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
200 OK

Genesys Mobile Services API Reference Notification API
Notification API
Overview
Important
Do not use the Publish part of this API from a mobile device. The API is designed and
intended for use only from Orchestration Server-based Services. In release 8.1.100.28,
Comet was added as a notification subscription for device_os parameters.
This set of APIs manages notifications between applications and Genesys systems. It is event-driven,
that is, consumers subscribe to an event and indicate how to deliver the notification, and events are
published to the system. For the GMS delayed use case, it can work as follows:
1. The mobile application triggers a subscription for an ORS event; something like ors.contact.12345678;
the application specifies the device id and the type (for example, iOS).
2. When ORS determines that an agent is available, or will soon be available, it will push a message to
GMS with the event ors.contact.12345678.
3. GMS pushes the message to the mobile device.
Structures
The following are the API data structures. All structures are in JSON format. The servlet expects JSON,
so queries need to provide application/json content type. Its absence or incorrect value can result
in a 415 (Unsupported Media Type) error.
Subscription
The subscription data identifies the subscriber of the given set of events.
Subscription Request
{ "subscriberId":"${subscriberId}",
"providerName":"${providerName}",
"notificationDetails":{
"deviceId":"${id}",
"properties":
{"${key2}":"${val2}",
"debug":"${debug}",
"${key1}":"${val1}"},
"type":"${type}"},
"authorization": "ZGVtbzo=",

"expire":30,
"filter":"${filter}"
}
Property Mandatory Description

subscriberId yes The ID of subscriber.
Authorization parameter to add
to the HTTP headers of the
authorization no request if basic authorization is
required on the custom HTTP
channel.
Time, in seconds, after which the
expire no subscription expires (optional;
default value is configurable).
The filter which is applied to the
tags of incoming events. If the
filter matches the tag, the
system publishes the event to
filter yes
the destination specified by the
subscription. Note: The event is
published to ALL subscriptions
which match the filter.
Name of the provider for the
given subscription. If not
providerName no specified, the subscription is
registered for the default
provider.
Language used by this
subscription. If missing, GMS
handles the localized strings as
language no normal messages. See Genesys
Mobile Services
PushNotificationService for
details about languages.
Information needed for delivering
the event to the subscriber.
• type–(Mandatory) Notification
mechanism that the
application requires. Valid
values are ios, android,
gcm, comet, httpcb
(callback POST to the
provided URL), and orscb
notificationDetails yes (callback to ORS), wns (to-
wns-client) (see more
information here).
• deviceId – (Mandatory) ID of
the device to deliver a
message to (in the case of
HTTP or ORS callback; see
Push Notification Service for
further details.

Property Mandatory Description
• properties – (Optional) The

String-String map of
additional properties used for
delivering the notification. If
the information provided is
incomplete from the
publisher standpoint, GMS
returns an error.
• debug – true if the production
or debug provider connection
must send the notifications.
The subscription is sent to
the debug channel if the
${debug} value is debug or
true.
Note: For comet subscriptions, the gms_user header is required. For example, here is a request for
an android push notification subscription (note the absence of the properties entry):
{"subscriberId":"$The_subscriber_9774",
"deviceId":"9774d56d682e549c",
"type":"android"},
"expire":30,
"filter":"ors.context.123456"}
Subscription Response
If OK:
{"id":"${id}"}
- returns the ID of created subscription.
Event
Internal components are required to publish the events. The Notification service matches the event to
the subscription using the event's tag and subscriptions filters and notifies the subscriptions with
matching filters. The event structure is formatted as follows:
{
"message":"${message}",
"tag":"${tag}",
"mediaType":"${mediaType}",
"notificationDetails":
{
"deviceId":"${devideId}",
"type":"${type}",
"properties":
{
"debug":"{true/false}"
}
}

Where:
Parameter Mandatory Description

tag yes The message tag.
A string message. It may contain
the string representation of ANY
data: the notification service is
message-agnostic and always
interprets the message as a
string. If you do not add a
message, an empty string is sent
message no to the subscribers. Make sure
that the message content is
correctly formatted if you use
some JSON representation string.
If the message breaks the JSON
parser which attempts to parse
the request body, GMS replies
with a BAD_REQUEST response.
"string" for a simple string,
"localizestring" for a string with
mediaType no a localized parameter, and json
for a JSON payload in the
message. See Localization File.
This is the name of the provider
that this subscription is for. If not
providerName no
specified, the subscription is for
the default provider.
If missing, notification is sent to
default subscribers. It allows
notificationDetails no
sending the notification to a
specific device.
The ID of the device (for
devideId yes example, Android device ID or
iPad ID).
type yes Type of notification (gcm, ios...).
properties no Additional properties.
If true, displays the debug log for
debug no
this notification.
Filters and Tags

The tag cannot be null or an empty string. The format of tag, specified in the event, matches the java
package name alphanumeric string with '.' delimiters.
• Underscores are allowed.

• The first symbol may be number.

• Only English alphanumeric chars are allowed.
The filter cannot be null or an empty string. The format of filter entry is similar to the tag format, but
in addition, it allows wildcard '*' after last '.' (or only '*' which indicates a subscription to all events)
and the last character cannot be '.'. So, the channels formatted as follows are allowed:
• * - subscription to all channels

• ors.* - subscriptions to all channels starting with ORS.
• ors.events.agentavailabilty.context.1234560 – Subscription to the only specified channel.
When publishing event, the tag is matched versus the filters of all active
subscriptions and GMS notifies all matching subscriptions. For example,
consider the Notification Event published with tag
ors.agentavailability.agent123.available. Such notification will be
propagated to the subscriptions with any of the following filters:
• *
• ors.*
• ors.agentavailability.*
• ors.agentavailability.agent123.*
• ors.agentavailability.agent123.available
APIs
The standard InternalServerError with code 500, or BAD_REQUEST with code 400, can be returned
as response to each request, so it is not mentioned in further descriptions (except in some cases
when the syntax of body is involved). Notes: All POST requests must use the media type
application/json.
Create Subscription
This API allows an application to subscribe to a given set of events.
Operation
POST /genesys/{api version}/notification/subscription

Body: JSON with subscription (see above)
Response
Success

HTTP code 200

HTTP message OK
A JSON object with the property id, identifying the assigned id

Body for this storage request.
Errors
• In the case of incorrect request syntax (see requirements above) the BAD_REQUEST error will be
returned.
HTTP code 400

HTTP message BAD REQUEST
• If the subscription is being created for a push type which is not enabled for now, GMS returns the
NOT_FOUND error.
HTTP code 404

HTTP message NOT FOUND
Delete Subscription
This API cancels/terminates a given subscription.
Operation
DELETE /genesys/{api version}/notification/subscription/{subscription-id}

URI Parameters
The ID of the
{subscription-id} String yes
subscription to cancel.
Response
Success
HTTP code 200

HTTP message OK
Error If a problem occurs during subscription removal, the following status code is returned:
HTTP code 404

HTTP message Not Found
{"message":"Subscription ID not found",
Body
"exception":"com.genesyslab.gsg

HTTP code 404
.services.notification.SubscriptionNotFoundException"}
Delete subscription for given subscriber

This API cancels/terminates all the subscriptions for a given subscriber.
Operation
DELETE /genesys/{api version}/notification/subscription/subscriber/{subscriberId}

URI Parameters
The ID of the subscriber
{subscriberId} String yes whose subscriptions will
be cancelled.
Returns
Success
HTTP code 200

HTTP message OK
Error
If a problem occurs during removing subscriptions of the subscriberId, the following status code is
returned:
HTTP code 404

{"message":"Subscriber ID not found",
"exception":
Body
"com.genesyslab.gsg.services.notification
.SubscriberNotFoundException"}
Publish Event
To publish an event or a message, your application can use one of the following workflows:
• Publish the event to the subscriber ID, if the subscription ID is not null.
• Publish the event to the device ID or type or [provider] if the device ID is not null.
• Publish the event to all subscriber IDs which registered to a channel like
service.chat.refresh.<service_ID> using the tag parameter.

Operation
POST /genesys/{api version}/notification/publish

Body: JSON event (see the example below.)
The message to publish. For example a string or a
message
JSON map of key/value pairs.
The channel, for example,
tag service.chat.refresh.<service_ID>", where the
event should be published.
The media type. The following values are
mediaType
supported: MAP, STRING, or LOCALIZE_STRING.
language The language used to publish the message.
localized arguments A map of key/value pairs for localization.
The prefix name of the push section defined in the
GMS options: push.provider.<provider name>. If
providerName
null, the system uses the default provider
configured in the GMS push section.
notificationDetails.deviceId The device ID (android or ios).
Type of the device where the message is published.
The supported values are: ios, gcm/fcm,
notificationDetails.type
httpcb, orscb, comet, java, customhttp,
wns.
Additional properties for device type such as
notificationDetails.properties
"debug":"{true/false}"
Unique subscriber ID where the message should be
subscriptionId
published.
Example
The following example sends a message to iOS, with a different alertMessage.body parameter:
POST /genesys/1/notification/publish HTTP/1.1

Host: 172.25.157.93:8080
gms_user: 4f295ba0c0f0a7f1e5ef068bf1d0732e0e70fda7c443081bb3cc5698fa
9a276c
Content-Type: application/json
{
"message": "Agent availability",
"tag": "gms.notification.agentstatus",
"mediaType": "STRING",
"notificationDetails": {
"deviceId": "XXXXXXXXXXXXXXXXXXXXXX",
"type": "ios",
"properties": {
"apple.alertMessage.body": "Agent is available.",
"apple.badge": 9,
"apple.sound": "bingbong.aiff",
}
}
}

Response
Success
HTTP code 200

HTTP message OK
Errors
In case of an incorrect request body syntax, GMS returns BAD_REQUEST.
HTTP code 400

HTTP message BAD REQUEST
The error code 503 appears in one of the following conditions.
• Failure of HTTP Post action to the specified URL.

• The server did not return 200 status code.
• Network issues.
• Error from APNS and C2DM due to authorization issues or temporary service unavailability for C2DM.
HTTP code 503

HTTP message SERVICE UNAVAILABLE

Genesys Mobile Services API Reference Chat APIs
Chat APIs
Starting in 8.5.114, Chat API version 2 is available for both Web and Mobile App development.
• Chat API version 2: Use this API for Chat initiated by Web and Mobile App clients. Genesys recommends
that you use this API for new deployments. New features will be added to Chat API version 2 only.
• Chat API version 1: This API is documented to support older deployments. Genesys recommends that
you upgrade to Chat API version 2 if you are still using Chat API version 1.

Chat API Version 1
Important
This API is documented to support older deployments. Genesys recommends that you
upgrade to Chat API version 2 if you are still using Chat API version 1.
Prerequisites
Before using the Chat API described on this page, you must configure your Genesys Mobile Services
deployment correctly. Then, before you can create Chat sessions, you must create your chat service
(of type ors or builtin) with the Service Management UI. Then, you will be able to use this chat
service to request chat session IDs.
Getting Started
The Chat API is used by customer-facing applications to create and manage a chat session associated
with contact center-related services.
Basic Chat
To start chat session:
• Create the built-in service of type request-chat that provides the Basic Chat Service API.
• Use the Basic Chat Service API to create a Chat Service ID for each chat session. The built-in request-
chat service created in the Service Management UI provides the Basic Chat Service API.
Then, you can use the Chat Service ID to perform queries for your chat session.

Chat API Version 1 (Genesys Mobile Services-Based) allows an application to pass business context
data in the service creation request, using the fixed service name request-chat.
• No corresponding Orchestration Server (ORS) session will be created.

• Data is preserved by Genesys Mobile Services using the specified time-to-live parameter (or the
configured default value).
• Chat interaction could be initiated by an application at any point.
• The routing logic associated with the specified interaction endpoint (or the configured default value)
would be responsible for finding an appropriate agent.
• Both polling and async (CometD) modes of message delivery are supported.
• Applications can handle background state through chat push notifications
Tip
When using asynchronous messaging with CometD, all HTTP headers must include the
gms_user header.
ORS-Chat Services
Instead of creating a basic chat service to request chat session IDs, you can configure one of the
following chat service of type ors in the Service Management UI:

• Chat Immediate
• Chat Delayed
Then, use this ors service to retrieve your new service ID associated with your chat session. For
instance if you configured the chat-immediate service, you will post to the chat-immediate service:
POST http://localhost:8080/genesys/1/service/callback/chat-immediate
You can now use this ID in the Chat Interaction APIs.
Structures
The Chat API uses the data structures described in this section (in JSON format) to exchange data.
Requests are accepted in application/json, 'application/x-www-form-urlencoded', or
'multipart/form-data' formats, and responses are returned in 'application/json' format. If an
expected value is missing or incorrect, then your application receives a 415 (Unsupported Media
Type) error.
JSON-Encoding
For each method detailed below, if you wish to use JSON in your body, you must use JSON-encoding
for body capabilities by setting the Content-Type to application/json;charset=UTF-8. For
example, if you use the query for the chat session creation:
Request
POST http://localhost:8080/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/chat
HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json;charset=UTF-8
{
"_verbose":"true",
"first_name":"John",
"last_name":"Doe",
"subject":"GMSDemo",
"userDisplayName":"JohnDoe"
}
Response
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache
Cache-Control: no-store
Content-Length: 1225
{
"chatIxnState" : "CONNECTED",
"transcriptPosition" : "1",

"chatSessionId" : "000F3aBC3NXB001F",
"userId" : "017356D8446D002A",
"secureKey" : "ffe843f41bf1eec2",
"checkChatServiceLoadBalancerPath" : "null",
"chatServerLoadBalancerAlias" : "371",
"chatServerHost" : "bsdemo2012jac",
"chatWebApiPort" : "9002",
"isTLSrequired" : "false",
"clientTimeZoneOffset" : "60",
"_chatIxnAPI_SEND_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/chat/
send",
"_chatIxnAPI_REFRESH_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/
chat/refresh",
"_chatIxnAPI_START_TYPING_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/
ixn/chat/startTyping",
"_chatIxnAPI_STOP_TYPING_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/
chat/stopTyping",
"_chatIxnAPI_DISCONNECT_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/
chat/disconnect",
"_chatIxnAPI_REFRESH_FROM_START_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-
a5b8-f14f99236042/ixn/chat/refresh?transcriptPosition=1",
"_chatIxnAPI_SEND_CUSTOM_URL" : "/genesys/1/service/fb80ed7b-a164-46ef-a5b8-f14f99236042/ixn/
chat/customNotice"
}
Warning
The current implementation supports simple key/value parameters. You cannot
manage complex JSON-structured values such as maps and arrays. See the above
code example above.
Chat Interaction API Resources

The chat interaction is used to represent the current state of the chat session and transcript. This
information is returned in the HTTP response of each API request in poll mode or delivered
asynchronously in push mode (CometD).
Important
You need to create the service session with the basic chat service before you can
create a chat interaction. Since 8.5.1, you can specify push notification parameters to
manage your application's background state (see sections below).
The Chat Interaction Attributes are the following:
• chatIxnState – The current state of the chat session.

• chatSessionId – Session ID associated with the chat.
• transcriptPosition – The current position in the chat dialog or transcript for this user.

• chatServiceMessage – A diagnostic message used for debugging.
The following are only returned if the _verbose parameter in the API request is true:
• userId – User ID assigned by the Genesys Chat Server.

• secureKey – The security key for this chat session.
• checkChatServiceLoadBalancer – Indicates that we should check the chat load balancer for the
appropriate Chat Server to use.
• PathchatServerLoadBalancerAlias – The alias for the Chat Server that is assigned to this chat session
by the Chat Server load balancer.
• chatServerHost – Host name for the Chat Server assigned to this chat session from the Chat Server
load balancer.
• chatWebApiPort – Port number of the Chat Server load balancer
• isTLSrequired – Indicates whether a TLS connection is required for the Chat Server.
• clientTimeZoneOffset – Time zone offset specified by the user client. Could be used to convert UTC
time returned by server into user local time.
• _chatIxnAPI_SEND_URL – URL used to send chat messages for this chat session.
• _chatIxnAPI_REFRESH_URL – URL used to refresh the chat transcript for this chat session.
• _chatIxnAPI_START_TYPING_URL – URL used to indicate that the user started typing a chat message for
this chat session.
• _chatIxnAPI_STOP_TYPING_URL – URL used to indicate that the user stopped typing a chat message for
this chat session.
• _chatIxnAPI_DISCONNECT_URL – URL used to disconnect the user from the chat session.
• _chatIxnAPI_REFRESH_FROM_START_URL – URL used to refresh the chat transcript from the beginning of
the session.
• _chatIxnAPI_SEND_CUSTOM_URL – URL used to send a custom notice to the chat session.
Example of Chat Interaction Resources
/genesys/1/service/{sessionid}/ixn/chat
?notify_by=comet&firstName=Buzz&lastName=Brain
⊂ject=French&email=b.b%40gmail.com
&push_notification_deviceid=deviceid
&push_notification_type=ios
{
"chatIxnState": "CONNECTED",
"chatSessionId": "000C2a7VVQRB001U",
"transcriptPosition": 1,
"chatServiceMessage": "Chat service is available"
}
/genesys/1/service/{sessionid}/ixn/chat?_verbose=true
¬ify_by=comet&firstName=Buzz&lastName=Brain⊂ject=French
&email=b.b%40gmail.com&push_notification_deviceid=deviceid
&push_notification_type=ios

{
"chatIxnState": "CONNECTED",
"chatSessionId": "000C2a7VVQRB001U",
"transcriptPosition": "1",
"chatServiceMessage": "Chat service is available",
"userId": "015E4FD3CD890036",
"secureKey": "b306749dabfa1cf6",
"checkChatServiceLoadBalancerPath":
"/WebAPI812/SimpleSamples812/ChatHA/ChatLBServerInfo.jsp?
chatServerLoadBalancerAlias=350",
"chatServerLoadBalancerAlias": "350",
"chatServerHost": "135.225.51.225",
"chatWebApiPort": "4856",
"isTLSrequired": "false",
"clientTimeZoneOffset": "-420",
"_chatIxnAPI_SEND_URL":
"/genesys/1/service/9d6c31d3-1121-4ba9-91e1-b93c0fa6e32f
/ixn/chat/send",
"_chatIxnAPI_REFRESH_URL":
/ixn/chat/refresh",
"_chatIxnAPI_START_TYPING_URL":
/ixn/chat/startTyping",
"_chatIxnAPI_STOP_TYPING_URL":
/ixn/chat/stopTyping",
"_chatIxnAPI_DISCONNECT_URL":
/ixn/chat/disconnect",
"_chatIxnAPI_REFRESH_FROM_START_URL":
/ixn/chat/refresh?transcriptPosition=1"
}
Chat Transcript Resource

The Chat Transcript Attributes are the following:
• startedAt - Chat interaction start time (in UTC).

• transcriptToShow - An ordered array of transcript events. Each event is represented by another array
of the following format:
[{Event type}, {Agent nickname}, {Chat message}, {Number of seconds from interaction
start}, {Type of user}, {message index}] where:
• Event type: {"Message.Text", "Notice.Joined", "Notice.Left", "Notice.TypingStart",
"Notice.TypingStop", "Notice.PushUrl"}
• Type of user: {"AGENT", "CLIENT", "EXTERNAL"}
Starting in 8.5.105, the message index field has been added to the chat message to indicate the
position of each message in the transcript. Your chat client application can now manage the comet
and the API response channel and merge the messages according to their index in the transcript. This
will avoid duplicate messages on screen. To enable this message index, configure enable-fast-chat-
transcript-refresh = true in the chat section of your GMS configuration.
This example shows how to send messages with their transcript position:

$ curl --data "transcriptPosition=1&message=good"

http://localhost:8080/genesys/1/service
/9f704400-7967-4586-821e-2e2ad5c1585f/ixn/chat/send
{
"chatIxnState" : "TRANSCRIPT",
"chatSessionId" : "000F7aBK86UC001F",
"transcriptToShow" :
[["Notice.Joined","Kristi Sippola","has joined the session",
"21","AGENT","2"],
["Message.Text","127.0.0.1","good","35","CLIENT","3"]],
"startedAt" : "2016-06-01T14:51:37Z"
}
$ curl --data "transcriptPosition=4&message=right"

/9f704400-7967-4586-821e-2e2ad5c1585f/ixn/chat/send
{
"chatIxnState" : "TRANSCRIPT",
"chatSessionId" : "000F7aBK86UC001F",
"transcriptToShow" :
[["Notice.TypingStarted","Kristi Sippola",
"user is typing","55","AGENT","5"],
["Message.Text","Kristi Sippola","position 2","57","AGENT","6"],
["Notice.TypingStarted","Kristi Sippola",
["Message.Text","Kristi Sippola","hello","57","AGENT","8"],
["Message.Text","Kristi Sippola","allo","58","AGENT","10"],
["Message.Text","Kristi Sippola","bonjour","58","AGENT","12"],
["Message.Text","Kristi Sippola","Hallo","59","AGENT","14"],
["Message.Text","127.0.0.1","right","65","CLIENT","15"]],
"startedAt" : "2016-06-01T14:51:37Z"
}

Important
The index data set of the transcript allows missing numbers due to configurable
filtering events system. For example, if you have index series like "1, 3, 4, 5, 7", the
unavailable "2, 6" index numbers can be filtered events).
Refresh Chat Transcript Examples
/genesys/1/service/{sessionid}/ixn/chat/refresh?message=hello%20agent
{
"chatIxnState": "TRANSCRIPT",
"chatSessionId";:"000BRa84KRFB00BK",
"transcriptPosition": 5",
"transcriptToShow":
[["Notice.Joined","ksippo","has joined the session","35","AGENT"],
["Notice.TypingStarted","ksippo","is typing","42","AGENT"],
["Message.Text","ksippo","hello customer","48","AGENT"],
["Message.Text","VasyaP","hello agent","71","CLIENT"]]",
"startedAt": 2012-06-09T06:15:35Z"
}
/genesys/1/service/{sessionid}/ixn/chat/refresh?_verbose=true &message=hello%20agent
{
"chatSessionId":"000BRa84KRFB00BK",
"transcriptToShow": [
[
"Notice.Joined",
"ksippo",
"has joined the session",
"15",
"AGENT"
],
[
"Message.Text",
"VasyaP",
"hello agent",
"26",
"CLIENT"
],
[
"Notice.TypingStarted",
"ksippo",
"is typing",
"57",
"AGENT"
],
[
"Message.Text",
"ksippo",
"hello customer",

"61",
"AGENT"
]
],
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",
"/WebAPI812/SimpleSamples812/ChatHA/ChatLBServerInfo.jsp
?chatServerLoadBalancerAlias=350",
"chatServerHost": "135.225.51.225",
/ixn/chat/send",
/ixn/chat/refresh",
/ixn/chat/refresh?transcriptPosition=1"
}
Basic Chat Service Resources

Basic Chat: genesys/1/service/request-chat
{
"_id": "a7e6ed0b-0380-4223-97f8-b3c7d93205e8"
}
Basic Chat: genesys/1/service/request-chat?_verbose=true
{
"_chatIxnAPI-CREATE-URL":
"/genesys/1/service/a7e6ed0b-0380-4223-97f8-b3c7d93205e8/ixn/chat",
"_id": "a7e6ed0b-0380-4223-97f8-b3c7d93205e8"
}
Basic Chat Service API
Create basic chat service

This API allows the application to create basic chat service session and then initiate chat interaction

immediately or when user is ready. Note: If agent availability need to be checked before chat
interaction is started - use one of the advanced sessions (for example: request-chat-poll)
Operation
Method POST
URL /genesys/1/service/request-chat
URI Parameters
Name of the
'request-chat' String yes preconfigured basic chat
service
Body: The body will be x-www-form-urlencoded form consisting of different items representing the key/
value pairs associated with the request.
Body Properties: The following are the properties:
• _verbose - This will allow the application to get all the detail attributes associated with the chat
session in the corresponding response.
• ... - Any other business data attributes can also be passed.
Response
HTTP code 200

HTTP message OK
A chat JSON object for details on the properties of
Body the object. See the section on data structures for
more details.
Notes None
HTTP code 503

HTTP message Service Unavailable
Body None
This is send if the service has not sent a
Notes notification to the application that an agent is
available.
Example Request:
POST http://localhost:8080/genesys/1/service/request-chat HTTP/1.1

_verbose=true
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 07:49:46 GMT
Pragma: no-cache

Transfer-Encoding: chunked
{
"_chatIxnAPI-CREATE-URL":
"/genesys/1/service/81f0ef4e-99dd-43ea-8366-8d27a2cbd605/ixn/chat",
"_id":"81f0ef4e-99dd-43ea-8366-8d27a2cbd605"
}
Chat Interaction APIs
Start Chat
This API creates and initiates a Chat Session. It works with the service session created through
Genesys Mobile Services.
Operation
POST /genesys/1/service/{service_id}/ixn/chat
URI Parameters
The identifier of the
service that the chat
{service_id} string yes
session is suppose to be
associated with.
Body: The body can be either a MultiPart form, or x-www-form-urlencoded form, or JSON key/value pairs
associated with the request.
Allows the application to
get all the detail
attributes associated
_verbose boolean yes if JSON
with the chat session in
the corresponding
response.
Contains a custom
notice message that
message string yes if JSON replaces the standard
system notice in the
chat session/transcript.
If specified, should be
notify_by string no
"comet".
User's first name.
firstName string no
Optional.
User's last name.
lastName string yes
Optional.
User's email address.
email string yes
Optional.
Subject of the chat
subject string yes
conversation.

POST /genesys/1/service/{service_id}/ixn/chat
ID of the subscription
created to receive
subscriptionID string yes specific events on
Comet channel
disconnection.
Nickname displayed in
userDisplayName string yes the chat conversation.
Optional.
Device ID to use for
chat push notifications
(used to manage
push_notification_deviceid string no background state). If not
specified, push
notifications are
disabled.
Device Type to use for
chat push notification.
push_notification_type string no Possible values are ios,
gcm, android, comet,
httpcb, orscb.
Set to true to enable
debug push notifications
push_notification_debug boolean no
in the GMS server.
Default value is false.
Set the language to use
for chat push
push_notification_languagestring no notifications. (See
localization instructions
here).
Limit the payload size of
push notifications
messages. If you do not
add the
push_notification_maxsize
parameter to your
query, the the payload
size is set to 4096 bytes
by default.
push_notification_maxsize integer no
Tip
For iOS version 7 and
earlier, your iOS device
limits the push
notification payload size
to 256 bytes. Set this
parameter to 256 to
ensure correct push
notifications.

Response
HTTP code 200

HTTP message OK
more details.
The chat session id will be the service ID. The
Notes Genesys Mobile Services code for this API will keep
track of the service ID to the chat server session.
Error
HTTP code 503

Body None
Returned if the service has not sent a notification
Notes
to the application that an agent is available.
Example
Request:
POST http://localhost:8080/genesys/1/service
/9d6c31d3-1121-4ba9-91e1-b93c0fa6e32f/ixn/chat?_verbose=true HTTP/1.1
firstName=Vasya&lastName=Pupkin&[email protected]
⊂ject=test
Response (if transcriptPosition input parameter is null):
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache
{
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",
"chatServerHost": "localhost",

"/genesys/1/service/{service_id}/ixn/chat/send",
"/genesys/1/service/{service_id}/ixn/chat/refresh",
"/genesys/1/service/{service_id}/ixn/chat/startTyping",
"/genesys/1/service/{service_id}/ixn/chat/stopTyping",
"/genesys/1/service/{service_id}/ixn/chat/disconnect",
"/genesys/1/service/{service_id}/ixn/chat/refresh?transcriptPosition=1"
}
Response (if the transcript input parameter is set [transcriptToShow output parameter is
set]):
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache
{
[
"Notice.Joined",
"ksippo",
"15",
"AGENT"
],
[
"Message.Text",
"VasyaP",
"hello agent",
"26",
"CLIENT"
],
[
"ksippo",
"is typing",
"57",
"AGENT"
],
[
"Message.Text",
"ksippo",
"hello customer",
"61",
"AGENT"
]
],
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",

}
Refresh Chat
This API refreshes the users view with the latest updates to the Chat session. It can also be used to
simultaneously send a user message to the chat session.
Operation
POST /genesys/1/service/{service_id}/ixn/chat/refresh
URI Parameters
session is associated
with.
Body Properties: The following are the properties:
• transcriptPosition – This optional property indicates the current position in the chat session that the
current user is in. This property is ignored when notify_by = comet when starting the chat session
(ixn/chat)
• message – This optional property is a chat message that will be added to the chat session/transcript.
• _verbose - This optional property will allow the application to get all the detail attributes associated
with the chat session in the corresponding response.
Response
HTTP code 200

HTTP message OK

HTTP code 200

more details.
The main property is the list of chat message that
Notes
have been communicated (transcriptToShow).
Error
HTTP code 503

Body None
This is returned if the service has not sent a
available.
Example
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001H
/ixn/chat/refresh?_verbose=true HTTP/1.1
message=aaa
Response (if transcriptPosition input parameter is null):
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache
{
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",

}
Response (if transcript input parameter is set [transcriptToShow output parameter is

set]):
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache
{
[
"Notice.Joined",
"ksippo",
"15",
"AGENT"
],
[
"Message.Text",
"VasyaP",
"hello agent",
"26",
"CLIENT"
],
[
"ksippo",
"is typing",
"57",
"AGENT"
],
[
"Message.Text",
"ksippo",
"hello customer",
"61",
"AGENT"
]
],
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",

}
Start Typing
This API allows the application to indicate that the user started typing a chat message for the session.
Operation
POST /genesys/1/service/{service_id}/ixn/chat/startTyping
URI Parameters
associated with.
This will allow the
application to get all the
detail attributes
associated with the chat
session in the
corresponding response.
This mandatory
property must contain a
message string yes if JSON custom notice message
that will be added to the
Response
HTTP code 200

HTTP message OK
more details.
Notes None

Error
HTTP code 503

Body None
available.
Example
Request:
POST http://localhost:8080/genesys/1/service/EKUJPKAQ197CFA6SJQKTJ03DBG
00001J/ixn/chat/startTyping HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 07:38:38 GMT
Pragma: no-cache
Content-Length: 246
{
"transcriptToShow": [ [
"VasyaP",
"is typing",
"57",
"CLIENT"
]],
"startedAt": "2012-06-10T07:37:42Z"
}
Stop Typing
This API allows the application to indicate that the user has stopped typing a chat message for the
session.
Operation
POST /genesys/1/service/{service_id}/ixn/chat/stopTyping
URI Parameters
{service_id} string yes The identifier of the

POST /genesys/1/service/{service_id}/ixn/chat/stopTyping
associated with.
This will allow the
detail attributes
session in the
This mandatory
Response
HTTP code 200

HTTP message OK
more details.
Notes None
Error
HTTP code 503

Body None
available.
Example
Request:
POST http://localhost:8080/genesys/1/service/EKUJPKAQ197CFA6SJQKTJ03DBG
00001J/ixn/chat/stopTyping HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 07:38:58 GMT
Pragma: no-cache

Content-Length: 251
{
"transcriptToShow": [ [
"Notice.TypingStopped",
"VasyaP",
"stopped typing",
"77",
"CLIENT"
]],
"startedAt": "2012-06-10T07:37:42Z"
}
Disconnect from chat session

This API allows the application to disconnect user from the chat session.
Operation
POST /genesys/1/service/{service_id}/ixn/chat/disconnect
URI Parameters
associated with.
This will allow the
detail attributes
session in the
This mandatory
Response
HTTP code 200

HTTP message OK
more details.
Notes None

Error
HTTP code 503

Body None
available.
Example Request:
POST http://localhost:8080/genesys/1/service/EKUJPKAQ197CFA6SJQKTJ03D
BG00001J/ixn/chat/disconnect HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 07:43:07 GMT
Pragma: no-cache
Content-Length: 114
{
"chatIxnState" : "DISCONNECTED",
"chatServiceMessage" : "Chat was finished"
}
Send Custom Notice
This API query allows you to send a user notice that contains a custom message.
Operation
Method POST
URL /genesys/1/service/{service_id}/ixn/chat/customNotice
URI Parameters
{service_id} string Yes service associated with
the chat session.
The body can be either a MultiPart form, or x-www-form-urlencoded form, or
Body
JSON key/value pairs associated with the request.
Body Properties
Set to true to allow the
_verbose boolean No application to get all the
detail attributes

Method POST
session in the
Custom notice message
that will replace the
message string Yes standard system notice
in the chat session
transcript.
Response
HTTP code 200

HTTP message OK
A chat JSON object for the details of the object
Body properties. See the data structures for more
details.
Error
If a problem occurs during subscription, the following status codes are returned:
HTTP code 503

HTTP Message Service Unavailable
Body None
Important
This error is returned if the service could not send a notification to the agent
application.
Example
Request
/EKUJPKAQ197CFA6SJQKTJ03DBG00001H/ixn/chat
/customNotice?_verbose=true HTTP/1.1
message=photo.png
Response
HTTP/1.1 200 OK
Date: Sat, 09 Jun 2012 22:26:16 GMT
Pragma: no-cache

{
"startedAt": "2012-06-09T22:26:17Z",
"userId": "015E4FD3CD890036",
"/genesys/1/service/{service_id}/ixn/chat
/refresh?transcriptPosition=1",
"_chatIxnAPI_SEND_CUSTOM_URL" :
"/genesys/1/service/{service_id}/ixn/chat/customNotice"
}
Quick Start Examples

The following quick start examples show how you can establish a CometD connection to receive
asynchronous notification, and how to create a service.
Using CometD to Receive Event Updates

If you are using CometD to get event updates on the chat session then you need to set up a CometD
connection with a subscription for /_genesys. You also need to make sure 'gms_user' header in all
cometd related requests is set to the value uniquely representing application end user. Typically this
value would be setup (or at least verified) by security gateway located between the client application
and GMS.
CometD handshake request
POST http://localhost:8080/genesys/cometd
gms_user: BuzzBrain
{"version":"1.0","minimumVersion":"0.9",
"channel":"/meta/handshake","id":"0"}

HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 230
[{"id":"0","minimumVersion":"1.0","supportedConnectionTypes":
["websocket","callback-polling","long-polling"],
"successful":true,"channel":"/meta/handshake","ext": "ack":true},
"clientId":"44xkkazwfabw73jrvjsvoy4ul","version":"1.0"}]
CometD /meta/connect subscription request
gms_user: BuzzBrain
{"channel":"/meta/connect",
"clientId":"44xkkazwfabw73jrvjsvoy4ul","id":"1",
"connectionType":"long-polling"}
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 116
[{"id":"1","successful":true,"advice":
{"interval":0,"reconnect":"retry","timeout":60000},
"channel":"/meta/connect"}]
CometD /_genesys subscription request
POST http://localhost:8080/genesys/cometd Accept-Encoding: gzip,deflate

gms_user: BuzzBrain
[{"channel":"/meta/subscribe","subscription":"/_genesys",
"clientId":"44xkkazwfabw73jrvjsvoy4ul","id":"2"}]
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 85
[{"id":"2","subscription":"/_genesys","successful":true,
"channel":"/meta/subscribe"}]
CometD long polling request
gms_user: BuzzBrain
{"clientId":"44xkkazwfabw73jrvjsvoy4ul","id":"3",
"channel":"/meta/connect","connectionType":"long-polling"}
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 85
[{"id":"4","successful":true,"channel":"/meta/connect"}]

Creating a Genesys Mobile Services-Based Service Associated with a Chat

Session
The following section illustrates the process of creating and using a service.
Create a Service:
Request:
POST http://localhost:8080/genesys/1/service/request-chat-poll HTTP/1.1

_verbose=false
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:23:29 GMT
{"_id":"EKUJPKAQ197CFA6SJQKTJ03DBG00001M"}
Use the _id field from the response to check service status until it changes to "available":
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/status HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:26:26 GMT
Content-Length: 185
{
"message": {
"_id": "EKUJPKAQ197CFA6SJQKTJ03DBG00001M",
"_status": "waiting",
"_dialog": "waiting_for_agent.html"
},
"tag": "a2c.advanced.service.statuschanged
.EKUJPKAQ197CFA6SJQKTJ03DBG00001M"
}
Repeat request until status changes:
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/status HTTP/1.1
Response:
HTTP/1.1 200 OK

Date: Sun, 10 Jun 2012 08:28:25 GMT

Content-Length: 186
{
"message": {
"_id": "EKUJPKAQ197CFA6SJQKTJ03DBG00001M",
"_status": "available",
"_dialog": "agent_available.html"
},
"tag": "a2c.advanced.service.agentavailable
.EKUJPKAQ197CFA6SJQKTJ03DBG00001M"
}
Create chat interaction using same sessionid:
To create a chat interaction that is associated with a service, a ixn/chat request is sent with the
parameters to initiate the chat session.
Parameter Name Mandatory Description

First name of the user. If provided
will be attached as
firstName no
fldnFirstName to the chat
interaction.
Last name of the user. If provided
will be attached as
lastName no
fldnLastName to the chat
interaction.
e-Mail address of the subject. If
provided will be attached as
email no
fldnEmailAddress to the chat
interaction.
Subject of the service and chat
subject yes
session.
Available since GMS 8.1.100.27.
userDisplayName no Nickname to be displayed in the
chat conversation.
If using a CometD connection for
the asynchronous receiving of
notify_by no chat messages, then supply this
parameter with the value
"comet".
Device ID to use for chat push
notifications (used to manage
push_notification_deviceid no background state). If not
specified, push notifications are
disabled.
Device Type to use for chat push
notification. Possible values are:
push_notification_type no
ios, gcm, android, comet,
httpcb, orscb.
Set to true to enable debug push
push_notification_debug no notifications in the GMS server.
Default value is false.

Parameter Name Mandatory Description

Set the language to use for chat
push_notification_language no push notifications. (See
localisation instructions here )
Limit the payload size of push
notifications messages. If you do
not add the
push_notification_maxsize
parameter to your query, the
payload size is set to 4096 bytes
by default.
push_notification_maxsize no
Tip
For iOS version 7 and earlier, your
iOS device limits the push
notification payload size to 256
bytes. Set this parameter to 256 to
ensure correct push notifications.
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/ixn/chat HTTP/1.1
notify_by=comet&firstName=Vasya&lastName=Pupkin
&[email protected]⊂ject=test
&push_notification_deviceid=deviceid&push_notification_type=ios
&push_notification_debug=true&push_notification_language=en
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 119
{
"chatIxnState" : "CONNECTED",
"chatServiceMessage" : "Chat service is available"
}
Refresh chat transcript and show messages to the user:
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/ixn/chat/refresh HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:33:00 GMT
Content-Length: 367
{"_id":"B2FS3346K151548QMEAFD89TE8000EBJ",

"comet_channel":"/_genesys"}
Send user's message:
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/ixn/chat/refresh HTTP/1.1
message=hello agent
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:34:38 GMT
Content-Length: 241
{"_id":"B2FS3346K151548QMEAFD89TE8000EBJ",
"comet_channel":"/_genesys"}
Disconnect user from chat:
Request:
/EKUJPKAQ197CFA6SJQKTJ03DBG00001M/ixn/chat/disconnect HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 07:43:07 GMT
Content-Length: 114
{
"chatServiceMessage" : "Chat was finished"
}
CometD-Based Chat API
CometD Handshake
Request
POST http://localhost:8080/genesys/cometd/handshake
gms_user:
b16416334828b1d26ef14f329628b55b5a8c631d8928a371a5584722dd7fb673
[{"version":"1.0","minimumVersion":"0.9",
"channel":"/meta/handshake",

"supportedConnectionType"":["long-polling","callback-polling"],
"advice":{"timeout":60000,"interval":0},"id":"1"}]
Response
[{"id":"1","minimumVersion":"1.0","supportedConnectionTypes":
["callback-polling","long-polling"],
"successful":true,"channel":"/meta/handshake","ext":{"ack":true},
"clientId":"3vym301sjdtc218qabm5w0z8yb","version":"1.0"}]
CometD Subscribe
Request
POST http://localhost:8080/genesys/cometd/
gms_user:
[{"channel":"/meta/subscribe","subscription":"/_genesys","id":"2",
"clientId":"3vym301sjdtc218qabm5w0z8yb"}]
Response
"channel":"/meta/subscribe"}]
CometD Connect
Request
Note, ext component containing transcriptPosition is optional, see section on network connection loss
below.
POST http://localhost:8080/genesys/cometd/connect
gms_user:
[{"channel":"/meta/connect","connectionType":"long-polling",
"advice":{"timeout":0},
"id":"3","clientId":"3vym301sjdtc218qabm5w0z8yb"},
"ext": {"transcriptPosition": "4"}]
Response
[{"id":"3","successful":true,"advice":
{"interval":0,"reconnect":"retry","timeout":60000},
Create Service Session

Request

POST http://localhost:8080/genesys/1/service/request-chat
gms_user:
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
_verbose=true
Response
{ "_chatIxnAPI-CREATE-URL":
"/genesys/1/service/4d1697a9-dda5-4742-8a6f-fbc01c25c640/ixn/chat",
"_id":"4d1697a9-dda5-4742-8a6f-fbc01c25c640",
"_data_id":"429-791eaee8-571e-4633-9a73-cc936336f8e2"
}
Create Chat Interaction for Session 4d1697a9-dda5-4742-8a6f-fbc01c25c640

Request
POST
/4d1697a9-dda5-4742-8a6f-fbc01c25c640/ixn/chat
gms_user:
_verbose=true¬ify_by=comet&FirstName=John&LastName=Harry
⊂ject=French&EmailAddress=j.h%40gmail.com
Response
{
"chatServerLoadBalancerAlias":"371",
"_chatIxnAPI_SEND_CUSTOM_URL":
"/genesys/1/service/4d1697a9-dda5-4742-8
a6f-fbc01c25c640/ixn/chat/customNotice",
"clientTimeZoneOffset":"120",
"transcriptPosition":"1",
"chatWebApiPort":"9002",
"chatIxnState":"CONNECTED",
"comet_channel":"/_genesys",
"secureKey":"1b21478a91a7d1dc",
"/genesys/1/service/4d1697a9-dda5-4742-8a6f-fbc01c25c640
/ixn/chat/refresh?transcriptPosition=1",
/ixn/chat/refresh",
"chatSessionId":"000E5aA2A40P000Q",
"isTLSrequired":"false",
"chatServiceMessage":"Chat service is available",
"userId":"0173542518870006",

/ixn/chat/send",
"chatServerHost":"demosrv.genesyslab.com"
}
Polling Agent 'Joined' Message Through CometD

Request
gms_user:
"id":"4","clientId":"3vym301sjdtc218qabm5w0z8yb"}]"
Response
[
{"data":{"id":"7b239ff0455011e4b31cbb293fafe316",
"message":{"chatSessionId":"000E5aA2A40P000Q",
"startedAt":"2014-09-26T07:40:55Z",
"chatIxnState":"TRANSCRIPT",
"transcriptToShow":[ ["Notice.Joined","Kristi Sippola",
"has joined the session","14","AGENT"]]},
"tag":"service.chat.refresh.4d1697a9-dda5-4742-8a6f-fbc01c25c640"},
"channel":"/_genesys"},
{"id":"4","successful":true,"channel":"/meta/connect"}
]
Polling Agent 'StartTyping' Message Through CometD

Request
gms_user:
Response
[
{"data":{"id":"802c88e0455011e4b31cbb293fafe316",

"startedAt":"2014-09-26T07:40:55Z",
"transcriptToShow":
[["Notice.TypingStarted","Kristi Sippola",
"is typing","22","AGENT"]]},
]
Polling Agent Chat Message Through CometD

Request
gms_user:
Response
[
{"data":{"id":"816f9030455011e4b31cbb293fafe316",
"startedAt":"2014-09-26T07:40:55Z",
"transcriptToShow":[["Message.Text","Kristi
Sippola","Hello","23","AGENT"]]},
]
Send Client Chat Message

Request
POST
/4d1697a9-dda5-4742-8a6f-fbc01c25c640/ixn/chat/refresh
gms_user:
"b16416334828b1d26ef14f329628b55b5a8c631d8928a371a5584722dd7fb673
_verbose=true&message=Hi%20Verbose
Response
{
"chatServerLoadBalancerAlias":"371",

"_chatIxnAPI_SEND_CUSTOM_URL":
/ixn/chat/customNotice",
"clientTimeZoneOffset":"120",
"chatWebApiPort":"9002",
"startedAt":"2014-09-26T07:40:55Z",
"comet_channel":"/_genesys",
"secureKey":"1b21478a91a7d1dc",
"/genesys/1/service/4d1697a9-dda5-4742-8a6f-fbc01c25c640/ixn
/chat/refresh?transcriptPosition=1",
/ixn/chat/refresh",
"isTLSrequired":"false",
"chatSessionId":"000E5aA2A40P000Q",
"userId":"0173542518870006",
/ixn/chat/send",
"chatServerHost":"demosrv.genesyslab.com"
}
Client Message is Being Echoed Back Through CometD Channel as a Response to

"refresh" or "send" Request
Request
gms_user:
[{"channel":"/meta/connect","connectionType":"long-polling","id":"7",
"clientId":"3vym301sjdtc218qabm5w0z8yb"}]"
Response
[
{"data":{"id":"867b3840455011e4b31cbb293fafe316",
"startedAt":"2014-09-26T07:40:55Z",

"transcriptToShow":[["Message.Text","127.0.0.1",
"Hi Verbose","32","CLIENT"]]},
{"id":"7","successful":true,"channel":"/meta/connect"}]
CometD Polling
Request
gms_user:
Response
[{"id":"8","successful":true,"advice":{"reconnect":"none"},
Disconnect Chat Session

Request
POST
http://localhost:8080/genesys/1/service/4d1697a9-dda5-4742-8a6f
-fbc01c25c640/ixn/chat/disconnect
gms_user:
_verbose=true
Response
{
"chatServiceMessage" : "Chat was finished",
"chatSessionId" : "000E5aA2A40P000Q",
"userId" : "0173542518870006",
"secureKey" : "1b21478a91a7d1dc",
"checkChatServiceLoadBalancerPath" :
"chatServerLoadBalancerAlias" : "371",
"chatServerHost" : "demosrv.genesyslab.com",
"chatWebApiPort" : "9002",
"isTLSrequired" : "false",
"clientTimeZoneOffset" : "120",
"_chatIxnAPI_SEND_URL" :

/chat/send",
"_chatIxnAPI_REFRESH_URL" :
/chat/refresh",
"_chatIxnAPI_START_TYPING_URL" :
/chat/startTyping",
"_chatIxnAPI_STOP_TYPING_URL" :
/chat/stopTyping",
"_chatIxnAPI_DISCONNECT_URL" :
/chat/disconnect",
/chat/refresh?transcriptPosition=1",
"_chatIxnAPI_SEND_CUSTOM_URL" :
/chat/customNotice"
}
CometD Unsubscribe
Request
POST http://localhost:8080/genesys/cometd/
gms_user:
[{"channel":"/meta/unsubscribe","subscription":"/_genesys",
"id":"9","clientId":"3vym301sjdtc218qabm5w0z8yb"}]
Response
"channel":"/meta/unsubscribe"}]
CometD Disconnect
Request
POST http://localhost:8080/genesys/cometd/disconnect
gms_user:
[{"channel":"/meta/disconnect","id":"10","clientId":
"3vym301sjdtc218qabm5w0z8yb"}]
Response
[{"id":"10","successful":true,"channel":"/meta/disconnect"}]

Chat Push Notification and Background State
Mobile Application Background State Issues

If an iOS or Android mobile application is moved to the background state, the operating system does
not close active TCP connections. So, if your app does not handle the foreground and background
events, the server-side of your CometD connection isn't notified.
More specifically, if your app handles chat with GMS, the agent may send a new message which
would result in sending the long poll response. Here is a list of the various scenarios which can
happen according to your implementation.
• The Cometd server attempts to send long poll response but fails and closes socket of current long-poll
request.
• The Cometd server sets a 10 second timer; if the app does not reconnect within this period, the app is
considered to be gone and its context is destroyed.
Later, if the app returns to the foreground, it does not receive chat notifications from the Cometd
server and the chat session appears to be broken.
To avoid these type of issues, your app should listen for events that both iOS and Android submit
when your app enters the background (or foreground) state. See the Official documentation.
• Apple provides background instructions for iOS, here.

• Android provides best background practices here.
Then, your app should implement the Cometd Meta Disconnect message detailed below to handle
background State issues.
Cometd Meta Disconnect Messages

To handle background state, your app must send Cometd /meta/disconnect messages to GMS and
later, if your app returns to foreground, it should establish a new Cometd session as detailed below.
1. When your app enters the background state, it sends a Comet/meta/disconnect message to GMS
which includes the highest transcript position received by your app, as for example:
{
"channel": "/meta/disconnect",
"clientId": "71k6evjfbffqq9eir3jhn6udxz",
"ext:
{
"transcriptPosition": "4"
},
"id": "4"
}

2. If GMS receives a /meta/disconnect message, it flags your app as disconnected and sends a chat
Notice.Custom event to the agent. The default value is customer is not online. You can configure
this text.
1. Edit your GMS application (with Configuration Manager for example).
2. Navigate to Options > Service.<service_name>.
3. Edit the _agent_timeout_notification_message value.
3. If the agent sends a new message while your app is disconnected, GMS starts a configurable timer. You
can set this timer value to zero
3. Edit the _client_timeout_notification value.
When the timer expires, GMS sends a push notification (iOS apns, Android gcm, or http). Typically, the
notification results in a dialog which allows the user to optionally return the app to the foreground.
4. The chat session may have ended when the app returns to the foreground, either because the agent left
the session or because the session timed out as a result of user inactivity. In that case, the app no
longer receives Cometd notifications. To detect if the session has ended, call the Chat Refresh Chat API
– it will return a 4xx reply to indicate that a session has ended.
5. When the app returns to the foreground and if the session has not ended, it must start a new Cometd
session with GMS. GMS flags the app as connected and sends a Cometd notification that includes all
chat transcript events that occurred after the app entered the background state, as for example:
[
{
"data":{
"id":"fdf93730c1e411e4a5e8f1be76b28efd",
"message":
{ "chatSessionId":"0001BaAFC4J8000N",
"startedAt":"2015-03-03T20:36:12Z",
"chatIxnState":"TRANSCRIPT", "transcriptToShow":
[ ["Notice.TypingStarted","agentName","is typing","28","AGENT"],
["Message.Text","agentName","Hello","29","AGENT"] ] },
"tag":"service.chat.refresh.180-655e104c-a6cf-447d-b94b-f132d49a35fe"
},
"channel":"/_genesys"
},
{ "successful":true, "channel":"/meta/connect" }
]
Important
• If your app returns to foreground before the timer expires, no push notification is sent,
but your app must still start a new Cometd session and it will receive a Cometd
notification (which includes all new transcript data) from GMS.
• If your app does not return to foreground after the first push notification is sent, GMS
sends additional push notification messages for each new agent event. Note that these

events are sent immediately.
Content of Push Notification Messages

GMS triggers push notification messages if the agent submits new chat events to the app flagged as
disconnected. The following events can result in a notification:
• Notice.TypingStarted
• Notice.TypingStopped
• Notice.Joined
• Notice.Left
• Notice.PushUrl
• Notice.Custom
• Message.Text
Your application's configuration includes a filter to exclude events from triggering a push notification.
The filtering_chat_events option in the push section sets the default value for this filter to
Notice.TypingStarted,Notice.TypingStopped. You can still set a different value for your service.

3. Edit the _filtering_chat_events option to add new event types to exclude.
For the Android and http push notification types, notification messages include the content of the
filtered agent events.
The following example of the push notification message includes the content of the filtered agent
events.
"message": {
"message": "New message from Agent",
"serviceId": "180-e941460d-1eb0-4f0b-9022-b99ca9ee41f7",
"lastTranscript": [
{"Message.Text": "A line of text."}
{"Message.Text": "Another line of text."}
]
}
By default, the message attribute (or notification message) is set to New message from Agent, but
you can change this text in your service options.

3. Edit the value of the _client_timeout_notification_message option.

The notification is tagged as chat.newagentmessage. In addition to the notification message, the

notification content provides the lastTranscript text that can be displayed to the user.
• You can display this the lastTranscript text in a popup a or banner notification to the user.
Specific Configuration for Chat Push Notification

To customize your GMS configuration for push notification messages (for both iOS and Android), you
can create a push.provider.event.chat.newagentmessage section in the Options tab (with
Configuration Manager for instance). You can add there any of your Android or iOS options.
• This additional configuration is not mandatory.
Tip
• Read more about options of the GMS push section here.
• Read more about the OS specific capabilities associated with the notification message
here.

CometD and Loss of Network Connection

Mobile devices are subject to temporary loss of carrier or wifi network connectivity. If this occurs
when a chat session is active, the mobile device may not receive CometD transcription notifications
that occurred during or around the time of the loss.
The mobile device CometD client should detect when network connectivity has been lost; for
example, the current long-poll request will return an error. When this occurs, the CometD client
should establish a new session starting with a handshake sequence. To support the mobile client
informing GMS on the transcription notifications already received, the first /meta/connect message
that is sent after the handshake can optionally include the client's transcriptPosition in the ext
component. An example connect message is shown below.
gms_user: BuzzBrain
{
"channel": "/meta/connect",
"clientId": "44xkkazwfabw73jrvjsvoy4ul",
"connectionType": "long-polling"
"advice": {
"timeout": 0
},
"ext": {
},
"id": "1"
}
If the transcriptPosition is provided this way the next CometD notification sent by GMS will include
transcript content starting at the next position, so the client will only receive the content that was
missed due to the network connection loss.
Note, If the transcriptPosition is not provided in the /meta/connect after a network loss, GMS will
estimate the client transcriptPosition based on the timing of the loss of network connection. Typically
this will result in the next CometD notification including some transcript content that was previously
received, but could also result in the transcript content starting at an offset greater than what was
received. If the client does not provide the transcriptPosition upon reconnecting after a network
connection loss, it is recommended to call the refresh API function to reset the local transcript display.

Chat API Version 1 Push Notification and

Background State
Mobile Application Background State Issues

If an iOS or Android mobile application is moved to the background state, the operating system does
not close active TCP connections. So, if your app does not handle the foreground and background
events, the server-side of your CometD connection isn't notified.
More specifically, if your app handles chat with GMS, the agent may send a new message which
would result in sending the long poll response. Here is a list of the various scenarios which can
happen according to your implementation.
• The Cometd server attempts to send a long poll response but fails and closes the socket of the current
long-poll request.
• The Cometd server sets a 10-second timer; if the app does not reconnect within this period, the app is
considered to be gone and its context is destroyed.
Later, if the app returns to the foreground, it does not receive chat notifications from the Cometd
server and the chat session appears to be broken.
To avoid these types of issues, your app should listen for events that both iOS
and Android submit when your app enters the background (or foreground) state.
[+] Read more about background state
See the Official documentation.
• Apple provides background instructions for iOS, here

• Android provides best background practices here
Then, your app should implement the Cometd Meta Disconnect message detailed below to handle
background State issues.
Cometd Meta Disconnect Messages

To handle background state, your app must send Cometd /meta/disconnect messages to GMS and
later, if your app returns to foreground, it should establish a new Cometd session as detailed below.
1. When your app enters the background state, it sends a Comet/meta/disconnect message to GMS
which includes the highest transcript position received by your app, as for example:
{
"channel": "/meta/disconnect",

"clientId": "71k6evjfbffqq9eir3jhn6udxz",
"ext:
{
},
"id": "4"
}
2. If GMS receives a /meta/disconnect message, it flags your app as disconnected and sends a chat
Notice.Custom event to the agent. The default value is customer is not online. You can configure
this text. [+] Tell me how
3. Edit the _agent_timeout_notification_message value.
3. If the agent sends a new message while your app is disconnected, GMS starts a configurable timer. You
can set this timer value to zero [+] Tell me how
3. Edit the _client_timeout_notification value.
. When the timer expires, GMS sends a push notification (Google FCM, or HTTP). Typically, the
notification results in a dialog that allows the user to optionally return the app to the foreground.
4. If the app returns to the foreground, it must start a new Cometd session with GMS. GMS flags the app as
connected and sends a Cometd notification that includes all chat transcript events which occurred after
the app entered the background state, as for example:
[
{
"data":{
"id":"fdf93730c1e411e4a5e8f1be76b28efd",
"message":
{ "chatSessionId":"0001BaAFC4J8000N", "transcriptPosition":
"6", "chatServiceMessage":"Chat service is available", "startedAt":
"2015-03-03T20:36:12Z", "chatIxnState":"TRANSCRIPT", "transcriptToShow":[
["Notice.TypingStarted","agentName","is typing","28","AGENT"],
["Message.Text","agentName","Hello","29","AGENT"] ] },
"tag":
"service.chat.refresh.180-655e104c-a6cf-447d-b94b-f132d49a35fe"
},
},
{ "successful":true, "channel":"/meta/connect" }
]
Important
• If your app returns to foreground before the timer expires, no push notification is sent,
but your app must still start a new Cometd session and it will receive a Cometd
notification (which includes all new transcript data) from GMS.

• If your app does not return to foreground after the first push notification is sent, GMS
sends additional push notification messages for each new agent event. Note that these
events are sent immediately.
Content of Push Notification Messages

GMS triggers push notification messages if the agent submits new chat events to the app flagged as
disconnected. The following events can result in a notification:
• Notice.TypingStarted
• Notice.TypingStopped
• Notice.Joined
• Notice.Left
• Notice.PushUrl
• Notice.Custom
• Message.Text
Your application's configuration includes a filter to exclude events from triggering

a push notification. The filtering_chat_events option in the push section sets
the default value for this filter to
Notice.TypingStarted,Notice.TypingStopped. You can still set a different
value for your service. [+] Tell me how

3. Edit the _filtering_chat_events option to add new event types to exclude.
For the Android and HTTP push notification types, notification messages include the content of the
filtered agent events. Currently, this is not supported for iOS push notification messages due to the
256-byte payload size limit for this notification type.
The following example of the push notification message includes the content of the filtered agent
events.
"message": {
"message": "New message from Agent",
"serviceId": "180-e941460d-1eb0-4f0b-9022-b99ca9ee41f7",
"lastTranscript": [
{"Message.Text": "A line of text."}
{"Message.Text": "Another line of text."}
]
}

By default, the message attribute (or notification message) is set to New message
from Agent, but you can change this text in your service options. [+] Tell me
how

3. Edit the value of the _client_timeout_notification_message option.
The notification is tagged as chat.newagentmessage. In addition to the notification message, the

notification content provides the lastTranscript text that can be displayed to the user.
• You can display this the lastTranscript text in a popup a or banner notification to the user.
Specific Configuration for Chat Push Notification

To customize your GMS configuration for push notification messages (for both iOS and Android), you
can create a push.provider.event.chat.newagentmessage section in the Options tab (with
Configuration Manager for instance). You can add there any of your Android or iOS options.

• This additional configuration is not mandatory.
Tip
• Read more about options of the GMS push section here.
• Read more about the OS specific capabilities associated with the notification message
here.

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
HTTP Method URI
POST /genesys/2/chat/{serviceName}
HTTP Header Value
application/x-www-form-urlencoded
OR
Content-Type
multipart/form-data
Parameter Name Sample Value Description Required/Optional

customer's nickname
(either nickname or
nickname "JohnDoe" both firstName and Required
lastName should be
supplied)
first name of the
customer (either
firstName "John" nickname or both Required
firstName and lastName
should be supplied)
last name of the
customer (either
lastName "Doe" nickname or both Required
should be supplied)
subject as entered by
subject "Help with account" Optional
the customer
email address of the
emailAddress "[email protected]" Optional
customer
any attached data that
userData[attachedDataKey1]
value1 the client wants to add Optional
to chat
userData[importantKey2] value2 the client wants to add Optional
to chat

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
"I need help with
message text message to send Required
account"
userId "007553863DC30029" user ID Required

HTTP Method URI

secureKey "8b31761b2154884c" secure key Required
alias "117" host alias Required
any arbitrary type that
messageType "text" Optional
the user wants to set
Including this parameter
enables the return of
the transcription and it
transcriptPosition 8 Optional
sets the position in the
transcript from where it
should be retrieved.
Example
/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},
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

HTTP Method URI

message "message ..... " message if any Optional
Example
/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
Example
/00048aAPEQJ8000S/stopTyping
Input

userId=0075555D17270020
alias=117
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
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, this request can be used 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

HTTP Method URI

0 (no messages)
index position in the transcript Optional (All messages are
1 (all messages)
transcriptPosition starting from which the retrieved if no value is
messages should be retrieved provided, which defaults to 1)
2 (all messages starting from
2nd message)
Applies only to Typing Preview
• If no message is
submitted (absent
from JSON input), no
TypingStarted
For use with Typing Preview at request is submitted
the agent chat window. Text
that the user has entered so
to the chat server
far in the chat box at the time
this request is being made. • If message is
"Text that user is typing This text will be submitted to submitted (even if it
message
..." the chat server along with is empty/blank but
notification TypingStarted. present in JSON
Property "typing_preview" input) a
must be enabled as described TypingStarted
in Chat Services Options. 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",
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
/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",
"userId":"007555677CB4000D",
"nextPosition":22
}
Disconnect
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/disconnect
HTTP Header Value
Example
/00048aAPEQJ8000S/disconnect
Input
userId=0075555D17270020
alias=117

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
pushUrl "http://url.to.see" URL Required
Example
/00048aAPEQJ8000S/pushUrl
Input
userId=0075555D17270020
alias=117
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
nickname John Doe 2 new nickname Required
Example
/00048aAPEQJ8000S/updateNickname
Input
userId=00755567761A0008
alias=117
nickname=newName
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
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

HTTP Method URI

message "message ..." message, if any Optional
Example
/00048aAPEQJ8000S/customNotice
Input
userId=00755567761A0008
alias=117
message=custom+message
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
userId: "00755567761A0008"
}
Update User Data

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/updateData
HTTP Header Value
userData[key1] value1 user data to be updated Required
Example
/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
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
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

The index of the event
that the client app
acknowledges having
read.
transcriptPosition "5" Required
This is not the same index as
nextPosition, but rather the
index of the event from the
"messages" array.

Example
http://localhost:8080/genesys/2/chat/customer-support/00048aAPEQJ8000S/readReceipt
Input
userId=007553863DC30029
secureKey=8b31761b2154884c
alias=117
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

HTTP Method URI
• multipart/form-data
Content-Type
• application/x-www-form-urlencoded (starting in 8.5.110.07)
Required/
Parameter Name Sample Value Description Source
Optional
userId "007553863DC30029"user ID Required Form
secureKey "8b31761b2154884c"secure key Required Form
alias "117" host alias Required Form
Output Parameters
Parameter Description
Maximum number of times a specific file can be
download-attempts
downloaded during this session
Maximum number of files a client can upload
upload-max-files
during this session
Maximum allowable file size of a single uploaded
upload-max-file-size
file
upload-max-total-size Maximum allowable file size of all uploaded files
Indicates whether an agent needs to accept a chat
upload-need-agent
session before an upload is allowed
Colon-delimited list of file extensions indicating
upload-file-types
which types of files can be uploaded
Current number of files uploaded during this
used-upload-max-files
session
Current total size of all files uploaded during this
used-upload-max-total-size
session
Current number of downloaded files during this
used-download-attempts
session
Indicates whether upload-max-files is
delete-file
decremented after a file has been deleted
Example
/00048aAPEQJ8000U/file/limits
Input
userId=007553863DC30029
alias=117
Output

{
"messages": null,
"chatEnded": false,
"statusCode": 0,
"alias": "240",
"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
Required/
Optional
file to be uploaded
file "afile.txt" Required Form
into the session
This value can be
used by the agent
userData[file-
"March invoice" desktop and the Optional Form
description]
client UI to provide
additional file info
Collection of key-
value pairs that
userData[userKey1] "User value 1" Optional Form
provides file
metadata

Example
/00048aAPEQJ8000U/file
Input
userId=007553863DC30029
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
Required/
Optional
File to be
fileId "00048aAPEQJ8ABCD"downloaded from Required URL
the session

Example
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD
Input
userId=007553863DC30029
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/
POST
chat/{serviceName}/{chatId}/file/{fileId}/delete
HTTP Header Value
Content-Type • application/x-www-form-urlencoded (starting in
8.5.110.07)

Required/
Optional
The file to be
the session
Example
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD/delete
Input
userId=007553863DC30029
alias=117
Output
{
"messages": [],
"chatEnded": false,
"statusCode": 0,
"alias": "240",
"secureKey": "ad437d2338d09d09",
"userId": "00F057DB125E000A",
"chatId": "0001KaBWNVUV0011",
"nextPosition": 7
}

Genesys Mobile Services API Reference Pattern Matcher API
Pattern Matcher API
Getting Started
The Pattern Matcher API allows you to create and manage pattern lists that you can use to check
parameter values and define exceptions in your GMS service.

First, configure a list of patterns or groups of list of patterns in your GMS Configuration object or per
service, in the GMS Service Management UI as detailed in the Callback Solution Guide.
For example, the left-side screenshot shows the GMS configuration of the patterns_def1 group .
Once you have defined some patterns, use the Pattern Matcher API queries to check the validity of
your parameters. Each query will return the name of the matching pattern (if any) for each
parameter. As a result, if none of the parameters match the patterns, the response will be an empty
array.
For example, if you submit the following parameters:
param1 = 1234562
param2 = [email protected]
param3 = 911
The API result would be:
"param3":"911","param2":"email"
Pattern Format
The exception patterns are regular expressions as defined in the Java Pattern Class.
For the _customer_number parameter used in Callback, note that the system internally adds a + sign
to the phone number by default. As a result, if _customer_number=12345678901, it will become
_customer_number=+12345678901 in the system before going through the processing of the patterns
exception. So, to define patterns exception for specific phone numbers, you need to add the + sign at
the start of your pattern exception, for example:
[cb_errors]
12345678901=\+12345678901
List of API Queries

• POST genesys/1/patterns: Verify parameters against general patterns list.
• POST genesys/1/patterns/group/{groupName}: Verify parameters against a specific group in the
patterns list.
Verify Parameters Against General Patterns List

Use this query to submit a list of parameters to verify. The method returns a JSON array of the
parameters that match one of the patterns, where: the keys are the parameters and the values are
the name of the matching pattern in the general pattern list. Only strings that match one of the
patterns are returned; others are ignored. As a result, if none of the parameters match the patterns,
the response will be an empty array.

Operation
POST genesys/1/patterns
Body: The body can be either a MultiPart form or x-www-form-urlencoded form that consists of key/
value pairs representing the strings to test.
For example: param1=<string to check>¶m2=<string to check>&...¶m-n=<string to check>
Response
HTTP code 200

HTTP Message OK
A JSON array of key-value pairs where the key is
the parameter name and the value is the name of
the matching pattern. For example: {"param1":
Body
"pattern1","param2":"pattern2",..., "param-
n":"pattern-n"} where pattern-i is the name of
a pattern.
Example
The following example verifies param1, param2, and param3.
POST http://127.0.0.1:8080/genesys/1/patterns HTTP/1.1

Host: 127.0.0.1:8080
Connection: keep-alive
Content-Length: 347
Origin: chrome-extension://fdmmgilgnpjigdojojpjoooidkmcomcm
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.22
(KHTML, like Gecko) Chrome/25.0.1364.152 Safari/537.22
Content-Type: multipart/form-data;
boundary=----WebKitFormBoundaryTkdw0u7LG1bBGbnj
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8,fr;q=0.6,fr-FR;q=0.4
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
------WebKitFormBoundaryTkdw0u7LG1bBGbnj
Content-Disposition: form-data; name="param1"
12
[email protected]
911-
------WebKitFormBoundaryTkdw0u7LG1bBGbnj--
The following response indicates that param2 and param3 match some patterns defined in
Configuration Manager.
HTTP/1.1 200 OK
Date: Thu, 14 Mar 2013 16:13:06 GMT
Pragma: no-cache

Content-Length: 44
{"param3":"911","param2":"email"}
Verify Parameters Against a Specific Group in the Patterns List

Use this query to submit a list of parameters to verify against the patterns defined in a specific group
that is part of the general pattern list. The method returns a JSON array of the parameters that match
one of the patterns of this group, where the keys are the parameters and the values are the name of
the matching pattern in the group pattern list. Only strings that match one of the patterns are
returned; others are ignored. As a result, if none of the parameters match the patterns, the response
will be an empty array.
Operation
POST genesys/1/patterns/group/{groupName}
URI Parameters
The group to which the

{groupName} String Yes patterns belong.
Body: The body can be either a MultiPart form or x-www-form-urlencoded form consisting of key/value
pairs, representing the strings to test.
For example:
param1=<string to check>¶m2=<string to check>&...¶m-n=<string to check>
Response
HTTP code 200

HTTP Message OK
A JSON array of key-value pairs where the key is
the parameter name and the value is the pattern
found for this parameter. {"param1":
Body
"pattern1","param2":"pattern2",..., "param-
n":"pattern-n"} where pattern-i is the name of
a pattern.
Example
The following example verifies if the param1 and param2 match the group of patterns "patterns_def1".
Operation
POST http://127.0.0.1:8080/genesys/1/patterns/group/patterns_def1
HTTP/1.1
Host: 127.0.0.1:8080
Content-Length: 41

Origin: chrome-extension://fdmmgilgnpjigdojojpjoooidkmcomcm
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64)
AppleWebKit/537.22 (KHTML, like Gecko)
Chrome/25.0.1364.152 Safari/537.22
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8,fr;q=0.6,fr-FR;q=0.4
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
param1=john.doe%40gmail.com¶m2=blabla
Result
HTTP/1.1 200 OK
Date: Thu, 14 Mar 2013 16:22:30 GMT
Pragma: no-cache
Content-Length: 30
{"param1":"email"}
The following response indicates that param1 matches the email pattern of the patterns_def1 group
defined in Configuration Manager.
Sample Errors
Your application can receive an HTTP error 403 Forbidden if your service and your GMS configuration
do not include the required patterns or group of patterns.
HTTP/1.1 403 Forbidden

Date: Thu, 14 Mar 2013 16:23:35 GMT
Pragma: no-cache
Content-Length: 107
{"message":"Group (patterns_def1s) unknown.",
"exception":"com.genesyslab.gsg.services.pattern.MatchPattern"}
HTTP/1.1 403 Forbidden

Date: Thu, 14 Mar 2013 16:24:32 GMT
Pragma: no-cache
Content-Length: 142
{"message":"Service (match-interaction) not configured
to support exceptions.",
"exception":"com.genesyslab.gsg.services.pattern.MatchPattern"}

Genesys Mobile Services API Reference Service API
Service API
Overview
This API is used by customer-facing applications to manage different types of contact center related
services. For example the app-to-connect-basic service provides the necessary contact center access
information so the end user and associated application can initiate an interaction with the contact
center.
Important
Parameters that begin with an underscore (_) are passed to ORS. Anything else is
considered as user data, and is saved in storage. The stored data can be retrieved
using the _data_id parameter passed in scxml.
Create Service
This API query creates and initiates a service that you previously configured in the Admin UI in the
Configured Services interface.
Important
Before you start using a service by making REST-queries to its execution name, you
must create it with this API query.
Multipart or Urlencoded
Multipart or Urlencoded Operation
Method POST
URL /genesys/1/service/{service}
URI Parameters
{service} string yes The name of the service

Method POST
that is to be created and
initiated.
Body: The body can be either a MultiPart form or x-www-form-urlencoded form consisting of different
items representing the key/value pairs associated with the given service type. In the case of MultiPart,
the values can be strings or files, but with urlencoded, the values can be only strings.
Response
HTTP code 200

HTTP message OK
A JSON object with the following: {"id":
${service_id}, {service_specific_data}}
where:
• ${service_id} is the identifier assigned to the

Body
created service instance.
• ${service_specific_data} is service specific data
that can be returned when the service is
created.
If a matching services does not find a match, it will return the following status code.
HTTP code 404

Example
The following example starts a request-interaction service with the end user's phone number and
application data: current user's location, preferred language, and end user's picture.
Operation
Request URL:
http://localhost:8080/genesys/1/service/request-interaction
Request Method:POST
Status Code:200 OK
Accept:*/*
Host:localhost:8080
Referer:http://localhost:8080/GMS-web/resources/servicetest.html
Chrome/16.0.912.77 Safari/535.7
Request Payload

Content-Disposition: form-data; name="_phone_number"
6504669999
Content-Disposition: form-data; name="_provide_code"
true
Content-Disposition: form-data; name="language"
french
Content-Disposition: form-data; name="current_location_latitude"
48.8583
Content-Disposition: form-data; name="current_location_longitude"
2.2944
Result
The above service will be started with an id of 39a98e24-b03b-4191-b756-1efe8f3b16b8.
HTTP 200 OK
{
"_id":"39a98e24-b03b-4191-b756-1efe8f3b16b8",
"_access_number":"8003449999",
_access_code="7684"
}
JSON
JSON Body - Operation
Since 8.5.104, the Create Service query supports JSON inputs. You can now specify key/value pairs as
a JSON object. Because ORS allows simple key/value parameters, GMS cannot submit complex JSON-
structured values (such as maps and arrays) as ORS request parameters and convert complex values
to strings.
For example:
{
"address":"{street=mystreet, city=mycity}", // for map
"phones":"[9002@SIP_Switch, 5555666]" // for array
}
Important
The JSON API does not support form-encoded binaries.

Method POST
URL /genesys/1/service/{service}
URI Parameters
The name of the service
{service} string yes
to create and initiate.
Header
Content-type: application/json;charset=UTF-8
Body: A simple JSON structure representing key/value pairs.
• Keys that begin with "_" are ignored for storage.

• No binary values.
• Complex JSON-structured values (map and arrays) are converted to strings.
For example:
{
"lastname" : "mylastname",
"address": {
"street": "mystreet",
"city": "mycity"
},
"phones": [
"9002@SIP_Switch",
"5555666",
"7775666"
],
"_key":"ignored"
}
Response
HTTP code 200

HTTP message OK
If the JSON format is incorrect, the query returns a 500 error message.
HTTP code 500

HTTP message Server Error
{"message":"Could not read JSON: Unexpected
Body
character ('\"' (code 34)): [...]"}.
Example
POST http://localhost:8080/genesys/1/service/request-interaction
Content-Type:application/json
gms_user: default

{
"_phone_number":"6504669999",
"_provide_code":"true",
"language": "french",
"current_location_latitude":"48.8583",
"current_location_longitude":"2.2944"
}
Status Code: 200 OK
Update Conversation Expiration
Service Specific Request

This API allows the application to perform a specific request against a given service.
Important
This is only to be used for services that support such a request, otherwise it will be
rejected.
Operation
Method POST
URL /genesys/1/service/{service_id}/{request}
URI Parameters
The id of the service
that is to be requested.
This is the name of the
{request} string yes request that is to be
performed.
Body: The body can be either a MultiPart form or x-www-form-urlencoded form consisting of different
items representing the key/value pairs associated with the given service request. In the case of MultiPart,
the values can be strings or filesm but with urlencoded, the values can be only strings.

Response
HTTP code 200

HTTP message OK
This will contain the appropriate output data (JSON
Body data) that is defined by the given service request
definition.
Example
See the Chat Interaction APIs for an example.
Query All Keys

This API queries all of the keys in the storage area that has already been created for the service.
Note: Introduced in 8.5.000.12.
Operation
Method GET
URL /genesys/1/service/{id}/storage
URI Parameters
{id} string yes The id of the service.
Body: None
Response
HTTP code 200

HTTP message OK
Example
The following example queries all of the keys associated with service
efef8eb61-1f24-593d-90da-0034aca34b55.
Operation
Request URL (method GET)

/efef8eb61-1f24-593d-90da-0034aca34b55/storage
Result

{"Key2":"Value7","Key1":"Value6","Key3":"Value8”}
Query One Key

This API queries one of the keys in a storage area that has already been created for the service.
Note: Introduced in 8.5.000.12.
Operation
Method GET
URL /genesys/1/service/{id}/storage/{key}
URI Parameters
The key of the
value.
Body: None
Response
If the key exists, returns 200 OK and the following JSON format value: {"key4":"value4"} (not the
key value itself).
HTTP code 200

HTTP message OK
Returns 404: Not Found if the key is not found in the user data.
HTTP code 404

Example
efef8eb61-1f24-593d-90da-0034aca34b55.
Operation
Request URL (method GET)

/efef8eb61-1f24-593d-90da-0034aca34b55/storage/Key1
Request Method:GET
Result

Value1
Create or Update Service Storage

This API allows the creation of a new storage area or an update of the existing storage for a specific
service. The TTL of the user data storage is the same TTL as the service.
Operation
Method POST
URI Parameters
Body: A MultiPart form or a URL encoded form consisting of different items representing the key/value
pairs to store.
Response
HTTP code 200

HTTP message OK
Example
The following example stores:
Key1, Key2, Key3, and FileKey
Operation
Request URL:
Request Method:POST
Status Code:200 OK
Accept:*/*

Host:localhost:8080
Chrome/16.0.912.77 Safari/535.7
Request Payload
Value1
Value2
Value3
Result
The above data is now stored.
HTTP 200 OK
JSON
JSON Body
Starting in 8.5.104, you can update storage data with JSON arrays.
Because ORS allows simple key/value parameters, GMS cannot submit complex JSON-structured
values (such as maps and arrays) as ORS request parameters and convert complex values to strings.
For example:
{
"address":"{street=mystreet, city=mycity}", // for map
"phones":"[9002@SIP_Switch, 5555666]" // for array
}
Important
This query cannot handle binary values. To perform a request with an image, use the
multipart/form API query.

Operation
Method POST
URI Parameters
Header Parameters 'Content-type: application/json;charset=UTF-8
Body: The body is a JSON structure representing the key/value pairs.
• Keys that begin with "_" are ignored for storage.

• No binary values.
• Complex JSON-structured values (map and arrays) are converted to strings.
For example:
{
"lastname" : "mylastname",
"address": {
"street": "mystreet",
"city": "mycity"
},
"phones": [
"9002@SIP_Switch",
"5555666",
"7775666"
],
"_key":"ignored"
}
Response
HTTP code 200

HTTP message OK
HTTP code 500

HTTP message Server Error
{"message":"Could not read JSON: Unexpected
Body
character ('\"' (code 34)): [...]"}
Query Binary (One Binary Key)

This API queries one of the binary keys in a storage area that has already been created for the
service.
Note: Introduced in 8.5.002.02

Operation
Method GET
URL /genesys/1/service/{id}/storage/binary/{key}
URI Parameters
The key of the
value.
Body: None.

Response
HTTP code 200

HTTP message OK
HTTP code 404

HTTP message Not Found, if the binary key does not exists in user storage.
Example
The following example queries the value of myBinaryKey from the data associated with id efef8eb61-1f24-593d-90da-0034aca34b55.
Operation
Request URL (GET Method)

/efef8eb61-1f24-593d-90da-0034aca34b55/storage/binary/myBinaryKey
Result
Binary stream content and its content type.

Delete One Key Storage

This API deletes one of the keys (either binary or non-binary) in a storage area that has already been
created for the service.
Operation
Method DELETE
URL /genesys/1/service/{id}/storage/{key}
URI Parameters
{key} string yes The key to be deleted.
Body: None.
Response
HTTP code 200

HTTP message OK
Example
The following example deletes the value of Key1 from the data associated with id
efef8eb61-1f24-593d-90da-0034aca34b55.
Operation
Request URL:
/efef8eb61-1f24-593d-90da-0034aca34b55/storage/Key1
Request Method: DELETE
Result
OK
Delete All Keys in Storage

This API deletes all keys (binary or non-binary) in a storage area that has already been created for the
service.

Operation
Method DELETE
URI Parameters
Body: None.
Response
HTTP code 200

HTTP message OK
Example
The following example deletes all of the keys from the data associated with id
efef8eb61-1f24-593d-90da-0034aca34b55.
Operation
Request URL:
Result
OK
Delete Service
This API deletes the service that was created and the storage area associated with it.
Operation
Method DELETE
URL /genesys/1/service/{id}
URI Parameters

Method DELETE
Body: None.
Response
HTTP code 200

HTTP message OK
Example
The following example deletes the service id efef8eb61-1f24-593d-90da-0034aca34b55 and all the
keys from the data associated with it.
Operation
Request URL:
/efef8eb61-1f24-593d-90da-0034aca34b55
Result
OK

Genesys Mobile Services API Reference Calendar Service API
Calendar Service API
Overview
The Calendar Service API queries for all office hours so that your mobile app can make an intelligent
first offer to the user based on what's available in the next couple days, or with an explanatory hint
such as "Our offices are open from 8:00 am to 5:00 pm, please enter the desired
time.".
The calendar service API is intended to be tight to your office hours. It lets you handle the following
use cases.
• Find whether the office is open at the time of the query.

• If you call the API without any parameters, the start and end parameters are assumed to be now.
• Check in the response that the field error is null. If the list of periods is empty, it means that the
office is closed, otherwise, the office is open.
• Find the office's schedule for a given period.

• If you call the API and set the number-of-days-ahead_days parameter to 5, the start date is
assumed to be now. The response should contain any periods when the office is open.
Configuration
To configure office hours, create and configure an Office Hours service using the Service Management
UI, as detailed in the Help.
Be sure to update the existing calendar configuration to set the correct timezone for your business-
hours service. For instance, if you configured "EST", or "PST" timezones with the Genesys
Administrator Extension, your parameters must use the timezones defined for Java such as,
"America/Toronto" or "Europe/Paris". See Wikipedia list of correct timezones.
A complete list of options is available in the [office-hours] section of the Genesys Mobile Services
Options Reference guide.
REST API
The Calendar Service REST query retrieves the office hours per day for a provided period.

Calendar Service REST Request
GET /genesys/1/service/{service-execution-name}
Body
Start date is specified in
"ISO 8601" format,
using UTC as timezone:
start Date no "YYYY-MM-
ddTHH:mm:ssZ". If not
specified then it is
assumed to be now.
Specifies how many
days ahead to include
into interval beginning
form the "start" time.
Used as an alternative
number-of-days integer no to the end date. If
neither "end", nor
"number-of-days" is
specified, then end date
is assumed to be the
same as start date.
End date is specified in
"ISO 8601" format,
using UTC as timezone:
"YYYY-MM-
ddTHH:mm:ssZ". If
end Date no
neither "end", nor
"number-of-days" is
specified, then end date
is assumed to be the
same as start date.
Important
Other options from configuration section can be specified in the request.
Request example: GET http://127.0.0.1:8080/genesys/1/service/business-

hours?start=2014-12-03T15:00:00.000Z#ber-of-days=2
Calendar Service REST Response

The Calendar service returns an array of periods ordered in ascending chronological order.
• If the array is empty then there are no calendar events for the specified duration.
• If an error occurs while processing the request then the string error is specified in the "error" data field,
the contents of periods array, in that case, are undefined.

• Additional calendar information such as agent availability is returned in tags data field as a key-value
map.
• The open_for property reports how long the office will stay open in hours and minutes. Its format is
"hh:mm". Note that the value of the open_for property does not depend on any of the input
parameters. It returns the duration between the time at which the request was issued and the office
closing time. If the office is closed, then open_for = "00:00".
> GET /genesys/1/service/business-hours?start=2016-10-05T15:00:00.000Z#ber-of-days=2 HTTP/1.1

> Host: 127.0.0.1:8080
> User-Agent: curl/7.50.3
> Accept: */*
>
< HTTP/1.1 200 OK
< Set-Cookie: JSESSIONID=1wftsntzmfydfybt0v75gbprp;Path=/genesys;HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
<
{
"error": null,
"open_for": "11:20",
"periods": [
{
"start": "2016-10-05T15:00:00.000Z",
"end": "2016-10-05T21:00:00.000Z"
},
{
"start": "2016-10-05T23:00:00.000Z",
"end": "2016-10-06T21:00:00.000Z"
},
{
"start": "2016-10-06T23:00:00.000Z",
"end": "2016-10-07T15:00:00.000Z"
}
]
}

Genesys Mobile Services API Reference Capacity API
Capacity API
The Capacity Service enables you to define the number of scheduled callbacks that are allowed for
Callback for a given time slot in the week. Then, your Callback service refers to your Capacity service
and to your Office Hours service to adjust the agent availability and the number of scheduled
callbacks.
You can define exceptions for dates where less or more agents are available, and you can define as
many Capacity services that you need to match your Callback services. This way, you can address
the agent workload according to the real resources that are available.
Important
The Capacity applies to each individual _request_time_bucket time slot defined in the
GMS configuration.
For example, if _request_time_bucket=5 (for 5 minutes), then configuring capacity=10 means that
during a given hour, it is possible to create 10 callbacks for each of the 5 minute slots, therefore 120
callbacks for the full hour.
Configuration
Here is an example of GMS configuration:
[service.Capacity]
_capacity=[Mon, Tue, Wed, Thu, Fri, Sat, Sun]
_capacity_1={"1":{"0000":1,"0100":3}}
_capacity_2={"2":{"0100":3}}
_capacity_3={"3":{"1000":6,"1100":6,"1200":6,"1300":6,"1400":6,"1500":6,"1600":6,"1700":6,"1800":6,"1900":6,"200
_capacity_4={"4":{"1100":3,"0100":3}}
_capacity_5={"5":{"0100":3}}
_capacity_6={"6":{"0100":3}}
_capacity_7={"7":{"0000":1,"0100":3}}
_capacity_add={}
_service=capacity
_timezone=UTC
_type=builtin
Important
You can also configure a capacity service in the Service Management UI.

Capacity Service API

When you add a capacity service through the Configured Services interface, you can access the
capacity service by its execution name and retrieve its content through the API.
In order to find the available capacity, the query provides a date and time range. The response object
provides a list of time periods and available capacity for each period. Here is a list of input
parameters:
GET /genesys/1/service/{capacity-execution-name}
GET /genesys/1/service/{capacity-execution-name}?start=<date and time>&end=<date and

time>&timezone=<timezone>
Retrieves the capacity for the given service during the given period.
Name Required Description

Start date and time in ISO-8601
format without a timezone
start yes
component; for example:
2015-03-17T09:15:00.000
End date and time in ISO-8601
format without a timezone
end yes
component; for example:
2015-03-17T12:45:00.000
Timezone used for "start" and
timezone yes "end" parameters; for example:
America/Los_Angeles
For example, the following request will provide the following results:
GET /genesys/1/service/Capacity?start=2016-10-05T15:00:00.000Z HTTP/1.1

> Host: 127.0.0.1:8080
> User-Agent: curl/7.50.3
> Accept: */*
>
< HTTP/1.1 200 OK
< Set-Cookie: JSESSIONID=1opza084c3vszo631xnrtqw38;Path=/genesys;HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Transfer-Encoding: chunked
<
{
"error": null,
"slots": [
{
"utcTime": "2016-10-05T15:00:00.000Z",
"localTime": "2016-10-05T15:00:00.000Z",
"durationMin": 540,
"capacity": 6
},
{
"utcTime": "2016-10-06T01:00:00.000Z",
"localTime": "2016-10-06T01:00:00.000Z",
"durationMin": 60,
"capacity": 3

},
{
"utcTime": "2016-10-06T11:00:00.000Z",
"localTime": "2016-10-06T11:00:00.000Z",
"durationMin": 60,
"capacity": 3
}
],
"timezone": "UTC"
}
Capacity Provisioning API

Introduced in 8.5.212
Capacity Provisioning API is a new developer-friendly API that enables you to provision and update
Capacity settings. It introduces a CRUD (Create/Read/Update/Delete) set of operations which are not
limited by complex aspects of JSON into String option storage.
Important
This API requires Basic Authentication. Roles are not used.
POST genesys/1/admin/config/capacities
POST /genesys/1/admin/config/capacities
Creates capacity for the given service (provisioning).
JSON Body
Name Type Required Description
Execution name of the
service as created in the
name string yes
Configured Services
interface.
Timezone that defines
the translation of days
and times into UTC
time; the timezone is
used to calculate DST
timezone string no
switches. By default, the
timezone is set to "UTC".
To get the list of
supported timezones,
refer to Wikipedia.
A list of one or multiple
weekdays list yes entries associating
simplified timeslots with

a capacity for a
weekday.
This list can contain 1 to 7
entries only. Each entry
identifies one day of the week
using its 3-letter English short
name.
{
"mon": {
"0900": 10, "1000":
5 },
"tue": {
"0900": 10 },
"wed": {
"0900": 10 },
"thu": {
"0900": 10 },
"fri": {
"0900": 10 },
"sat": {
"0900": 10 },
"sun": {
"0900": 10 },
}
Each weekday can be

assigned 1 to 24 values
representing hour slots in the
form "HHmm" (24-hour format
and minutes) between "0000"
and "2300" and, for each hour
slot, the capacity is provided.
For example, "tue": {
"0900": 10} means that on
Tuesdays, the timeslot starting
at 9:00 am allows a capacity
of 10. If, in the service
options,
_request_time_bucket=5 (for
5 minutes), then provisioning
capacity=10 means that it is
possible to create 10 callbacks
for each of the 5 minute slots,
therefore 120 callbacks for the
full hour.
The maximum
capacity allowed
per slot is 1000 by
default. You can
change this value
using the
_max_capacity
option.
A list of additional
entries representing a
adds list yes
special day. For each
element, the key must

match a date in the

form "YYYYMMDD"
(year, month, day of the
month).
Each entry can be assigned 1
to 24 values representing hour
slots in the form "HHmm"
(24-hour format and minutes)
between "0000" and "2300".
{
"20190501": {
"0900": 10 },
"20190508": {
"0900": 10 }
}
Response
Success
HTTP code 200
HTTP message OK
Error
HTTP code 400
HTTP message Existing service name
{
"exception":
"com.genesyslab.gsg.services.capacity.CapacityException",
JSON Body
"message": "Name already exists. Please
choose another name."
}
Error
HTTP code 400
HTTP message Bad request
{
"exception":
"message": "Capacity entered is out
of range. Please enter a valid value"
JSON Body }
{
"exception":
"message": "<name/weekdays/adds> is

Error
a mandatory field."
}
{
"exception":
"message": "Parameters passed for
the capacity are empty."
}
{
"exception":
"message": "Timezone entered is
invalid. Please enter a valid timezone"
}
{
"exception":
"message": "Timeslot entered is out
}
Example of a successful operation
POST http://localhost:8080/genesys/1/admin/config/capacities
{
"name": "capacity-test",
"timezone": "UTC",
"weekdays": {
"mon": { "0900": 10, "1000": 10 },
"tue": { "0900": 10 },
"wed": { "0900": 10 },
"thu": { "0900": 10 },
"fri": { "0900": 10 },
"sat": { "0900": 10 },
"sun": { "0900": 10 },
},
"adds": {
"20190501": { "0900": 10 },
"20190508": { "0900": 10 }
}
}
Result
200 OK
GET /genesys/1/admin/config/capacities/{service_name}
Gets the capacity settings for a given service.

GET /genesys/1/admin/config/capacities/{service_name}
Gets the capacity provisioned for a given service.
URI Parameters
URI Parameters
{service_name} string yes
Configured Services
interface.
Response
Success
HTTP code 200
HTTP message OK
Response Body (JSON content)
name string yes
Configured Services
interface.
and times into UTC
timezone string no
To get the list of
refer to Wikipedia.
entries associating
a capacity for a
weekday.
name.
weekdays list yes
{
"mon": {
"0900": 10, "1000":
5 },
"tue": {
"0900": 10 },
"wed": {
"0900": 10 },
"thu": {

Success
"0900": 10 },
"fri": {
"0900": 10 },
"sat": {
"0900": 10 },
"sun": {
"0900": 10 },
}
Each weekday can be

options,
full hour.
match a date in the
form "YYYYMMDD"
month).
adds list yes to 24 values representing hour
between "0000" and "2300".
{
"20190501": {
"0900": 10 },
"20190508": {
"0900": 10 }
}
Error
HTTP code 400
HTTP message Bad service name
{
JSON Body
"exception":

Error
"message": "Name does not exist. Please
}
Example of sucessful operation
GET http://localhost:8080/genesys/1/admin/config/capacities/capacity-test
Result
200 OK
{
"timezone": "UTC",
"weekdays": {
"mon": { "0900": 10, "1000": 10 },
"tue": { "0900": 10 },
"wed": { "0900": 10 },
"thu": { "0900": 10 },
"fri": { "0900": 10 },
"sat": { "0900": 10 },
"sun": { "0900": 10 },
},
"adds": {
"20190501": { "0900": 10 },
"20190508": { "0900": 10 }
}
}
PUT /genesys/1/admin/config/capacities/{service_name}
Updates the capacity.
Warning
The request must contain all the provisioning settings, not only changes.

URI Parameters
service_name string yes service as created in the
Configured Services

interface.
Body (JSON content)
name string yes
Configured Services
interface.
and times into UTC
timezone string no
To get the list of
refer to Wikipedia.
entries associating
a capacity for a
weekday.
name.
{
"mon": {
"0900": 10, "1000":
5 },
"tue": {
"0900": 10 },
"wed": {
"0900": 10 },
weekdays list yes
"thu": {
"0900": 10 },
"fri": {
"0900": 10 },
"sat": {
"0900": 10 },
"sun": {
"0900": 10 },
}
Each weekday can be



options,
full hour.
The maximum
capacity allowed
per slot is 1000 by
default. You can
change this value
using the
_max_capacity
option.
match a date in the
form "YYYYMMDD"
month).
adds list yes to 24 values representing hour
between "0000" and "2300".
{
"20190501": {
"0900": 10 },
"20190508": {
"0900": 10 }
}
Response
Success
HTTP code 200
HTTP message OK
Error
HTTP code 400

Error
{
"exception":
JSON Body
}
Error
HTTP code 400
HTTP message Bad request
{
"exception":
"message": "Capacity entered is out
}
{
"exception":
"message": "Parameters passed for
the capacity are empty."
}
JSON Body
{
"exception":
"message": "Timeslot entered is out
}
{
"exception":
"message": "Date entered is out of
range. Please enter a valid date"
}
Example of successful operation
PUT http://localhost:8080/genesys/1/admin/config/capacities/capacity-test
{
"timezone": "UTC",
"weekdays": {
"mon": { "0900": 10, "1000": 10 },
"tue": { "0900": 10 },
"wed": { "0900": 10 },
"thu": { "0900": 10 },
"fri": { "0900": 10 },
"sat": { "0900": 10 },

"sun": { "0900": 10 },
},
"adds": {
"20190501": { "0900": 10 },
"20190508": { "0900": 10 }
}
}
Result
200 OK
DELETE /genesys/1/admin/config/capacities/{service_name}
Deletes the capacity provisioning for a given service.
DELETE /genesys/1/admin/config/capacities/{service_name}
Deletes the capacity provisioning.

URI Parameters
service_name string yes
Configured Services
interface.
Response
Success
HTTP code 200
HTTP message OK
Error
HTTP code 400
{
"exception":
JSON Body
}
Example of successful operation
DELETE http://localhost:8080/genesys/1/admin/config/capacities/capacity-test

Result
200 OK

Genesys Mobile Services API Reference Callback Services API
Callback Services API

Modified in: 8.5.2
Getting Started
When you add a callback service, you define a Service Name, which is referred to as {callback-
execution-name} in this API documentation. Each time that you perform a callback query, you must
specify the {callback-execution-name} in the URI parameters.
Accessing your Callback Service

The URLs used by the Callback API are dependent on the execution name of the Callback service that
you have just created. Callback services are available at the following URL:
http://<host>:<port>/genesys/1/service/callback/{callback-execution-name}
For instance, if you create a callback service named callback-for-mobile, then {callback-
execution-name} is callback-for-mobile, its configuration in GMS is located in the
service.callback-for-mobile section, and you can access the callback service at the following
URL:
http://<host>:<port>/genesys/1/service/callback/callback-for-mobile
Overwriting Configuration in Queries

To overwrite service configuration parameters in your POST REST queries (Start-Callback), use the
_overwritable_options option. This option lets you define a list of overwritable parameters that you
will be able to pass in the Body of your REST request.
Important
This list can include the _ors and _target options only.
For example, if you set:
_overwritable_options = _ors,_target
Then, you can pass _ors and _target in your REST query:
POST /1/service/callback/callback-for-mobile
{
"_ors": "http://myors:4421",

"_target": Billing@Stat_Server1.GA
}
Passing Configuration Tokens in Queries
Added in: 8.5.104

In your service configuration, you can create token variables that can be used in other configuration
parameters. Then, at runtime, you can pass values for these tokens in POST REST queries (Start-
Callback) and these values will be used to modify your configuration.


To create a token variable, create a new service parameter and configure its value with a string
matching the following format: $<any-token-name>$
For instance, create:
my_token_name = $my_token$
Then, you can use the body parameter my_token=<anyvalue> in your REST queries. As a result, the
occurrences of $my_token$ in this service configuration will be replaced with the query's provided
value.
For example, if you wish to create a callback request for the CLBCK-terminated-preview service
using the Stat_Server1 server target, use the following query:
POST /genesys/1/service/callback/CLBCK-terminated-preview
HTTP/1.1
Host: 127.0.0.1:8080
_customer_number=01822256&my_token=Stat_Server1
When GMS receives my_token=Stat_Server1 in the query information, it replaces the $my_token$
placeholder with Stat_Server1 everywhere that it is used in the configuration of CLBCK-terminated-
preview. Using our example, the result would be:
_target = Billing@Stat_Server1.GA
Tip
Use this feature to avoid duplicating configuration for multiple services that handle
the same functionality, but use different queues or servers.
Understanding Callback States

When the Callback request is submitted, it gets through several callback states and ORS handles
some of these callback states while processing the associated callback interaction. You can access
the callback status in the _callback_state parameter of the callback's JSON representation.
Important
The _callback_state parameter is incompatible with the _new_desired_time
property.

Callback states While in ORS Description
The customer is connected to an

PROCESSING
agent and talking with this agent.
The callback is actively waiting

QUEUED for an agent in ORS/URS; the
agent is not assigned yet.
The Callback service handles the
callback (there are no sessions
started in ORS). While in this
SCHEDULED state, the request is handled by
the callback service running in
GMS until the specified
desired_time is approaching.
Customer phone is reached and

ROUTING
waiting for an agent.
The call has ended and the

Callback is completed with the
COMPLETED
reason specified in
_callback_reason.
The call is paused. See Pausing

PAUSED
Callback for details.
Callback reasons in COMPLETED State
You can get the following reasons in the _callback_reason parameter when receiving the COMPLETED
state.
ABANDONED_IN_QUEUE

The Callback interaction was deleted prior to routing the interaction to the agent because the customer abandoned.
AGENT_CONNECTED
Callback Service successfully routed the interaction to the agent.
AGENT_PREVIEW_CANCEL
The agent canceled the callback preview request. To get this state reason, create an Agent First Preview service and configure the
following options with the following values, for example: _agent_preview=true, _agent_preview_allow_reject=3,
_agent_preview_set_notready_reason='Coffee Break',
_agent_preview_set_notready_reason_attribute=false,_agent_preview_set_notready_reason_key='ReasonCode',
_agent_preview_timeout_set_notready=true, _agent_preview_via_rp=false
AGENT_PREVIEW_CANCEL_AFTER_<n>REJECTS
The agent rejected the request '<n>' times.
AM_CONNECTED
Callback Service successfully routed the interaction to the answering machine.
CANCELLED
Callback Service received a cancel request for this callback.
CANCELLED_BY_ADMIN
Callback Service received a cancel request from the Service Management UI for this callback.
FAIL_AGENT_CONNECT
The Callback interaction could not be connected to the agent. This error may happen when the value of
_max_time_to_wait_for_agent_on_the_call is too short.
FAIL_CALL_TO_CUSTOMER
Replaces FAIL_USER_UNREACHABLE since GMS 8.5.102.14. Callback Service could not connect the customer.
FAIL_ERROR
Callback Service failed due to an unknown error.
FAIL_FAX_REACHED
Callback Service could not connect the customer. The provided number was answered by a fax machine.
FAIL_INBOUND_TIMEOUT
The customer did not make the call within the expected _booking_expiration_timeout period defined for User-Originated scenarios.
FAIL_INCORRECT_CONFIG_MEDIA_TYPE
The _media_type option is set to an incorrect value. Callback Service only processes voice and chat interactions.
FAIL_INTERACTION_DELETED
The callback interaction was deleted prior to routing the interaction to the agent. This error may happen when
_wait_for_agent=true and the agent hung up the call.

FAIL_IXN_UNKNOWN_MEDIA_TYPE
The media type of the interaction is not supported by Callback Service. Callback Service only processes voice and chat
interactions.
FAIL_LOAD_MESSAGE_FILE
Callback Service cannot load the strings resource file specified in the _notification_message_file option.
FAIL_NO_CUSTOMER_NUMBER
Customer number is missing.
FAIL_QUEUEING
The Callback request could not be queued. This error may happen when an error occurs while requesting the route delay to URS.
FAIL_TARGET_NOT_FOUND
Callback Service cannot reserve the requested target to handle the request. This error may happen when the value of
_urs_queued_ttl is too short.
FAIL_TIMEOUT_TTL
Callback Service did not manage to handle the request in the specified time (_ttl).
FAIL_USER_NO_CONFIRM
The user confirmation was not received although it was required; this issue can occur if _on_user_confirm_timeout is not set to
CONNECT-ANYWAY.
FAIL_USER_UNREACHABLE
Reported as FAIL_CALL_TO_CUSTOMER prior to GMS 8.5.102.14.
NOT_AVAILABLE
Callback Service exited with no specified reason.
SUBMIT_ERROR
GMS did not manage to submit the Callback service request to Orchestration Server for processing.
List of API Queries

The Callback Services API provides the following REST queries:
• Start or Schedule Callback–Initiate a Callback request.

• Cancel-Callback–Cancel a Callback request.
• Delete-Callback–Delete a Callback request.
• Reschedule-Callback–Reschedule a Callback request.
• Query-Availability—Get the availability for a new callback request.

• Query-Callback-By-Id–Query a callback by its ID.

• Query-Callback by Lookup Properties—Query outstanding callbacks by lookup properties.
• Query-Callback by Queue(s)—Query outstanding callbacks by queue(s).
• Query Counter Watermarks—Query the current set of executed callback instances in queues.
• Export Callback Records—Export Callback records.
Important
The documentation for "Query-EWT for Virtual Queues" was moved to the Stat Service
API page.
Start or Schedule Callback

Initiates a callback request. It validates the request by doing the following:
• Checks parameters, in general (in particular, if the target queue is valid).

• Checks the customer number against exceptions.
• Checks the time criteria of the request against the business.
• If invalid:
• Returns the appropriate error.
• Sends a reporting event to the GMS data manager indicating that the callback request has been
rejected.
• If valid:
• Creates a unique ID for the request.
• Sends a reporting event to the GMS data manager indicating that the callback request has been
accepted and started.
This event also indicates the state of the request (immediate or scheduled).
• If the request needs to be scheduled for a later date/time, the request and its associated data
will be stored in the module persistent data storage.
• If the request can be started now, an ORS session is initiated using the associated SCXML-based
service with this particular callback request.
Note: the provisioned data for the execution service to be started will be used as input
along with the input parameters from the request itself.
• Returns the ID generated for this request.
Starting in 8.5.2, you can redial a COMPLETED callback by submitting the callback ID to create a copy
of this callback. The properties and user data of the copied callback are merged with the parameters
of the new callback submitted in the POST query.
• The parameters specified in the POST query override the copied properties.

• Internal retry flags and properties such as _callback_state, _ors_session_id, _desired_time will be
ignored when creating the callback copy.
Tip
You can include any of the _xxx callback option parameters in your start query if they
are not configured in the service; for example _target, _wait_for_agent,
_paused_services_list, _paused_services_id, or any other _xxx parameter listed
in the Callback Service Options Reference Guide. If the option is already configured in
the service, the query parameter's value is ignored and the service option value is
used. See Overwriting Configuration in queries to learn about overwriting
configuration in queries.
POST /genesys/1/service/callback/{callback-execution-name}
Initiates a callback request.
Header
application/json
multipart/form-data
Content-type
URI Parameters
Name Type Description
callback-execution-name string Name of the callback execution

*required path service provisioned in GMS.
Body (JSON content)

Number to call back.
This parameter can also be replaced by
any parameter specified in the option
_customer_number*required string
_mandatory_customer_lookup_keys
(comma-separated list of attributes) that
can identify a unique customer.
ID of a Callback in COMPLETED
state. The properties and user
data of this completed callback
_copy_from_id are copied in the new callback
Introduced in 8.5.2 string and use for redial.
• Properties specified in the

POST request will override
copied properties.

• The following properties and

internal retry flags will be
excluded from the copy:
Desired time to have the

callback. By default, the desired
time is the current time.
This option format is ISO 8601 "yyyy-MM-
ddTHH:mm:ss.SSSZ" such as
"2013-05-28T15:30:00.000Z"
Note: The Callback is an immediate

Callback based on the following rule:
immediate = _desired_time <
{current_time} +
option(_request_execution_time_buffer) +
computed(option(_request_queue_time_stat))
Note that the desired time is

a time, not a duration.
Additional examples:
• _desired_time is in 1h,
_request_execution_time_b
uffer=300 (5min), statistic
set is "EstimatedWaitTime"
returning, for example, 10min
_desired_time string then the Callback is not
immediate and will be
submitted later for
execution because
immediate = today
16h > today 15h + 5
min + 10 min =
false
• _desired_time is in 5min,
_request_execution_time_b
uffer=120 (2min), statistic
set is "EstimatedWaitTime"
returning, for example, 5min
then the Callback is

immediate and is
submitted for
execution because
immediate = today
16h05 > today 16h +
2 min + 5 min =
true
Any properties key/values to be

attached. Key/Values may be
<property> string used in Orchestration
execution service. Keys without an

underscore prefix are User Attached Data.
The key must be a valid

ECMAScript variable name.
This means that variable
semantics that include
elements like "." (for
example, foo.foo) and "-"
(for example, foo-foo) are
not allowed.
Forces creation of Callback in a

specified state.
Important: This is for
advanced users that handle
_callback_state string Callback life-cycle externally to GMS. By
default, the _callback_state value is
either QUEUED or SCHEDULED depending if
the Callback is processed as immediate
or scheduled (respectively).
Queue to use for this callback if

several virtual queues are used
_urs_virtual_queue string
for callback with identical
configuration.
Queue statistics. For example,
"ExpectedWaitTime;Queue;8999@SIP_Server;Env
Note: If the
_request_queue_time_stat
_request_queue_time_stat string option is configured in the
Callback service, the
request parameter is
ignored.
Responses
Name Description
200 OK
_id The service id for which a successful callback
required request was registered.
ID
only for immediate callback Dialog Event ID
Action
only for immediate callback Dialog Action.
Text
only for immediate callback Text to display

Name Description
OkTitle
only for immediate callback Label for the OK button.
Name Value
500 Internal Server Error

Response body (JSON Content)
code 50006
phrase ORS_MAX_SUBMIT_RETRIES
"Callback {id} reached maximum attempts to submit to ORS

message reached ({max-attempts})"
exception com.genesyslab.gsg.services.callback.CallbackExceptionMaxORSSubmitAttempts
{ "id": "callback id", "max-attempts": <value for

properties _max_ors_submit_attempts> }
Name Value
429 Too Many Requests

code 40001
phrase NUMBER_ALREADY_BOOKED
"There is already {max_queued} or more Callbacks QUEUED for

message this number, please refer to _enable_in_queue_checking for
detail."
exception com.genesyslab.gsg.services.callback.CallbackExceptionAlreadyBooked
{ "max_queued": <1 if _enable_in_queue_checking=strict or

properties 2 if _enable_in_queue_checking=true>}

Name Value

code 40002
phrase THROTTLE_SERVICE_LIMIT
message "Limit of queued callbacks for {service} is reached."
exception com.genesyslab.gsg.services.callback.CallbackExceptionThrottled
"service": <service name>

properties
}
Name Value

code 40003
phrase THROTTLE_SERVICE_INTERVAL_LIMIT
"Limit of queued callbacks for {service} is reached for interval

message {interval}s."
"service": <service name>,

properties
"interval": <interval throttling limit>

Name Value

code 40004
phrase THROTTLE_SERVICE_PARAMETER_LIMIT
"Limit of queued callbacks for {service} is reached for

message parameter {parameter}. Reached {attempts} times today."
{ "service": <service name>,
"parameter": <parameter triggering the

properties throttling>,
"attempts": <number of attempts reached> }
Name Value
400 Bad Request

code 40020
phrase INVALID_OPERATION
• "Request cannot be processed because callback

message {id} to copy is not COMPLETED. Check
parameter _copy_from_id"
exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation
{"id": <callback id>,

properties
"time": <ISO UTC time>,
"state": <callback state>,

Name Value
"message": <ORS server's message>,
"filter": <filtering expression>

}
Name Value
400 Bad Request

code 40030
phrase CALLBACK_NOT_FOUND
message "Callback {id} to copy from cannot be found"
exception com.genesyslab.gsg.services.callback.CallbackExceptionNotFound
"id": <callback service id>,

properties
"time": <ISO UTC time>
Name Value
400 Bad Request

code 40050, 40051
• SLOT_UNAVAILABLE (40050)
phrase
• SLOT_UNAVAILABLE_PROPOSAL(40051)

Name Value
• "No time slots available."

• "Too many requests at desired time slot {slot}.
message Proposing time slots."
• "Office is closed at desired time slot {slot}.
Proposing time slots."
exception com.genesyslab.gsg.services.callback.CallbackExceptionAvailability
"slot": <ISO UTC time range>,

properties
Name Value

code 50020
phrase BAD_CONFIGURATION
• "Service option {service} / _default_country is

not configured. But option
_disallow_impossible_phone_numbers is set. We
cannot validate phone numbers without
knowing the country."
_disallow_premium_phone_numbers is set. We
message cannot validate phone numbers without
• "Unable to parse option:
_request_queue_time_stat={statistic}"
• "Missing default_chat_endpoint option in chat
section because this service has parameter
_media_type=chat"
• "Missing default _client_timeout option in chat

Name Value

_media_type=chat"
• "Option service.{service} /
_business_hours_service not configured."
• "Option _business_hours_service is invalid:
{message}"
• "Service undefined: {service}"
• "Service {service} has unknown value for
option _type"
• "Service {service} has option _type != ors"
• "Service {service} has option _service !=
callback"
exception com.genesyslab.gsg.services.callback.CallbackExceptionConfiguration

properties
}
Name Value

code 50005
phrase CALENDAR_ERROR
message message returned by Calendar service
exception com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError
properties

Name Value

code 50004
phrase CAPACITY_ERROR
message message returned by Capacity service
exception com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError
properties
Name Value

code 50030
phrase ORS_ERROR
• "Invalid ORS response"

message
• message returned by ORS strategy
exception com.genesyslab.gsg.services.callback.CallbackExceptionFromORS
properties
Name Value

code 50040

Name Value
phrase SERVICE_REDIRECT_FAILED
message message from redirected service
exception com.genesyslab.gsg.services.callback.CallbackExceptionServiceRedirect
properties
Name Value
400 Bad Request

code 40040
phrase NUMBER_REJECTED
• "Customer Number is not allowed, because it is

invalid. Check option "Customer Number is not
allowed, because it is invalid. Check option
_disallow_impossible_phone_numbers"
• "Customer Number is not allowed, because it's a
premium number. Check option
message _disallow_premium_phone_numbers"
• "Customer Number is not allowed, because it
failed validating. Check option
• "Customer Number is not allowed. Check option
_exceptions"
exception com.genesyslab.gsg.services.callback.CallbackExceptionNumber
properties
Name Value


Name Value
code 50050
phrase UNKNOWN_ERROR
message "Error processing callback {message} "
exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown
properties { "message": <message catched> }
Example
POST http://localhost:8080/genesys/1/service/callback/request-callback
{
"_customer_number": "5115",
"usr_customer_name": "Bob Markel",
"usr_reason": "billing question",
"_device_notification_id":
"b16416334828b1d26ef14f329628b55b5a8c631d8928a371a5584722dd7fb673",
"_device_os": "comet",
"_desired_time":"2013-06-17T10:25:00.000Z"
}
Result
200 OK
{
"_id":"a550a12e-ca77-4146-98d0-58960e0939f7"
}
The result of this operation is different if the callback is immediate or schedule. If immediate, some
information may be returned in response along with service_id.
200 OK
{
"ID": "0",
"Action": "ConfirmationDialog",
"Text": "You will receive the call shortly",
"OkTitle": "Ok",
"_id": "361-58ce803e-362c-477f-8ac8-5bbc93f9acc7"
}
Cancel-Callback
The Cancel-Callback API cancels a Callback request, by doing the following:
• Validates that the request is still in the queue.

• If not, returns the appropriate error.

• If valid, removes the request from the scheduling queue.
• Checks the state of the Callback request:

• If _callback_state=QUEUED, a callback cancel event is submitted to the execution service.
• Callback request is marked _callback_state=COMPLETED with _callback_reason=CANCELLED.
DELETE /genesys/1/service/callback/{callback-execution-
name}/{service_id}
Cancels a Callback request
URI Parameters

*required path service of 'ors' type provisioned
in GMS.
string This is the service id returned
service_id *required path from the initial start callback
response.
False by default. If true, GMS can
bypass ORS failures and marks
the cancellation of the callback.
discard_ors_failure boolean Set this option to true to manage

troubleshoot cases that happen if the
callback session is exited in ORS while
the record is not marked as COMPLETED in
GMS.
Responses
200 OK
No JSON Body
Name Value
400 Bad Request

code 40010
phrase BAD_PARAMETER

Name Value
• Generic parser exception message: Typically, a

bad date parsing may fall there as a bad
parameter error with the appropriate
message statement.
• Generic missing parameter exception message
(case of controller level detection).
exception com.genesyslab.gsg.services.callback.CallbackExceptionBadParameter
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,

properties
"properties": <lookup properties>,
"option": <invalid option key>
Name Value
400 Bad Request

code 40020
• "Callback {id} does not contain _desired_time

property."
• "Callback {id} cannot be cancelled or
completed - _callback_state={_callback_state}"
• "Callback {id} cannot be cancelled - unable to
message
process ORS cancel request : {message} "
• "Callback {id} cannot be cancelled - No ORS
session found. (_callback_state=QUEUED while
_ors_session_id=null?)"
• "Rejecting update : {service}=[{id} @ {time}] -

Name Value
reached state COMPLETED"

properties
Name Value
400 Bad Request

code 40030
• "Callback {id} cannot be found"

message • "Callback {id} cannot be found - {service}=
[{id} @ {time}]"

properties

Name Value

code 50030
phrase ORS_ERROR

message
properties
Name Value

code 50050
Examples
DELETE http://localhost:8080/genesys/1/service/callback/BasicCallback/a550a12e-
ca77-4146-98d0-58960e0939f7
Result 200 OK
DELETE http://localhost:8080/genesys/1/service/callback/BasicCallback/a550a12e-
ca77-4146-98d0-58960e0939f7

Result 400 Bad Request

{
"message": "No such request to cancel : [a550a12e-ca77-4146-98d0-58960e0939f7]",
"exception": "com.genesyslab.gsg.services.callback.CallbackException"
}
DELETE http://localhost:8080/genesys/1/service/callback/callback-test/361-cf088d4e-88ab-452c-
ac1f-39086cc96cbe
Result 400 Bad Request
{
"message": "Request already cancelled or completed : [361-cf088d4e-88ab-452c-
ac1f-39086cc96cbe]",
"exception":
"com.genesyslab.gsg.services.callback.exceptions.CallbackExceptionInvalidOperation"
}
If you set discard_ors_failure=true, the previous query will get a 200 OK response, though the
error will be logged as an error in ORS.
DELETE http://localhost:8080/genesys/1/service/callback/callback-test/61-cf088d4e-88ab-452c-
ac1f-39086cc96cbe?discard_ors_failure=true
Result 200 OK
Reschedule-Callback
The Reschedule-Callback API changes various input parameters associated with a given callback
service. This request will have the Callback request id that is to be updated. This API does the
following:
• Validates that the request is still in the scheduling queue.

• If not, returns the appropriate error.
• If valid, updates the request in the scheduling queue.
Note: The Reschedule operation is available only for requests where _callback_state=SCHEDULED.
PUT /genesys/1/service/callback/{callback-execution-name}/{service_id}
Reschedules a Callback request
Header
application/json
multipart/form-data
Content-type
URI Parameters

in GMS.

string This is the service id returned

service_id *required path from the initial start callback
response.
Body (JSON content)
The new time for which to
reschedule the callback.
If provided and validated through office-
_new_desired_time string hours, _callback_state will be
automatically switched to "scheduled" or
"immediate", discarding
_callback_state property.
Possible values are SCHEDULED,

QUEUED, ROUTING, PROCESSING,
COMPLETED.
_callback_state string Note: The _new_desired_time parameter
triggers the re-schedule operation,
discarding the _callback_state
parameter.
Properties to be updated in
<other properties> any
request.
Responses
200 OK
No JSON Body
Name Value
400 Bad Request

code 40010
• "Callback {id} does not contain the mandatory

customer lookup keys {keys}"
• "Callback {id} does not contain _desired_time
property."
message • "Callback {id} contains _desired_time
property in the past (-%ds < %ds < %ds) -
epoch %ds"
• "Callback request contains _desired_time
property too far in future (-%ds < %ds < %ds) -

Name Value
epoch %ds"
• "Cannot create service, missing mandatory
callback option {option}"
• "Cannot create service, empty mandatory
callback option {option}"
statement.

properties
"option": <invalid option key> }
Name Value
400 Bad Request

code 40020
• "Invalid service stored for callback {id}."

• "Request cannot be processed because callback
{id} to copy is not COMPLETED. Check
message parameter _copy_from_id"
• "Callback {id} is no longer scheduled. State=
{state}"
• "Callback {id} has invalid desired time stored."

Name Value
• "Rejecting update : {service}=[{id} @ {time}] -

reached state COMPLETED"

properties
Name Value
400 Bad Request

code 40030
• "Callback {id} cannot be found"

message • "Callback {id} cannot be found - {service}=
[{id} @ {time}]"

properties

Name Value
400 Bad Request

code 40050, 40051
phrase

message Proposing time slots."

properties
Name Value

code 50020

message not configured. But option
_disallow_impossible_phone_numbers is set. We

Name Value

_media_type=chat"
_media_type=chat"
{message}"
option _type"
callback"

properties
}
Name Value

code 50005

Name Value
properties
Name Value

code 50004
properties
Name Value

code 50030
phrase ORS_ERROR

message

Name Value
properties
Name Value
400 Bad Request

code 40040
phrase NUMBER_REJECTED
• "Customer Number is not allowed, because it is

invalid. Check option "Customer Number is not
allowed, because it is invalid. Check option
• "Customer Number is not allowed, because it's a
premium number. Check option
message _disallow_premium_phone_numbers"
• "Customer Number is not allowed, because it
failed validating. Check option
• "Customer Number is not allowed. Check option
_exceptions"
exception com.genesyslab.gsg.services.callback.CallbackExceptionNumber
properties
Name Value

code 50050

Name Value
Examples
Successful Rescheduling
PUT http://localhost:8080/genesys/1/service/callback/
BasicCallback/a550a12e-ca77-4146-98d0-58960e0939f7
{
"_new_desired_time":"2013-05-27T15:05:00.000Z"
}
Result
200 OK
Failed Rescheduling
PUT http://localhost:8080/genesys/1/service/callback
/callback-test/361-d61e636da-3109-436c-877e-8d7174277bb9
{
}
Result
400 Bad Request
{
"message": "Callback '361-738dadcb-9d20-4557-8e24-fddb82f9c1b8'
is no longer scheduled. State=PROCESSING",
"exception": "com.genesyslab.gsg.services.callback.exceptions
.CallbackExceptionInvalidOperation"
}
No availability
PUT http://localhost:8080/genesys/1/service
/callback/BasicCallback/a550a12e-ca77-4146-98d0-58960e0939f7
{
}
Result
400 Bad Request
{
"message": "Too many requests at desired time
[2013-05-27T16:45:00.000Z, 2013-05-27T16:50:00.000Z].
Proposing time slots.",
"exception": "com.genesyslab.gsg.services.callback
.CallbackExceptionAvailability",
"availability":
{
"2013-05-27T16:50:00.000Z": 5,
"2013-05-27T16:35:00.000Z": 5,
"2013-05-27T16:40:00.000Z": 5,
"2013-05-27T16:55:00.000Z": 3,

"2013-05-27T16:25:00.000Z": 5,
"2013-05-27T16:30:00.000Z": 5
}
}
Sample operation typically performed by ORS execution
PUT http://localhost:8080/genesys/1/service/callback
/callback-test/361-738dadcb-9d20-4557-8e24-fddb82f9c1b8
{
"_callback_state":"PROCESSING",
"_reason":""
}
Result
200 OK
{}
Delete Callback (Forget Me)
Deletes one or more Callback Service instance(s) by passing service IDs or Customer Numbers. You
can delete a Callback only if it is in SCHEDULED or COMPLETED status. This API enables you to support
General Data Protection Regulation and enables you to "forget" customers.
To use this query, you need Basic Authentication. Therefore, you must provide the authentication
credentials in the auth parameter of the operation. There are two ways to provide credentials in an
auth object:
• In an open form containing the username and password fields of a user defined in the Configuration
Server.
• In an encoded form using encoded fields, similar to the Basic Authentication header, which is a
Base64-encoded composite string of "username:password".
POST /genesys/1/admin/callback/ops/delete
Deletes one or more callback request(s).
Header
application/json
Content-type
Body (JSON content)

List of Customer Numbers or
Service IDs that identify the
_customer_number String array
callback service instances that
must be deleted.
List of service IDs that identify
_id String array the callback service instances
that must be deleted.

Responses
Name Description
200 OK
Array of service IDs and
Customer Numbers that were
deleted or were considered as
successful with a reason.
success
[{ "_id": "68542134" },
required Array
{ "reason": "no
callback(s) to delete",
"_customer_number":
"132456" } ]
Array of service IDs and

Customer Numbers that were
not deleted with the associated
error codes.
[{ "non-existing-lookup-
key": "132456", "code":
40010, "phrase":
"BAD_PARAMETER",
errors "message": "No such
required Array lookup possible for
{properties}" },
{ "code": 40020, "phrase":
"INVALID_OPERATION", "_id":
"118-576b21b4-a235-4ba5-92d4-102cbbb54bca",
"message": "Callback
118-576b21b4-a235-4ba5-92d4-102cbbb54bca
cannot be deleted -
_callback_state=PROCESSING" } ]
Name Value

code 50020

message _disallow_impossible_phone_numbers is set. We

Name Value

_media_type=chat"
_media_type=chat"
{message}"
option _type"
callback"

properties
}
Name Value
400 Bad Request

code 40010

Name Value
• "No such lookup possible for {properties}"

• "No lookup possible. No properties to look for."
message bad date parsing may result in a bad parameter
error with the appropriate statement.

properties
Name Value
400 Bad Request

code 40020
message "Cannot process 'filter' parameter correctly : {filter}"

properties

Name Value
Name Value

code 50050
Example
POST http://localhost:8080/genesys/1/admin/callback/ops/delete
{
"_id": ["118-576b21b4-a235-4ba5-92d4-102cbbb54bca"],
"_customer_number": [
"132456",
"1111",
"3333"
]
}
Result
Response: 200 OK
{
"success": [
{
"reason": "no callback(s) to delete",
"_customer_number": "132456"
},

{
"_id": "118-27f3bed5-6e3a-4c89-903f-dae562b30481"
},
{
"_id": "118-c2ce7a84-d33a-4d8d-88a0-b76a563f2324"
}
],
"errors": [
{
"code": 40020,
"phrase": "INVALID_OPERATION",
"_id": "118-576b21b4-a235-4ba5-92d4-102cbbb54bca",
"message": "Callback 118-576b21b4-a235-4ba5-92d4-102cbbb54bca cannot
be deleted - _callback_state=PROCESSING"
}
]
}
Query Callback By ID
Retrieves a callback request by its ID.
GET /genesys/2/service/callback/{callback-execution-name}/{id}
Queries the outstanding callback associated with a given ID.
URI Parameters

in GMS.
string
id *required path Callback ID.
Responses
Name Description
200 OK
• If accepted, the currently outstanding callback

request.
[
<none>
{
"_id": <callback id>,
"desired_time": <ISO UTC time>,
"url": <service URL>,

Name Description
"_expiration_time": <ISO UTC time>,

"_service_name": <service-name>,
"_customer_number": <customer
number>,
"_callback_state": <callback state>,
"_time_scheduled": <ISO UTC time>
}
]
• If not, an error code indicating the reason.
Name Value
400 Bad Request

code 40010

message bad date parsing may result in a bad parameter
error with the appropriate statement.

properties

Name Value
400 Bad Request

code 40020

properties
Name Value

code 50050

Example
GET http://localhost:8080/genesys/1/service/callback/BasicCallback/120-07f85068-650d-4cce-
a5e7-396dfa22455b
Result
200 OK
{
"_callback_state": "SCHEDULED",
"_expiration_time": "2020-05-11T11:59:59.000Z",
"_service_name": "BasicCallback",
"_id": "124-07f85068-650d-4cce-a5e7-396dfa22455f",
"_url": "/genesys/1/service/callback/BasicCallback/120-07f85068-650d-4cce-
a5e7-396dfa22455b",
"_time_scheduled": "2020-04-16T12:52:31.521Z",
"_desired_time": "2020-04-27T12:00:00.000Z"
}
Query-Callback by Lookup Properties

Modified in 8.5.111

The Query-Callback API queries the current set of outstanding Callback services associated with a given property.
Notes:
• Outstanding Callback services are requests where _callback_state is one of the following values: SCHEDULED, QUEUED, ROUTING, PROCESSING,
COMPLETED.
• Properties allowing the Callback request trackback are defined as comma-separated keys with the service option _customer_lookup_keys.
• The API returns each callback for which the looked-up property is or was equal to the value specified in the requested property.
• Starting in 8.5.111, you can configure the list of values to be retrieved when calling this query by setting the returned-keys option at the GMS application
level.
• To use the _customer_number lookup property regardless of whether you specify a callback service name or not in the API URL, the
_fix_plus_on_int_phone_numbers option must be identical in the callback section and in each service-specific section.
• This is the expected behavior if you stick to defaults.
• If a callback service has a distinct value for _fix_plus_on_int_phone_numbers, you can only use the _customer_number lookup property by specifying
the service name in the API URL.
GET /genesys/1/service/callback/{callback-execution-name}?{property=value}
GET /genesys/1/service/callback?{property=value}
Queries the current set of outstanding Callback services associated with a given property.
URI Parameters
string Name of the callback execution service of 'ors'
callback-execution-name path type provisioned in GMS.
This is a property name used to query the

string
*required callback. Properties allowing the Callback request
property=value path trackback are defined as comma-separated keys
with the service option _customer_lookup_keys.

If you specify several properties, you may need to use the

operand property.
Operand to use for the properties defined in the

service option _customer_lookup_keys. Possible
values are AND or OR. Default is AND.
When multiple property=value are provided in the query, the
operand specifies which operation to perform on matched
operand string Callback requests:
• AND means that all property=value must

match;
• OR means any property=value can match.
Specifies a unique state to filter onto. For example:
• _callback_state='COMPLETED' filters
callbacks and returns only callbacks in
COMPLETED state.
_callback_state • _callback_state='!COMPLETED' filter

string callbacks and only return the ones that are not
Since 8.5.101.03 COMPLETED.
Important
The character "!" is used to negate a case.
You can query the following callback states: SCHEDULED,

QUEUED, ROUTING, PROCESSING, COMPLETED.
_desired_time_from Specifies ISO timestamps. All callback matching lookup

string properties that were scheduled before this time will be filtered
Since 8.5.101.03 out.

_desired_time_to Specifies ISO timestamps. All callback matching lookup

string properties that were scheduled after this time will be filtered
Since 8.5.101.03 out.
Responses
200 OK
• If accepted, JSON array of service IDs of the

currently outstanding callback requests.
[
{
"_id": <callback id>,
"desired_time": <ISO UTC time>,
"_callback_state": <callback
state>,
<none> "_expiration_time":<ISO UTC time>,
"_customer_number": <customer
number>,
"url": <service URL>
},
...
• If not, an error code indicating the reason.

Name Value
400 Bad Request

code 40010

message • Generic parser exception message: Typically, a bad date parsing may
result in a bad parameter error with the appropriate statement.
• Generic missing parameter exception message (case of controller level
detection).

properties

Name Value
400 Bad Request

code 40020

properties

Name Value

code 50050
Example
GET http://localhost:8080/genesys/1/service/callback
/BasicCallback?_customer_number=555-5461206
Result
200 OK
[
{
"_id": "a550a12e-ca77-4146-98d0-58960e0939f7",
"desired_time": "2013-05-27T15:05:00.000Z",
"_callback_state": "QUEUED",
"_customer_number": "555-5461206",
"url": "/1/service/callback/BasicCallback/a550a12e-ca77-4146-98d0-58960e0939f7"

},
{
"_id": "4a1ea889-1ef7-432d-a543-cff96b4a2daf",
"desired_time": "2013-05-27T15:10:00.000Z",
"_customer_number": "555-5461206",
"url": "/1/service/callback/BasicCallback/4a1ea889-1ef7-432d-a543-cff96b4a2daf"
}
]

Query-Availability
v1
Query-Availability v1
This query returns a simple map of slots in which the office capacity is not full.
GET /genesys/1/service/callback/{callback-execution-name}/availability
Returns a simple map of slots in which the office capacity is not full.
URI Parameters

in GMS.
JSON Body
Start date is specified in ISO
8601 format, using UTC as the
timezone: yyyy-MM-
start date
ddTHH:mm:ss.SSSZ. If not
specified, it is assumed to be
now.
Alias to start parameter; kept
timestamp date
for compatibility reasons.
Used as an alternative to the end
date. If neither end nor number-
number-of-days integer of-days is specified, the end
date is assumed to be the same
as the start date.
End date is specified in ISO 8601
format, using UTC as timezone:
yyyy-MM-ddTHH:mm:ss.SSSZ. If
end date neither end nor number-of-days
is specified, the end date is
assumed to be the same as the
start date.
Maximum number of time slots
to be included in the response
when the office is open and
max-time-slots integer capacity is above zero. It can be
used to improve the performance
of the query over a long period of
time.

Important
If neither of the parameters number-of-days and end parameters are specified, the
default time range matches 1 bucket only (as configured in the _request_time_bucket
service option).
Request example:
GET http://localhost:8080/genesys/1/service/callback/Callback_VQ/
availability?start=2014-12-03T15:00:00.000Z
Response
The Callback controller provides a facet to the availability service, which uses the calendar service
underneath. Just as the calendar service takes three non-mandatory input parameters (start, number-
of-days, end), the availability service should accept the same parameters and pass them on to the
calendar service.
• The response contains a map of time slots and capacity counters.

• The slots are ordered in ascending order.
• Any time slots where the capacity is full (for example, zero) are not provided in the response. Similarly,
if the office is closed, those time slots are not provided in the response.
200 OK
{
// All periods are ordered in ascending time order
"2014-10-17T13:00:00.000Z":"5",
"2014-10-17T13:10:00.000Z":"4",
// there were no agents available between 13:20 and 13:30 UTC
//hence the time slot is not reported
"2014-10-17T13:30:00.000Z":"5"
}
v2
Query-Availability v2
This query includes more query options than v1 and returns an array of ordered slots that include
detailed capacity information and timezone information.
GET /genesys/2/service/callback/{callback-execution-name}/availability
Returns an array of ordered slots that include detailed capacity information and timezone
information.
URI Parameters


in GMS.
Start date in the "ISO 8601"
format, using the UTC timezone:
"yyyy-MM-ddTHH:mm:ss.SSSZ".
If not specified, the default start
date is the date on which the
query was submitted.
• If you set the start

start date parameter, do not set the
start-ms or timestamp
parameters.
• You must also set the end or
number-of-days parameter;
otherwise, the end date is
assumed to be the start
date.
Start date in epoch time, that is,

the number of milliseconds since
00:00:00, Thursday, 1
January 1970 (UTC).
• You must also set the end-ms

or number-of-days
start-ms long parameter; otherwise, the
end date is assumed to be
the start-ms date.
• If you set the start-ms
parameter, do not set the
start or timestamp
parameters.
Number of days used to define

the availability period starting at
the start or start-ms date. You
number-of-days integer
can use this parameter instead of
the end or of the end-ms
parameter.
End date, in "ISO 8601" format,
using the UTC timezone: yyyy-
MM-ddTHH:mm:ss.SSSZ. By
end date default, if neither the "end" nor
the "number-of-days" parameter
is specified, then the end date is
assumed to be the start date.
End date in epoch time, that is
the number of milliseconds since
end-ms long
00:00:00, Thursday, 1
January 1970 (UTC).

Set only one of the end, end-ms, or

number-of-days parameters.
Maximum number of time slots

to include in the response if the
office is open and the capacity
max-time-slots integer greater than zero. You can use
this parameter to improve query
performance over a lengthy
period of time.
Timezone for the start and end
date parameters. Additionally,
timezone string the response object will return
the localTime fields formatted in
this timezone.
If true, the response includes the
slots where the office is open and
report-busy boolean where callbacks are booked to
full capacity. By default, report-
busy is false.
JSON body: None.
Important
If neither of the parameters number-of-days, end, and end-ms parameters are
specified, the default time range matches 1 bucket only (as configured in the
_request_time_bucket service option).
Responses
If successful, the response returns multiple values that describe the slots, availability, and capacity
for a given slot.
200 OK
Array of ordered slots and each slot

includes the minute duration
(durMinutes), and the timezone.
slots
required String array of slots • The array of slots includes
detailed information about
each slot.
• Slots are sorted in ascending

order by their time.

• Slots are all the same
duration, specified in the
durMinutes value.
• The "timezone" value
specifies the timezone used
for the "localTime" fields in
slots' information.
{
"slots": [
{
"utcTime": <UTC time>,
"localTime": <UTC
time>,
"capacity": <capacity>,
"total": <total>
},
(...) ]
"durationMin": <duration
in minutes>,
"timezone": <timezone>
}
Each slot includes:
• "utcTime" specifies when this

slot begins in UTC time.
• "localTime" reports the same
time as "utctime", but
formatted using the
"timezone" set in the request.
• "capacity" value is the
number of available callbacks
that can be scheduled within
this timeslot.
• "total" is the total capacity
that is configured for this
timeslot.
Name Value
400 Bad Request

code 40010

Name Value
• "day parameter must be between 1 and 7,

inclusively. Actual value is: {day}"
• "No time slots available. The requested time
period is in the past."
message • Generic parser exception message: Typically, a

statement.

properties
Name Value
400 Bad Request

code 40050, 40051
phrase

message

Name Value


properties
Name Value

code 50020
{message}"
message
option _type"
callback"
{
properties

Name Value
}
Name Value

code 50005
properties
Name Value

code 50004
properties

Name Value

code 50050
Examples
Request example:
http://localhost:8010/genesys/2/service/callback/callback-PST
/availability?start=2016-04-13T09:00:00.000&end=2016-04-13T16:00:00.000
&timezone=America/Toronto
{
"slots": [
{
"utcTime": "2016-04-13T13:00:00.000Z",
"localTime": "2016-04-13T09:00:00.000",
"capacity": 42,
"total": 100
},
{
"utcTime": "2016-04-13T13:05:00.000Z",
"localTime": "2016-04-13T09:05:00.000",
"capacity": 67,
"total": 100
},
{
"utcTime": "2016-04-13T13:10:00.000Z",
"localTime": "2016-04-13T09:10:00.000",
"capacity": 91,
"total": 100
}
...
],
"durationMin": 5,
"timezone": "Eastern Standard Time"
}

Important
Existing calendar configurations must be updated for the time zone definition. Instead
of EST or PST time zones that were configured using Configuration Manager, you must
use time zones as allowed in Java (http://en.wikipedia.org/wiki/
List_of_tz_database_time_zones), such as America/Toronto, or Europe/Paris. You
must also change the service option _type from ors to builtin.
Query-Callback by Queue(s)
Modified in 8.5.111
The Query-Callback API queries the current set of outstanding Callback services in the given
queue(s).
Starting in 8.5.111, you can filter and configure the list of values to be passed and retrieved when
calling this query through the following options at the GMS application level: returned-keys and filter-
keys.
Important
Outstanding Callback services are requested if their _callback_state is one of the
following values: SCHEDULED, QUEUED, ROUTING, PROCESSING, COMPLETED.
auth object:
Server.
GET /genesys/1/admin/callback/queues?target={callback-execution-
name}☆t_time={iso_start_time}&end_time={iso_end_time}
Queries the current set of outstanding Callback services in given queue(s).
URI Parameters
{iso_start_time} string This is the minimum time for

which to query callback requests.

The format is ISO 8601 "yyyy-MM-
ddTHH:mm:ss.SSSZ".
For example:
"2013-05-27T15:30:00.000Z"
This is the maximum time for

which to query callback requests.
If not specified, requests that are due in
the next 24 hours are returned.
{iso_end_time} string
The format is ISO 8601 "yyyy-MM-
ddTHH:mm:ss.SSSZ".
For example:
"2013-05-28T15:30:00.000Z"
Comma-separated list of callback

states used to filter the returned
results. For example, if
states=SCHEDULED,QUEUED, only
{states} string scheduled and queued callbacks
are returned.
If not specified, all the callbacks of the
given queue are returned.
This is the maximum number of

requests to return for each
queue.
{max} integer
If not specified, 500 maximum requests
per queue are returned.
Name of the callback execution

service provisioned in GMS. For
example, BasicCallback.
callback-execution-name string
If not specified, the queues for all
services are returned.
This is the maximum number of

requests to return for each
queue.
{max} integer
If not specified, 500 maximum requests
per queue are returned.
Responses
Name Mandatory Description
200 OK

Name Mandatory Description
If accepted, a tree list of target queues

and the following properties:
<Queue name>: {
"_customer_number":
<customer number>,
List of target queues "_callback_state": <callback

required string state>,
"_desired_time": <callback
UTC desired time>,
"_id": <callback service id>,
"url": <request>
Name Value
400 Bad Request

code 40020
"Query range spans too wide time range (%d / %d). Adjust
message query parameters for time range."

properties

Name Value

code 50050
Example
GET http://localhost:8080/genesys/1/admin/callback/queues
Result
200 OK
{
"BasicCallback":
[
{
"_callback_state": "PROCESSING",
"_desired_time": "2013-06-07T16:25:00.000Z",
"_id": "fd30abb97bd04885b544893276fb534b",
"url": "/1/service/callback/BasicCallback/fd30abb97bd04885b544893276fb534b"
}
],
"AdvancedCallback":
[
{
"_callback_state": "QUEUED",
"_desired_time": "2013-06-07T16:35:00.000Z",
"_id": "07d2ddd506f04b4ba91aba59c4fa8871",
"url": "/1/service/callback/AdvancedCallback/07d2ddd506f04b4ba91aba59c4fa8871"
},
{
"_desired_time": "2013-06-07T16:45:00.000Z",
"_id": "8f68d4969d904d039ccf0101fac39283",
"url": "/1/service/callback/AdvancedCallback/8f68d4969d904d039ccf0101fac39283"

}
]
}
Query Counter Watermarks

This query counts the current set of executed callback instances per queues or for a given queue.
Executed callback instances are:
• Callbacks that are in execution within ORS

• Callbacks do not have their _callback_state property set to SCHEDULED
• Callbacks do not have their _callback_state property set to COMPLETED in GMS storage. Callbacks in
such a state for more than 3 hours are discarded.
auth object:
Server.
Important
You can use this API to ensure that you do not book more Callbacks than you have
licenses for.
GET /genesys/1/admin/callback/watermarks?service_name={callback-
execution-name}
GET /genesys/1/admin/callback/watermarks
Counts the current set of executed callback instances per queues or for a given queue.
URI Parameters
Name of a callback execution
service. If you set this parameter,
the response will return the
{callback-execution-name} string
watermarks for the specified
service only. If the service name
is not set, the response returns

the total count of executed

callback instances in queues and
the count per service.
You can query watermarks for several
services in a single query. To do so, add
as many service_name values as you
need to your query:
GET /genesys/1/admin/
callback/
watermarks?service_name=service1&service_nam
Responses
HTTP code 200

HTTP message OK
If accepted, a list of target queues and the count of
callbacks that are in execution within ORS or that
do not have their _callback_state property set to
SCHEDULED or COMPLETED) in GMS storage.
{
"total": <total of callbacks in

progress>,
"services": {
<service-1>: <number of callbacks in
progress for service-1 >,
...
<service-n>: <number of callbacks in
progress for service-n>,
}
}
Name Value

code 50050

Example
Operation
GET http://localhost:8080/genesys/1/admin/callback/watermarks
Result
200 OK
{
"total": 1,
"services": {
"callback-immediate": 0,
"callback-test": 1
}
}
GET http://localhost:8080/genesys/1/admin/callback/watermarks?service_name=callback-immediate
Result
200 OK
{
"total": 0,
"services": {
"callback-immediate": 0
}
}
Check in Queue Position

This query enables your application to query for the position and Estimated Wait Time while the GMS
Service request is in QUEUED status. This query is used to provide additional details in the Callback UI.
POST /genesys/1/service/{callback-service-id}/check-queue-position
BODY Parameters
{callback-service-id} ID of the callback execution
required string service. For example,
445-f4fa53ec-8e93-4836-ba35-f0bd74a025a8.
Important
The GET method is also supported for this feature.

Response
HTTP code 200

HTTP message OK
JSON-formatted information for the given service ID:
• app_version: Callback strategy version.

• wt: The time that the call has waited in queue.
• connid: Interaction ID in the Virtual Queue.
• ewt: The estimated time that customer will wait
for the callback.
• positioninqueue: The callback's current
position in the queue.
• _position: position of the interaction in the
virtual queue (top position = 1).
• _eta: estimated wait time to the agent
availability.
• _total_waiting: total number of requests
waiting in queue.
• priority: The callback priority in the Virtual
Queue.
• agents_logged_in: The number of agents that
have logged in.
• ors_session_id: ORS session ID of the
callback.
• ewt_at_offer: The estimated wait time when
the callback is offered.
• pos_at_offer: The callback's position in the
queue when the callback is offered.
• callback_type: The type of callback.
• time_callback_accepted: The time when the
callback is accepted.
• channel: The callback channel.
• skill_expression: The callback's target or skill
expression.
• ewt_at_first_dial: The estimated wait time
when the first outbound call happened.
• pos_at_first_dial: The callback's position in
the queue when the first outbound call
happened.
• time_at_first_dial: The time when the first
outbound call happened.

• dial_attempt: The number of dials that agent

has attempted.
• is_snoozed: If true, shows that the callback is
snoozed.
• dial_result: The result of callback dial.
• time_customer_connected: The time when the
customer connected.
Errors
Name Value

code 50050
Example
Operation
POST /genesys/1/service/445-f4fa53ec-8e93-4836-ba35-f0bd74a025a8/check-queue-position HTTP/1.1

Connection: close
Content-Length: 0
Response:
200 OK
{
"app_version":"v2.41",
"wt":26,
"connid":"006e02aea54bc008",
"ewt":0,
"positioninqueue":0,
"_position":1,
"_eta":0,
"_total_waiting":1,
"priority":500,

"agents_logged_in":3,
"ors_session_id":"00ACLU5N00CV19601K015B5AES000003",
"ewt_at_offer":0,
"pos_at_offer":0,
"callback_type":"WAIT_FOR_AGENT",
"time_callback_accepted":1508959666,
"channel":"WEB",
"skill_expression":"[email protected]",
"ewt_at_first_dial":"100.0",
"pos_at_first_dial":"1",
"time_at_first_dial":1508959684,
"dial_attempt":1,
"is_snoozed":false,
"dial_result":"PERSON",
"time_customer_connected":1508959690
}
Export Cancelled Callback Records

Added in: 8.5.110
This query exports the callbacks that were cancelled by the Service Management UI only (Bulk
Cancel).
• The data will be exported in CSV format.

• The request will export the records cancelled from the last 30 days to the next 15 days.
• You can export additional fields with the retrieved callback records.
By default, the CSV report includes the following default properties: _desired_time, _service_name,
_customer_number, urs_virtual_queue, _vq_for_outbound_calls, and target.
auth object:
Server.
POST /genesys/1/admin/callback/reportcancelled
BODY Parameters
callback_reason The reason for the cancellation.
required' string For example,
CANCELLED_BY_ADMIN.
exported_properties string List of properties to export for


each selected record. For
example:
["_service_id,_desired_time"]. If
this parameter is empty or
missing, the following properties
will be exported by default:
_desired_time, _service_name,
_customer_number,
urs_virtual_queue,
_vq_for_outbound_calls, and
target.
Response
HTTP code 200

HTTP message OK
CSV-formatted results for exported records:
<property-1>,<property-2>,...,<property-n>
<record-1-property1>,<record-1-property2>,...,<record-1-pro
...
<record-n-property1>,<record-n-
property2>,...,<record-n-propertyn>
Errors
HTTP code 400

HTTP message Callback reason is missing.
HTTP code 204

HTTP message No record found.
Name Value

code 50050

Name Value
Example
Operation
{
"callback_reason": "CANCELLED_BY_ADMIN",
"exported_properties": []
}'
Response:
Access-Control-Allow-Credentials →true
Access-Control-Allow-Origin →chrome-extension://aicmkgpgakddgnaphhhpliifpcfhicfo
Access-Control-Expose-Headers →
Content-Disposition →attachment; filename="report.csv"
_desired_time,_service_name,_customer_number,_target,_vq_for_outbound_calls,_urs_virtual_queue
2017-07-04T22:00:00.000Z,callback-
gms,5115,Billing@Stat_Server.GA,GMS_Callback_VQ_OUT,GMS_Callback_VQ
Operation
HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/
50.0.2661.102 Safari/537.36
Cookie: JSESSIONID=1ff4o2zwehsbx6fzdfwb66jsa
Authentication: Basic=....
{
"callback_reason": "CANCELLED_BY_ADMIN",
"exported_properties": ["_service_id,_desired_time"]
}
Response
desired_time,customer_number,exported_properties1,exported_properties2
2017-05-11T12:22:00+00:00,3329284556,exported_value1,exported_value2
Implement Preview and Disposition Scenarios

If you implement a custom agent desktop and wish to integrate the Preview and Disposition scenarios

to your Callback application, you need to configure Preview and Disposition options in your Callback
service. After you do this, your Custom Agent Application will receive the following UserEvent events
from Orchestration Server:
• CallbackInvitationEvent—The Callback invitation that contains the attached data for the preview.
The invitation includes the list of actions that the agent can perform–accept, reject, or cancel. Your
Agent application displays the actions and the attached data for the preview to the agent, then submits
a Preview Response to your Callback service.
• CallbackDispositionEvent—The Callback disposition event that provides the URL to which you submit
the disposition selected by the agent. Your Agent application then submits a Disposition Response to
your Callback service through this URL.
For a complete description, refer to the Callback Solution Guide.

Genesys Mobile Services API Reference Digital Channels API
Digital Channels API

The Digital Channels API allows Genesys Mobile Engagement to work with Genesys digital channels
such as chat and email. Before you can start using these APIs, you need to configure them by
creating services in your GMS configuration. This information has been moved in the Configuring the
Digital Channels API section of the Deployment Guide.
The following APIs and responses are supported:
• Chat API Version 2

• Chat API Version 2 for CometD
• Email API
• Open Media API
• API Responses
To get the list of options that you can configure for these APIs, refer to the Genesys Mobile
Engagement Configuration Options Guide:
• Chat service options

• Email service options
• Open Media service options

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
HTTP Method URI
POST /genesys/2/chat/{serviceName}
HTTP Header Value
OR
Content-Type
multipart/form-data

customer's nickname
(either nickname or
nickname "JohnDoe" both firstName and Required
lastName should be
supplied)
first name of the
customer (either
firstName "John" nickname or both Required
should be supplied)
last name of the
customer (either
lastName "Doe" nickname or both Required
should be supplied)
subject as entered by
subject "Help with account" Optional
the customer
email address of the
emailAddress "[email protected]" Optional
customer
userData[attachedDataKey1]
value1 the client wants to add Optional
to chat
userData[importantKey2] value2 the client wants to add Optional
to chat

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
Input
firstName=First
lastName=Last
subject=Subject+to
Output
{
"statusCode":0,
"alias":"117",
"userId":"007555677B20000A",
"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
"I need help with
message text message to send Required
account"

HTTP Method URI

any arbitrary type that
messageType "text" Optional
the user wants to set
Including this parameter
enables the return of
the transcription and it
transcriptPosition 8 Optional
sets the position in the
transcript from where it
should be retrieved.
Example
/00048aAPEQJ8000S/send
Input
userId=00755567761A0008
alias=117
transcriptPosition=8 message=hello
Output
{
"messages":[
Last","participantId":1,"type":"Client"},"index":7,
"text":"hello","messageType":null,"
type":"Message","utcTime":1432845541000},
Last","participantId":1,"type":"Client"},"index":8,"text":"hello",
"messageType":null,"
type":"Message","utcTime":1432845548000}],
"chatEnded":false,
"statusCode":0,
"alias":"117",
"userId":"007555677CB4000D"
}
Start Typing
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/startTyping
HTTP Header Value

HTTP Method URI

Example
/00048aAPEQJ8000S/startTyping
Input
userId=0075555D17270020
alias=117
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
userId: "0075555D17270020"
}
Stop Typing
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/stopTyping
HTTP Header Value
Example
/00048aAPEQJ8000S/stopTyping
Input

userId=0075555D17270020
alias=117
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
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, this request can be used 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

HTTP Method URI

0 (no messages)
index position in the transcript Optional (All messages are
1 (all messages)
transcriptPosition starting from which the retrieved if no value is
messages should be retrieved provided, which defaults to 1)
2 (all messages starting from
2nd message)
Applies only to Typing Preview
• If no message is
submitted (absent
from JSON input), no
TypingStarted
For use with Typing Preview at request is submitted
the agent chat window. Text
that the user has entered so
to the chat server
far in the chat box at the time
this request is being made. • If message is
"Text that user is typing This text will be submitted to submitted (even if it
message
..." the chat server along with is empty/blank but
notification TypingStarted. present in JSON
Property "typing_preview" input) a
must be enabled as described TypingStarted
in Chat Services Options. 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",
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",
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
/00048aAPEQJ8000W/refresh
Input

userId=007555677CB4000D
alias=117
secureKey=3e2a69d421ae2672
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",
"userId":"007555677CB4000D",
"nextPosition":22
}
Disconnect
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/disconnect
HTTP Header Value
Example
/00048aAPEQJ8000S/disconnect
Input
userId=0075555D17270020
alias=117

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
pushUrl "http://url.to.see" URL Required
Example
/00048aAPEQJ8000S/pushUrl
Input
userId=0075555D17270020
alias=117
pushUrl=url.to.see
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
userId: "00755567761A0008"
}

Update Nickname
HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/updateNickname
HTTP Header Value
nickname John Doe 2 new nickname Required
Example
/00048aAPEQJ8000S/updateNickname
Input
userId=00755567761A0008
alias=117
nickname=newName
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
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

HTTP Method URI

message "message ..." message, if any Optional
Example
/00048aAPEQJ8000S/customNotice
Input
userId=00755567761A0008
alias=117
message=custom+message
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
userId: "00755567761A0008"
}
Update User Data

HTTP Method URI
POST /genesys/2/chat/{serviceName}/{chatId}/updateData
HTTP Header Value
Example
/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
Output
{
messages: null
chatEnded: false
statusCode: 0
alias: "117"
userId: "00755567761A0008"
}
Read Receipt
HTTP Method URI

POST /genesys/2/chat/{serviceName}/{chatId}/readReceipt
HTTP Header Value

that the client app
acknowledges having
read.
transcriptPosition "5" Required
"messages" array.

Example
http://localhost:8080/genesys/2/chat/customer-support/00048aAPEQJ8000S/readReceipt
Input
userId=007553863DC30029
alias=117
Output
{
"messages": null,
"chatEnded": false,
"statusCode": 0,
"alias": "117",
"userId": "00F05702F26B0006"
}

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
HTTP Method URI

POST /genesys/2/chat/{serviceName}/{chatId}/file/limits
HTTP Header Value

HTTP Method URI
Content-Type
Required/
Optional
Output Parameters
download-attempts
upload-max-files
during this session
file
upload-need-agent
upload-file-types
session
session
session
delete-file
Example
/00048aAPEQJ8000U/file/limits
Input
userId=007553863DC30029
alias=117
Output

{
"messages": null,
"chatEnded": false,
"statusCode": 0,
"alias": "240",
"userId": "00F05702F26B0006",
"userData": {
"upload-file-types": "bmp:csv:doc:docx:exe:gif:htm:jpg:pdf:png:ppt:
pptx:tif:txt:xls:xlsx:zip"
}
}
Upload File
HTTP Method URI

POST /genesys/2/chat/{serviceName}/{chatId}/file
HTTP Header Value
Required/
Optional
file to be uploaded
into the session
This value can be
used by the agent
userData[file-
description]
Collection of key-
value pairs that
provides file
metadata

Example
/00048aAPEQJ8000U/file
Input
userId=007553863DC30029
alias=117
Output
{
"messages": [],
"chatEnded": false,
"statusCode": 0,
"alias": "240",
"userId": "00F057DB0FC30001",
"chatId": "0001KaBWNVUV000K",
"userData": {
"file-id": "00F057DB0FF10005"
},
"nextPosition": 6
}
Download File
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
Required/
Optional
File to be
the session

Example
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD
Input
userId=007553863DC30029
alias=117
Output
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
URI HTTP Method

/genesys/2/
POST
chat/{serviceName}/{chatId}/file/{fileId}/delete
HTTP Header Value
8.5.110.07)

Required/
Optional
The file to be
the session
Example
/00048aAPEQJ8000U/file/00048aAPEQJ8ABCD/delete
Input
userId=007553863DC30029
alias=117
Output
{
"messages": [],
"chatEnded": false,
"statusCode": 0,
"alias": "240",
"secureKey": "ad437d2338d09d09",
"userId": "00F057DB125E000A",
"chatId": "0001KaBWNVUV0011",
"nextPosition": 7
}

Chat API Version 2 via CometD

Client applications can use the GMS Chat API Version 2 to initiate an anonymous and unauthenticated
chat session from a client application. GMS then routes the interaction to an agent. The Agent
application, usually a desktop, uses another distinct Genesys API to participate in the chat session.
See also the Chat Version 2 CometD Sample page. Link to video
Versions Changes
Genesys Mobile Enterprise supports the Digital
Channels Chat API V2 over CometD channel. Most
8.5.109 of the time, requests, responses, parameter
names, and error codes are identical between the
REST and CometD APIs.
GMS supports CometD WebSocket Transport. To
8.5.110 enable Secure WebSocket, deploy GMS with an SSL
certificate.
• Digital Channels Chat API V2 over CometD now

supports File Transfer operations.
• Chat API with CometD usability is enhanced and
8.5.112 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.
• 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
8.5.114 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.
Chat V2 API over CometD now supports Read receipt.

8.5.201

Versions Changes
The push_notification_to_active_client option was introduced to

stop sending mobile and HTTP push notifications in chat
sessions when the CometD connection is established. If you
8.5.219 configure this option to true, mobile and HTTP push
notifications for new events in chat sessions are only sent when
there is no active CometD connection.
Prerequisites for the CometD API

Server Minimum version Configuration details
• 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.
GMS 8.5.109.05+
• 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.
• All the connected Chat Server

instances need to be
deployed in N+1
configuration with session
restoration.
Chat Server 8.5.108+
• 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 the 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 respond and confirm the requested
operations.
CometD in GMS supports:
• HTTP JSON Long Polling

• JSONP with Callback
• Web Socket
CometD in GMS supports WebSockets unless there are some other limitations, such as a Load
Balancer. In this scenario, long polls need to end up on the same GMS Node and require that you
enable sticky sessions.
To implement your client, use a CometD library such as CometD Javascript or CometD-Faye.
CometD selects the best available transport. When implementing your application, you do not need
to take into account the transport, as it doesn't modify GMS API queries and their order.
Important
Use a standard CometD client library to implement your client application. Chat V2
over CometD is tested and intended to be used only with CometD libraries.

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 chat service named customer-support, the associated
chat channel is /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();
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 and requestNotifications operations succeed, GMS starts sending unsolicited
notifications through CometD connection about the chat session activity, for example, when an agent
connects or leaves chat session, sends a message, and so on.
• Unsolicited notifications have exactly one event.

• Notifications sent as a response to a request may have one or no events, except for notifications sent in
response to the requestChat and requestNotifications requests which may have 0, 1, or more
events.
• Your client application should read the secureKey parameter from each received notification response,
and reuse it with each subsequent request message as its value can change, for example, when the
chat session is moved to another Chat Server instance.
• Each chat event has an index matching the event order. Some gaps are possible because GMS does not
deliver all session events to client applications.
Important
You cannot have multiple requestChat requests in one CometD instance. A separate
CometD connection must be created for each new chat session.
See Digital Channels Chat V2 Response Format for additional details about the notification structure.
Here is a notification example:
[
{
"data": {
"messages": [
{
"from": {
"nickname": "a1001",
"participantId": 3,
"type": "Agent"
},
"index": 8,
"text": "hello",
"type": "Message",
"utcTime": 1590051516000
}
],
"chatEnded": false,
"statusCode": 0,
"alias": "0",
"secureKey": "zpcRUAk",
"userId": "deprecated",
"chatId": "deprecated",
"nextPosition": 9,
"monitored": false,
"channel": "/service/chatV2/customer-support"
}
}
]
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 newly 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.
Important
Starting with release 8.5.112, the request parameters such as alias, userId, and
chatId are deprecated.
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

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:

"userData": {
"key1": "value1",
"key2": "value2"
},
"auth": {
"encoded": "dXNlcjE6cGFzczE="
}
}
cometd.publish( channel, requestChatData);
(Optional) Enable Push Notifications for Mobile

CometD supports the following Push Notifications for Mobile:
• Firebase Cloud Messaging (FCM)

• Apple Push Notifications or iOS
• Custom HTTP Notifications
If push notifications are enabled, GMS sends these notifications independently from the CometD
operations and status. The receiver, i.e. mobile application, needs to implement the appropriate logic
for processing the push notifications – based on the current state of the mobile application.
Provide Push Notification Parameters in User Data
When your client application submits requestChat and requestNotifications queries, the request
must include the push_notification_* parameters 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.

Apple Push Notifications
Warning
The Apple Push Notification service (APNs) will no longer support the legacy binary
protocol as of March 31, 2021. Read more.
This means that the APN service will no longer be accessible for the legacy binary protocol. Genesys
Mobiles Services will stop supporting the legacy binary protocol, which is the default protocol for Apple Push
notifications. For further details, read End of Genesys Support for Apple Push Notification service (APNs) –
Legacy binary protocol.
Genesys recommends that you migrate to a supported notification type such as:
• Firebase Cloud Notification

• Custom HTTP Notification
Refer to the Apple Notification documentation to configure your Apple Push Notification Service
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 options that you
configured in the push section of the GMS configuration.
• As stated above, default notifications are submitted in English only. To support additional languages,
you must provision the apple.title and apple.alertMessage.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.
Firebase Cloud Messaging (FCM)
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.

Firebase Push Notification Limitations
• Only one session per client is supported. If the same user tries to login to 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 the 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.
Push Notification Events

You can receive the following notifications with CometD.
Event Name Title default value Body default value Comments

"Chat participants
ParticipantJoined "%s joined chat"
changed"
ParticipantLeft "Chat participants changed" "%s left chat"
The message sent by the

Message "%s sent new message"
participant.
URL pushed by the

PushUrl "%s suggests Web page"
participant. %s is substituted with
the party name
"%s suggests to download

FileUploaded "Open app for more info"
file"
"Please use app if you want to

IdleAlert "Chat will close soon"
continue"
"Your chat session was ended

IdleClose "Chat is over"
due to inactivity"
Important
The FileDeleted, CustomNotice, and Notice events are not pushed even if they are
available in the chat transcript.

CometD API
• requestChat
• requestNotifications
• sendMessage
• readReceipt
• startTyping
• stopTyping
• disconnect
• pushUrl
• updateNickname
• customNotice
• updateData
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
Customer's nickname.
Genesys recommends
that you supply either
nickname string yes nickname or both
firstName and
lastName parameters.
For example: "JohnDoe"
Last name of the
lastName string no
customer. Genesys

Operation requestChat
recommends that you
supply either nickname
or both firstName and
lastName parameters.
For example: "Doe"
The subject as entered
by the customer. For
subject string no
example: "Help with
account"
The email address of
the customer. For
emailAddress string no
example:
"[email protected]"
Any attached data that
the client wants to add
userData JSON-formatted string no 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 or APNS push notifications.
User Data Key Value Required Description

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

Firebase Messaging
fcm client
ios • "ios" for Apple Push
push_notification_type Yes
Notification Service
customhttp
• "customhttp" for
Custom HTTP
Service

Your client app must provide

the exact same data each
issues the
operation.
If true, debug mode for

Firebase Cloud
Messaging or Apple
notification service will
"true" be used. Note if your
push_notification_debug No Apple certificate is
"false" (default)
available for debug
mode only, set this flag
to true; otherwise, the
device will not receive
notifications.
Reserved for now.
Defines the language
for the client
push_notification_languageISO language code No
application. The
language is en_US by
default.
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
push_notification_provider string No
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.

"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 you start
a new chat session or after the CometD channel has been disconnected and reconnected. See Digital
Channels Chat V2 Response Format for all of the notification details.
Operation
Operation requestNotifications
Chat ID that GMS sent in
chatId response to the
Deprecated in Long yes requestChat operation.
8.5.112 For example:
"00048aAPEQJ800U"
User ID that GMS sent in
userId response to the
Deprecated in Long yes requestChat operation.
8.5.112 For example:
"007555677B20000A"
Secure key that GMS
sent in response to the
secureKey Long yes requestChat operation.
For example:
"4ee15d7e1c343c8e"

Operation requestNotifications
alias
Deprecated in string yes Chat host alias.
8.5.112
The transcript event
position from which the
client application would
like to receive the
transcriptPosition integer no 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 or APNS push notifications.

Unique deviceId or
token received from
FCM or APNS. Your client
app must provide the
exact same data each
push_notification_deviceid ID Yes
issues the
operation.
• "fcm" for Google

Firebase Messaging
client
• "ios" for Apple
fcm (APNS) client
• "customhttp" for
ios
push_notification_type Yes Custom HTTP
customhttp Service
Your client app must provide
the exact same data each
issues the
operation.


If true, debug mode for
Firebase Cloud
Messaging or Apple
notification service will
"true" be used. Note if your
push_notification_debug No Apple certificate is
"false" (default)
available for debug
mode only, set this flag
to true, otherwise, the
device will not receive
notifications.
Reserved for now.
Defines the language
for the client
push_notification_languageISO language code No
application. The
language is en_US by
default.
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
push_notification_provider string No
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 requestNotificationData ={
"operation": "requestNotifications",
"alias": "117",
"userId": "007555677B20000A",
"secureKey": "4ee15d7e1c343c8e",
}
cometd.publish( channel, requestNotificationData );
Example of received notification:
{
"messages": [
{
"from": {


"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
Text message to send.
message string yes For example: "I need
help with my account."
chatId The chat ID. For
Deprecated in long yes example:
8.5.112 "00048aAPEQJ800U"
userId The user ID. For
8.5.112 "007555677B20000A"
Secure key. For
secureKey long yes example:
"4ee15d7e1c343c8e"
alias
Chat host alias. For
Deprecated in string yes
example: "117"
8.5.112
Any arbitrary type that
messageType string no the user wants to set.
For example: "text"
Example
Example of request:

var sendData ={
"operation": "sendMessage",
"message": "Hello, ...",

"userId": "007555677B20000A",
"secureKey": "4ee15d7e1c343c8e"
}
cometd.publish( channel, sendData );
Example of notification response:
{
"messages": [
{
"from": {
"participantId": 1,
"type": "Client"
},
"index": 2,
"text": "Hello, ...",
"messageType": "text",
"type": "Message",
"utcTime": 1432845541000
},
],
"chatEnded": false,
"statusCode": 0,
"alias": "117",
"userId": "007555677CB4000D",
"nextPosition": 3
}
Read receipt

Operation readReceipt
Secure key. For
"4ee15d7e1c343c8e"
that the client app
acknowledges having
read.
transcriptPosition integer yes
"messages" array.

Example
Example of request:
var channel = "/service/chatV2/customer-support"

...
var readReceiptData = {
"operation":"readReceipt",
}
cometd.publish( channel, updateNicknameData );
{
"messages":[],
"chatEnded":false,
"statusCode":0,
"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
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
Optional preview typing
message to send. For
message string no
example: "I need help
with my account."
Example
Example of request:


var startTypingData ={
"operation": "startTyping",
"userId": "007555677B20000A",
}
{
"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",
"userId": "007555677CB4000D",
"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
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias Chat host alias. For
string yes
Deprecated in example: "117"

Operation stopTyping
8.5.112
Optional preview typing
message to send. For
message string no
example: "I need help
with my account."
Example
Example of request message:

var sendData ={
"operation": "stopTyping",
"userId": "007555677B20000A",
}
Example of notification response data object:
{
"messages": [
{
"from": {
"participantId": 1,
"type": "Client"
},
"index": 4,
"text": "hello, I have a question",
"type": "TypingStopped",
"utcTime": 1493509618000
}
],
"chatEnded": false,
"statusCode": 0,
"alias": "117",
"userId": "007555677CB4000D",
"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
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
Example

var disconnectData ={
"operation": "disconnect",
"alias": "117",
"userId": "007555677B20000A",
}
cometd.publish( channel, disconnectData );
{
"messages":[],
"chatEnded":true,
"statusCode":0,
"alias":"117",
"nextPosition":1
}
Push URL
Use this operation to push a web page to the agent.
Operation
Operation pushUrl
long yes
Deprecated in example:

Operation pushUrl
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
URL to push to the
pushUrl string yes agent. For example:
"http://www.genesys.com"
Example
Example of request.

var pushUrlData ={
"operation": "pushUrl",
"pushUrl": "http://www.genesys.com",
"userId": "007555677B20000A",
}
cometd.publish( channel, pushUrlData );
{
"messages": [
{
"from": {
"participantId": 1,
"type": "Client"
},
"index": 2,
"text": "http://www.google.com",
"type": "PushUrl",
"utcTime": 1493250733000
}
],
"chatEnded": false,
"statusCode": 0,
"alias": "117",
"userId": "007555677CB4000D",
"nextPosition": 3
}

Update Nickname
Use this operation to update the customer's nickname.
Operation
Operation updateNickname
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
New nickname. For
nickname string yes
example: "John Doe 2"
Example
Example of request:

...
var updateNicknameData = {
"operation":"updateNickname",
"nickname" : "MyNewNickname",
"userId":"007555677B20000A",
"secureKey":"4ee15d7e1c343c8e"
}
cometd.publish( channel, updateNicknameData );
{
"messages":[{
"from":{"nickname":"MyNewNickname","participantId":1,"type":"Client"},
"index":8,
"text":"MyNewNickname",
"type":"NicknameUpdated",
"utcTime":1493936549000
}],
"chatEnded":false,
"statusCode":0,
"alias":"117",
"userId":"007555677CB4000D",
"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
8.5.112 "00048aAPEQJ800U"
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
message string no Optional message.
Example

...
var customNoticeData = {
"operation":"customNotice",
"message" : "ORDER UPDATE",
"userId":"007555677B20000A",
"secureKey":"4ee15d7e1c343c8e"
}
cometd.publish( channel, customNoticeData );
{
"messages": [
{
"from": {
"participantId": 1,
"type": "Client"
},
"index": 8,
"text": "ORDER UPDATE",
"type": "CustomNotice",

"utcTime": 1493510733000
}
],
"chatEnded": false,
"statusCode": 0,
"alias": "117",
"userId": "007555677CB4000D",
"nextPosition": 9
}
Update User Data

Use this operation to modify or add attached data to the chat session.
Operation
Operation updateData
8.5.112 "007555677B20000A"
Secure key. For
"4ee15d7e1c343c8e"
alias
example: "117"
8.5.112
Any attached data that
the client wants to add
userData JSON-formatted string no to the chat session. For
example: {
"key":"value", ... }
Example

...
var updateUDData = {
"operation":"updateData",
"userId":"007555677B20000A",
"userData" : { "key3" : "value3", "key4" : "value4" }
}
cometd.publish( channel, updateUDData );
{
"messages":[],

"chatEnded":false,
"statusCode":0,
"alias":"117",
"userId":"007555677CB4000D",
"nextPosition" : 9
}

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:
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
HTTP Header Value
Content-Type
• application/x-www-form-urlencoded
Input Parameters

operation "fileGetLimits" user ID Required


Output Parameters
download-attempts
upload-max-files
during this session
file
upload-need-agent
upload-file-types
session
session
session
delete-file
Example
http://localhost:8080/genesys/2/chat-ntf
operation=fileGetLimits
Output
{
"messages": [
{
"from": {
"nickname": "JohnS",
"participantId": 1,
"type": "Client"
},
"text": "file-client-cfg-get",
"type": "Notice",
"utcTime": 1497840553000,
"userData": {

"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
HTTP Header Value

Input parameters
Required/
Optional
operation fileUpload secure key Required Form
file to be uploaded
into the session
This value can be
used by the agent
userData[file-
description]
Collection of key-
value pairs that
provides file
metadata
Example
operation=fileUpload

Output
{
"chatEnded": false,
"statusCode": 0,
"userData": {
"file-id": "00F057DB0FF10005"
}
}
Download File
response for Refresh Chat request) indicating that a file was upload.
HTTP Header Value
Content-Type
Required/
Optional
operation fileDownload Required Form
File to be
the session
Example
operation=fileDownload
fileId=00048aAPEQJ8ABCD
Output

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
HTTP Header Value
Content-Type
Required/
Optional
operation "fileDelete" user ID Required Form
The file to be
fileId "00048aAPEQJ8ABCD" Required URL
deleted.
Example
POST /genesys/2/chat-ntf
operation=fileDelete
fileId=007553863DC30029
Output
{
"chatEnded": false,
"statusCode": 0,
"secureKey": "ad437d2338d09d09"
}

Configure your Load-Balancer/Proxy Server for CometD

This section provides some load-balancer/proxy configuration examples that show how to make a
load-balancer proxy work with GMS WebSockets.
Nginx Configuration Sample

To configure NGINX, edit the NGINX configuration file available in the <NGINX INSTALLATION
DIR>/conf directory and add the below configuration.
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
upstream nginixloadbalancer {
server <your_domain_name>:<your_port>;
}
server {
listen 80;
server_name localhost;
location / {
proxy_pass http://nginixloadbalancer/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
}
}
}
Important
Make sure to replace the <your_domain_name>:<your_port> text placeholder with
the relevant domain and port. Use, for example, gms.network.local:8080.
Apache Configuration Sample

If your application uses Apache, edit the httpd.conf file (or alternate file).
1. Uncomment the following modules in the httpd.conf file.
LoadModule proxy_module modules/mod_proxy.so

LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
LoadModule rewrite_module modules/mod_rewrite.so
2. Add the below configuration at the end of the httpd.conf file.
<VirtualHost *:80> ProxyRequests on RequestHeader set X-Forwarded-Proto "http"

ProxyPass / http://{your domain name Eg: gms.network.local:8080}/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]

RewriteCond %{HTTP:Connection} upgrade [NC]

RewriteRule ^/?(.*) "ws://<your_domain_name>:<your_port>/$1" [P,L]
</VirtualHost>
Important
HA Proxy Configuration Sample

Edit the etc/haproxy/haproxy.cfg file and add some special docker directives:
global
maxconn 2000
pidfile /var/run/haproxy.pid
log 127.0.0.1 local0
log 127.0.0.1 local1 notice # echo "" | nc -U /var/run/haproxy.sock
stats socket /usr/local/sbin/haproxy.sock mode 777resolvers dockerdns
nameserver dockerowned 127.0.0.11:53
timeout retry 1s
resolve_retries 10
hold valid 1sdefaults
mode http
log global
option httplog
option http-server-close
option dontlognull
option redispatch
option contstats
retries 3
backlog 10000
timeout client 25s
timeout connect 5s
timeout server 25s
# timeout tunnel available in ALOHA 5.5 or HAProxy 1.5-dev10 and higher
timeout tunnel 3600s
timeout http-keep-alive 1s
timeout http-request 15s
timeout queue 30s
timeout tarpit 60s
default-server inter 3s rise 2 fall 3
option forwardforfrontend main
bind :80
maxconn 10000
default_backend bk_gms backend bk_gms
server server1 <your_domain_name>:<your_port> cookie server1 resolvers dockerdns
Important

Email API Version 2

• See Configuring Digital Channels for email configuration details

• See Email options reference for the list of options available for your email service.
HTTP Method URI

POST /genesys/2/email/{serviceName}
HTTP Header Value
8.5.110.07)
Required/
Parameter Name Sample Value Description Comments
Optional
first name of the
firstName "John" Required
customer
last name of the
lastName "Doe" Required
customer
email address of
fromAddress "[email protected]" Required
the customer
"Help with
subject email subject Required
account"
"I need help with email body as

text Required
my account" plain text
This value takes
priority over any
the address to
configured
mailbox "[email protected]"
which the email is Optional
"mailbox" in the
to be delivered
WebAPI application
on Config Server
User data — can
userData key1=value1 be submitted Optional
multiple times
User data — can
userData key2=value2 be submitted Optional
multiple times
files to be
files attached to the Optional
email

Required/
Parameter Name Sample Value Description Comments
Optional
Important
Use the multipart/
form-data Content-
Type if you need to
attach files. With
the application/
x-www-form-
urlencoded
Content-Type, this
parameter is
ignored.
Configuration
Constraints Default Value Comments
Parameter
Options / email /
Max no. of files 10
max_files
Max size of the content 10485760 (for 10MB), or Options / email /
in bytes 26214400 (for 25MB). max_size
If the parameter
"file_types" is
Options / email /
File Types pdf,doc,txt,jpg,png,gif,bmp,zip configured, it
file_types
completely overrides
the default value.
Configuration Parameter Comments

The address to which the email is to be delivered. If
no value is set in the incoming request and if this
value is set on Config Server then the Config
Options / email / mailbox Server value will be set to the mailbox value from
the request to Email Server. If neither of these
values is set, then Email Server uses its default
value.
Tenant name which has been assigned to email
Options / email / tenant
servers
Request
Content-Type: multipart/form-data;
boundary="WebKitFormBoundaryE19zNvXGzXaLvS5C"
----WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="firstName"
Name
Content-Disposition: form-data; name="lastName"
LastName
Content-Disposition: form-data; name="fromAddress"
[email protected]

Content-Disposition: form-data; name="subject"
Hi hello
Content-Disposition: form-data; name="text"
This is the text

Response
HTTP 200 - success
{
"statusCode": 0,
"interactionId":"0000KaA0C8XH003X"
}
HTTP 200 - failure (server down, network failure, etc. Try again)
{
"statusCode": 1
}

Open Media API

GMS supports OpenMedia API starting with 8.5.110. This API enables you to manage an Open Media
interaction: you can create, retrieve, update, or stop an Open Media interaction by submitting one of
the REST queries detailed below.
• See the API Responses page for further details about the returned status code.
• See Configuring Digital Channels for open media configuration details
• See Open Media Service Options for the list of options available for your open media service(s).
Create an Open Media Interaction

Creates an Open Media interaction. In your service configuration, you can define the default
Interaction Type, Subtype, and Media Type to assign to created interactions. You can overwrite these
defaults in your REST queries if you enable the allow_overwrite option in your configuration. See
Open Media Service Options for further details.
Operation
POST /genesys/2/openmedia/{serviceName}
HTTP Header Value
Parameter Name Type Mandatory Description
URI Parameters
Service to use to create
serviceName string Yes the Open Media
interaction.
Body Parameters
External ID to link to the
new interaction; for
example: "xy932". This
externalId string No ID is passed to
Interaction Server in the
UserData with the key
"ExternalId".
Interaction Type to
assign to the new
interaction, for example
interactionType string No
Inbound. The
Interaction Type must
match one of the values

listed in the Business
Attributes
>Interaction Type
section of your
configuration.
By default, the Interaction
Type used to create the
interaction is defined in the
interaction_type option of
your Open Media service
configuration. The system
considers the
interactionType parameter
only if the allow_overwrite
option is set to true in your
service configuration. See the
options section for more
information.
Interaction Subtype to
assign to the new
interaction, for example
InboundNew. The
Interaction Subtype
must match one of the
values listed in the
Business Attributes
>Interaction Subtype
section of your
configuration.
interactionSubType string No
By default, the Interaction
Subtype used to create the
interaction is defined in the
interaction_subtype option
of your Open Media service
configuration. The system
considers the
interactionSubtype
parameter only if the
allow_overwrite option is set
to true in your service
configuration. See the options
section for more information.
Media Type to assign to

the new interaction, for
example workitem. The
Media Type must match
one of the values listed
in the Business
Attributes > Media
mediaType string No Type section of your
configuration.
By default, the Media Type
used to create the interaction
is defined in the media_type
option of your Open Media
service configuration. The
system considers the

mediaType parameter only if

the allow_overwrite option
is set to true in your service
configuration. See the options
section for more information.
User data to attach to

the interaction. You can
userData[<key-name>] string No submit multiple user
data. For example:
userData[OrderNumber]=uABC1234567
Examples
The following request includes the following encoded parameters:
externalId=xy932&userData[OrderNumber]=ABC123456789&userData[TestKey2]=Test
value&userData[KeyToDelete]=value to delete
POST /genesys/2/openmedia/customer-support
HTTP/1.1
Host: localhost:8080
externalId=xy932&userData%5BOrderNumber%5D=ABC123456789&userData%5BTestKey2%5D=Test+value&userData%5BKeyToDelete
Response
HTTP 200 - success

{
"statusCode": 0,
"interactionId":"01QG0Q2S5S50G000"
}
HTTP 200 - failure (server down, network failure, etc. Try again)
{
"statusCode": 1
}
Get an Open Media Interaction

Retrieves an Open Media Interaction by its interactionId (default) or by its externalId.
Operation
POST /genesys/2/openmedia/{serviceName}/{id}/get
HTTP Header Value

POST /genesys/2/openmedia/{serviceName}/{id}/get
URI Parameters
Service to use to create
interaction.
ID to search. By default,
the interactionId is
id string Yes
used for search. For
example: "xy932".
Body Parameters
true to search by
externalId. By default, if
you omit this option's
searchByExternalId true, false No
value, this option is
false and an interaction
ID is used for search.
Examples
Request
POST /genesys/2/openmedia/customer-support/01QG0Q2S5S50G000/get HTTP/1.1

Response
HTTP 200 - success

{
"statusCode": 0,
"interactionProperties": {
"interactionType": "Inbound",
"interactionId": "01QG0Q2S5S50G000",
"interactionReceivedAt": "2017-05-31T04:43:52Z",
"interactionIsHeld": false,
"interactionSubmittedBy": "GMS-DC-API:gms1:1",
"interactionMediatype": "promotion",
"interactionTenantId": 1,
"interactionQueue": "ATS Inbound Queue",
"interactionSubmitSeq": "1049036",
"interactionMovedToQueueAt": "2017-05-31T04:43:52Z",
"interactionState": "Queued",
"interactionSubmittedAt": "2017-05-31T04:43:52Z",
"interactionPlacedInQueueAt": "2017-05-31T04:51:39Z",
"interactionUserData": [
{
"key": "KeyToDelete",
"type": "str",
"value": "value to delete"
},
{
"key": "OrderNumber",
"type": "str",
"value": "ABC123456789"

},
{
"key": "TestKey2",
"type": "str",
"value": "Test value"
},
...
],
"interactionSubtype": "InboundNew",
"interactionIsLocked": false,
"interactionIsOnline": false,
"interactionPlaceInQueueSeq": "1050198"
}
}
Response
HTTP 200 - Failure

{
"statusCode": 2,
"errors": [
{
"code": 248,
"advice": "Specified interaction Id[01QG0Q2S5S50G000] was not found"
}
]
}
Update an Open Media Interaction

Enables you to update values and/or delete key-value pairs. You need to provide at least one key to
update or delete.
Operation
POST /genesys/2/openmedia/{serviceName}/{id}/update
HTTP Header Value
URI Parameters
Service that manages
interaction.
ID of the updated
interaction. By default,
id string Yes the interactionId is
used. For example:
"xy932".
Body Parameters
Adds or modifies the
change[<key-1>] string No
value for the given user

POST /genesys/2/openmedia/{serviceName}/{id}/update
data key. For example:
change[OrderNumber]=uABC123456789
You must provide at least one

key to change or delete.
Adds or modifies the

value for the given user
data key. For example:
change[<key-n>] string No change[TestKey]=myValue
You must provide at least one

key to change or delete.
Key of the user data to

delete. You do not need
to provide a value; You
delete[<key-1>] empty No
can leave it empty. If
you provide a value, it
will be ignored.
Key of the user data to
delete. You do not need
to provide a value; You
delete[<key-n>] empty No
can leave it empty. If
you provide a value, it
will be ignored.
Examples
In this example, the requested update to be encoded is:
change[OrderNumber]=uABC123456789&change[TestKey2]=uTest+value&delete[KeyToDelete]=
POST genesys/2/openmedia/test/0000KaA0C8XH003Y/stop
POST /genesys/2/openmedia/customer-support/01QG0Q2S5S50G000/update HTTP/1.1
change%5BOrderNumber%5D=uABC123456789&change%5BTestKey2%5D=uTest+value&delete%5BKeyToDelete%5D=
Response
HTTP 200 - success

{
"statusCode": 0
}
HTTP 200 - failure
{
"statusCode": 2,
"errors": [
{
"code": 248,
"advice": "Interaction with specified id[01QG0Q2S5S50G000] was not found"
}
]

Stop an Open Media Interaction
Operation
POST /genesys/2/openmedia/{serviceName}/{id}/stop
HTTP Header Value
URI Parameters
Service that created the
serviceName string Yes
Open Media interaction.
ID of the interaction to
stop. By default, the
id string Yes
interactionId is used.
For example: "xy932".
Body Parameters
Reason for stopping the
interaction. This reason
will be attached to the
reasonSystemName string No
event sent by
Interaction Server; for
example: "Cancel"
Reason description for
stopping the interaction.
This description will be
reasonDescription string no attached to the event
sent by Interaction
Server; for example:
"Not needed"
Example
The following operation stops the interaction with the following encoded reason and description:
reason=RSN-123&description=ORDER+CANCELLED
POST genesys/2/openmedia/test/0000KaA0C8XH003Y/stop
POST /genesys/2/openmedia/customer-support/01QG0Q2S5S50G000/stop HTTP/1.1
reason%3DRSN-123%26description%3DORDER%2BCANCELLED
Response
HTTP 200 - success

{
"statusCode": 0
}
HTTP 200 - failure
{
"statusCode": 2,
"errors": [
{
"code": 248,
"advice": "Interaction with specified id[01QG0Q2S5S50G0001] was not found"
}
]
}

API Responses
All Digital Channels API responses contain:
• An HTTP status code

• Either an API statusCode or one or more API error codes.
The following sections provide more details about these responses.
HTTP 200
Name Description
200 OK
In all responses with an HTTP status code of 200:
• An API statusCode value of 0 indicates that the

operation was successful and all fields in the
response have valid values.
• An API statusCode value of 1 indicates that
there was an error and the client can keep
trying until it receives a statusCode of 0 or
until it decides to give up.
Note: When you receive this response, you
statusCode cannot assume that the values of any
required other fields are valid.
• An API statusCode value of 2 indicates that:

• There was an error
• Repeating requests will not be successful
• The chat may have ended—read the value of
the chatEnded flag.
Note: When you receive this response,
you cannot assume that the values of
any other fields are valid.
Digital Channels Chat V2 Response Format

The positive response (HTTP status 200) from the GMS node is identical for any Chat V2 API request.
It includes some fields that you can use in subsequent requests such as alias, userId, chatId,

securekey, nextPosition, as well as chat transcripts available in the messages array. The Chat
transcript may be empty or include one or more events.
200 OK
• 0 indicates that the operation

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

error.
Identifies the Chat Server

instance that served this request.
When provided, use it in
alias string
subsequent API requests. This
alias may change several times
within the same session.
boolean If true, indicates that the current
chatEnded false, true chat session has ended. If false,
the chat session is still ongoing.
Identifies current Chat Session id.
chatId string subsequent API requests. This
value doesn't change during the
chat session.
Contains full or partial chat
messages array of Chat transcripts transcript. See the Chat
Transcript section below.
Indicates which event index to
use to request a transcript in the
nextPosition integer
next operation (used in Refresh
Chat, and other requests)
Secured key for this session; use
this key (valid only for this
secureKey string
session) in each request. Make
sure to protect this key.
userId string Identifies this chat party (self).


subsequent API requests.
Party Resource
The from field of the chat event describes the party who generated this event. This resource matches
the following format:
Party Resource
The preferable calling [nick]
nickname string
name of the chat participant.
Identifier of this chat party. This
identifier differs from the userId.
The same party can join and
integer leave several times the chat
participantId 1,2... session. Each time that the party
joins, it is assigned a new
partyId even if it is the same
agent.
Describes the type of
participant.
string
"Agent" "External" means that the
event was not generated by
type "Client" a customer or an agent, but
rather by an ESP request,
"External"
received for example from
the routing strategy.
Chat Transcript
The Chat Transcript consists of a list of chat events. Each chat event has an index assigned to the
event when it happens that defines the order of events. You can request full or partial transcripts
using the Chat Refresh operation. Note that you do not receive all of the Chat events, so the index
difference between two events in the transcript can exceed one. Each chat event is generated by
some chat party.
Important
Semantics of event text and userData in the event may vary, depending on the event
type. For further details, see the query description in your Digital Channel API (Chat,
Email, or Open Media).

Chat Transcript Resource

Field Type Description
Describes the chat party who
from Party object
generated this event.
Identifies serial number of this
index integer event within chat session, starts
with 1 for the first event.
If available, contains the text
text string
associated with this event.
ParticipantJoined
ParticipantLeft
Message
TypingStarted
TypingStopped
NicknameUpdated
PushUrl
type Identifies the chat event type.
FileUploaded
FileDeleted
CustomNotice
Notice
IdleAlert
IdleClose
utcTime long Indicates the event timestamp.

If available, contains additional
userData map<string,string>
information for this event.
Example
200 OK
{
'alias': '117',
'chatEnded': False,
'chatId': '00001aCY6K8U003T',
'messages': [{'from': {'nickname': 'FirstStep',
'participantId': 1,
'type': 'Client'},
'index': 1,
'type': 'ParticipantJoined',
'utcTime': 1509117363000},
{'from': {'nickname': 'TestName',
'participantId': 2,
'type': 'Agent'},
'index': 2,

'type': 'ParticipantJoined',
'utcTime': 1509117368000},
{'from': {'nickname': 'FirstStep',
'participantId': 1,
'type': 'Client'},
'index': 3,
'text': 'First message',
'type': 'Message',
'utcTime': 1509117368000
}],
'nextPosition': 4,
'secureKey': 'e4071047872b7820630f',
'statusCode': 0,
'userId': '007559F34DB30001'
}
HTTP 400
Validation errors with an HTTP status code of 400 happen when any of the values necessary to
complete an operation is missing. They have two different formats, depending on which release you
are using:
GME version 8.5.103.08 and lower

{
error: "validationError"
fields:
{
nickname: "either nickname or firstName and
lastName should be supplied"
tenantName: "invalid"
}
}
GME version 8.5.103.09 and higher

// array of all validation errors
{ "errors" : [
// missing required parameter _firstName_
{"code":102},
// missing required parameter _lastName_
{"code":103},
// total file size exceeded,configured value of 300kB
{"code":202,"advice":"300000"},
// attempt to upload file of incorrect type
{"code":203,"
advice":"jpg,zip,txt,pdf,exe,bmp,gif,dll,png,doc"}
]}

Web API Validation Error Codes

code description chat email openmedia
Error messages in this range indicate that a required parameter is missing from a
100-199
request.
100 RESERVED
101 tenant is missing.
firstName is
102 x x
missing.
lastName is
103 x x
missing.
subject is
104 x x
missing.
userData is
105 x
missing.
151 alias is missing. x
152 userId is missing. x
secureKey is
153 x
missing.
154 chatId is missing. x
nickname is
161 x
missing.
message is
162 x
missing.
pushUrl is
163 x
missing.
fromAddress is
181 x
missing.
182 text is missing. x
mediaType is
191 x
missing.
interactionType
192 x
is missing.
interactionSubtype
193 x
is missing.
Error messages in this range indicate that one or more of the parameters specified
in a request is outside of the range configured in the Genesys Mobile Engagement
200-299
application options. These errors include an advice field that displays the allowable
range or limit.
200 RESERVED
The total number
201 of uploaded files is x x
too high
The total size of
202 x x
the uploaded files


is too large
The uploaded file
203 has an incorrect x x
filetype
An unexpected
error occurred. The
advice field
includes the
240 x x x
ReferenceID that
helps to identify
the error cause in
the GMS log file.
The specified file is
241 not present in the x
current session.
The interaction
248 with the specified x
ID was not found.
The Media Server
was not able to
249 x
execute the
request.
Error messages in
this range are not
generated by
Genesys Mobile
Engagement but
250-299 are provided x
directly by the
connected Media
Server (for
example, Chat
Server).
250 RESERVED
File Upload is not
possible until an
261 x
agent joins the
session.
File was already
264 x
deleted.
Error messages in this range indicate that a request parameter is malformed or
300-399
invalid (for example, an invalid email address).
300 RESERVED
serviceName URL
parameter is
invalid (that is, not
306 configured in the x x
Genesys Mobile
Engagement
application). The


HTTP status will be
set to 404 - Not
Found instead of
400 - Bad
Request.
emailAddress
364 contains an invalid x
email address.
fromAddress
381 contains an invalid x
email address.
mailbox contains
383 an invalid email x
address.

Genesys Mobile Services API Reference Phone Number Validation API
Phone Number Validation API

This Phone Number Validation API wraps the Google's common Java, C++ and JavaScript library for
the purposes of parsing, formatting, and validating international phone numbers. GMS 8.5.108.02.
integrates Version 7.2.8 and uses the Apache License Version 2.0.
The API supports the following features:
• Parsing the phone number for a syntactic check (number, plus signs, extensions, and so on);
• Splitting the phone number into parts (country code, extensions, and so on);
• Verifying local patterns such as: US=(650) 466-1100, FR=06 04 12 04 05, DE=089 125016040;
• Translating numbers to enable automated systems to use either localized or E164 or international form
(useful to identify unique patterns);
• Providing some hints on advanced information such as timezone, city, carrier;
• Providing information in the case of premium numbers.
You can pass a country code in the parameters of your queries. See below for further details.
Important
Note that if the validation parsing fails, the response will be an Error 400.
API Query
GET /genesys/1/phonenumber?number={number}
Name Type Mandatory Description
URI Parameters
Phone number to
number string yes validate. For example,
0604120405.
Two-letter country code
as defined in ISO 3166.
If you do not specify
country in your query,
US will be used by
country string no default to parse the
phone number. For
example, in the default
configuration, the phone
number 06 04 12 04
05 is invalid unless you

GET /genesys/1/phonenumber?number={number}
set country=FR in your
query.
Language used for
displaying the area
descriptions. For
example, if you validate
the phone number "06
04 12 04 05":
• geocodingLocale=F
geocodingLocale string no R would return
"location":
"France"
• geocodingLocale=D
E would return
"location":
"Frankreich"
Response

HTTP code 200
HTTP message OK
Specified language set
language-specified string yes in the geocodingLocale
request parameter.
number-specified string yes Validated number.
Specified or default
country-default string yes country used for the
response.
Country code part; for
country-code string yes
example, 33 for France.
The region where the
phone number is
region-code string yes
originating from. For
example, "IT" for Italy.
Information used to
detect country code.
• FROM_NUMBER_WITH_
PLUS_SIGN
country-code-source string yes
• FROM_NUMBER_WITH_
IDD
• FROM_NUMBER_WITHO
UT_PLUS_SIGN

• FROM_DEFAULT_COUN
TRY
Extension part. For

example, "32" if the
number is
extension string yes "0604120405#32". Note
that # should be url-
encoded as %23 in the
request.
Short number for
country. For example,
number-national-short string yes
604120405 for a French
mobile number.
Number formatted using
number-national string yes
the national format
number-E164 string yes
the E.164 format.
the original phone
number-original string yes
number format that was
parsed.
number-international string yes
the international format
true if the number looks
is-possible-number string yes valid from considering
the length information.
true if the number
looks valid from
is-valid-number string yes
considering the length
and prefix information.
In case of a valid
number, true if the
is-premium string no
number is a premium
rate number.
In case of an Italian
number, true if the
italian-leading-zero string yes
number has leading
zero.
Type of the number
based on the number
parsing to determine if
the number matches
Fixed-line, Mobile, Toll-
number-type string no
free, Premium Rate,
Shared Cost, VoIP, and
Personal Numbers
(whenever feasible).
The possible types are:

• UNKNOWN
• FIXED_LINE
• MOBILE
• FIXED_LINE_OR_MOBILE
• TOLL_FREE
• PREMIUM_RATE
• SHARED_COST
• VOIP
• PERSONAL_NUMBER
• PAGER
• UAN
• VOICEMAIL
Geographical
location string no information related to a
phone number.
Geographical time
time-zone string no information related to a
phone number.
Carrier information
carrier string no related to a phone
number.
If the number is
impossible or invalid,
is-possible-short-
string no might return information
number
on a possible usage as a
short number.
When number is not
possible short number,
is-valid-short-number string no might return info on
valid usage as short
number.
When the number is
is-possible-number-with- impossible, gives the
string no
reason reason why. For
example: "TOO_SHORT"
Examples
The following example returns a successful validation result for a French mobile number.
GET http://localhost:8010/genesys/1/phonenumber?number=0604120405&country=FR≥ocodingLocale=DE
Result

200 OK
{
"language-specified": "de",
"country-code": "33",
"extension": "",
"number-type": "MOBILE",
"number-national-short": "604120405",
"number-national": "06 04 12 04 05",
"number-E164": "+33604120405",
"number-specified": "0604120405",
"number-original": "06 04 12 04 05",
"is-possible-number": "true",
"italian-leading-zero": "false",
"carrier": "SFR",
"country-code-source": "FROM_DEFAULT_COUNTRY",
"number-international": "+33 6 04 12 04 05",
"country-default": "FR",
"is-valid-number-for-region": "true",
"number-region": "FR",
"location": "Frankreich",
"is-valid-number": "true",
"time-zone": "[Europe/Paris]"
}
The following example returns a successful validation result for a German fixed line number.
GET http://localhost:8010/genesys/1/
phonenumber?number=%2B4989125016040&country=DE≥ocodingLocale=FR
Result
200 OK
{
"language-specified": "fr",
"extension": "",
"number-type": "FIXED_LINE",
"number-national": "089 125016040",
"number-E164": "+4989125016040",
"number-specified": "+4989125016040",
"number-original": "+49 89 125016040",
"country-code-source": "FROM_NUMBER_WITH_PLUS_SIGN",
"number-international": "+49 89 125016040",
"country-default": "DE",
"number-region": "DE",
"location": "Munich",
"time-zone": "[Europe/Berlin]"
}
The following example returns a successful validation result for a US fixed line number.
GET http://localhost:8010/genesys/1/
phonenumber?number=%2B16504661100&country=US≥ocodingLocale=FR
Result

200 OK
{
"language-specified": "fr",
"extension": "",
"number-type": "FIXED_LINE_OR_MOBILE",
"number-national": "(650) 466-1100",
"number-E164": "+16504661100",
"number-specified": "+16504661100",
"number-original": "+1 650-466-1100",
"carrier": "",
"country-code-source": "FROM_NUMBER_WITH_PLUS_SIGN",
"number-international": "+1 650-466-1100",
"country-default": "US",
"number-region": "US",
"location": "California",
"time-zone": "[America/Los_Angeles]"
}
Errors
A 400 Bad request error is generated if the phone number is invalid. For example:
GET http://localhost:8010/genesys/1/phonenumber?number=bad&country=DE≥ocodingLocale=de
Result
400 Bad Request
{
"exception":"com.genesyslab.gsg.GSGException",
"message":"Invalid Phone Number bad for Country DE (parsing impossible)"
}

Genesys Mobile Services API Reference Stat Service API
Stat Service API

This API retrieves statistics from the Genesys Statistics Server (Stat Server) and URS.
Important
You need an Authentication header for this service.

Stat Request APIs
Sequence Diagrams
[+] Show Peek Stat Sequence (Statistic is not already opened)

[+] Show Peek Stat Sequence (Statistic already exists)


[+] Show Peek Stat Sequence (Update Cache)

Accessing the APIs

The Stat Server API exposes two interfaces:
• "genesys/1/internal_statistic" — for internal access with no authentication control.

• "genesys/1/statistic" — for external use, which uses Basic Access Authentication (BA) to authenticate users.
As a standard protocol, the username and password for BA can be passed in the URL, as shown here:
http://username:[email protected]:8080/genesys/1/statistic
This API provides the following queries:
• PeekStat
• URS Stat
Important
See the Extended API to query multiple statistics.
PeekStat Request
This request fetches one statistic value.
Operation
Method POST
URL /genesys/1/statistic

Method POST
Header Parameters
The max-age value used to check if
GMS has to recalculate the statistic.
If the peek statistic time window is
Cache-Control : max-age=XX A number of seconds no greater than max-age, GMS
recalculates the statistic value. If the
value is not present, it returns the
latest value in cache.
Body
The body can be either a MultiPart
form or an x-www-form-urlencoded
form consisting of different items
representing the key/value pairs
associated with the statistic
(objectId, objectType, tenant,
tenantPassword, metric,
objectId, objectType, tenant, metric notificationMode, filter,
(or statisticType), filter, timeProfile, timeRange,
yes
notificationMode, timeProfile, timeRange2).
timeRange, timeRange2
• NotificationMode can be
NoNotification, Reset, or
Immediate.
• filter is the business attribute
value to use to filter the results.
Response
HTTP code 200

HTTP Message OK
HTTP Header Content-Type: application/json;charset=UTF-8
Body A JSON object representing a structure with value

If a problem occurs during operation, the following status codes are returned:
HTTP code HTTP Message HTTP Body

message: {"message":"Notification Mode is
400 Bad Request
unknown","exception":"com.genesyslab.gsg.services.statistic.Stat
401 Unauthorized Access to API refused
message: {"message":"Object type not
403 Forbidden
valid","exception":"com.genesyslab.gsg.services.statistic.StatServ
message: {"message":"Agent 'Kippola' (Tenant
403 Forbidden 'Environment') not
found","exception":"com.genesyslab.gsg.services.statistic.StatSer
message: {"message":"Wrong
403 Forbidden
parameter","exception":null}
message: {"message":"Metric (TotalLoginTime;)
500 Server Error not found on running
StatServer","exception":"com.genesyslab.gsg.services.statistic.St
message: {"message":"Statistic Service bad
500 Server Error parameter for
tenant","exception":"com.genesyslab.gsg.services.statistic.StatSe
Important
You can make this request without using authentication by replacing /genesys/1/statistic with /genesys/1/
internal_statistic.

Example
Request
$ curl -v -u default:password -X POST --data "metric=TotalLoginTime&objectType=Agent&objectId=KSippola&tenant=Environment"

http://localhost:8080/genesys/1/statistic
Response
HTTP/1.1 200 OK
{"value":4963}
URS Stat Request

This API allows you to query URS statistics with GMS.
To use this request, you must add the following configuration information:
• URS version must be 8.1.400.12 or higher.

• In your URS application, allow HTTP requests:
1. Open your URS application in Genesys Administrator or Configuration Manager.
2. In the Server Info tab, create an HTTP listening port.
• In the reporting section of your GMS application, create the _urs_url option and set it to the URL of URS.
You can also create a builtin service to retrieve URS statistics with the urs-stat template. When you create your service, select the "urs-stat" type in
the Admin UI service panel. See the Admin UI Help for further details. Then, to retrieve the statistics, you can make the following request:
GET http://<gms_home>:<gms_port>/genesys/1/service/<urs_service>

Operation
Method GET
URL /genesys/1/statistic/urs/parameters

Header Parameters
The max-age value used to check if
GMS has to recalculate the statistic.
If the peek statistic time window is
Cache-Control : max-age=XX A number of seconds no greater than max-age, GMS
recalculates the statistic value. If the
value is not present, it returns the
latest value in cache.
URL Parameters
For information on these parameters,
either refer to the URS
documentation or send the following
parameters no
HTTP request to URS:
http://URS_host:URS_HTTP_port/urs/
help/
Response
HTTP code 200

HTTP Message OK


message: "Authentication failed: username and/or
401 Unauthorized
password is incorrect"
500 Server error
request","exception":"org.apache.http.HttpException"}
message: {"message":"Call not
500 Server error
found","exception":"org.apache.http.HttpException"}
Note: You can make this request without using authentication by replacing /genesys/1/statistic/urs/ with /genesys/1/internal_statistic/urs/.
Example
Request
$ curl -v -u default:password "http://localhost:8080/genesys/1/statistic/urs/stat/targetstate?tenant=Environment⯑=KSippola.A&json=&ext="
Response
HTTP/1.1 200 OK
{
"dnsall":6,
"voice":1,
"status":4,
"loading":0,
"dns":
[
{
"type":38,
"number":"KSippola",
"switch":"",
"status":4,
"loading":0,
"ready":1,
"media":1,
"loggedin":0
},

{
"type":36,
"switch":"",
"status":2,
"loading":0,
"ready":0,
"media":1,
"loggedin":0
},
{
"type":61,
"switch":"",
"status":4,
"loading":0,
"ready":1,
"media":1,
"loggedin":0
},
{
"type":1,
"number":"7001",
"switch":"SIP_Switch",
"status":4,
"loading":0,
"ready":1,
"media":0,
"loggedin":0
},
{
"type":1,
"number":"7001_IM",
"status":8,
"loading":0,
"ready":0,
"media":0,
"loggedin":0
},
{
"type":38,
"number":"7001_IM",

"status":8,
"loading":0,
"ready":0,
"media":0,
"loggedin":0
}
],
"login":"SIP1",
"place":"SIP_Server_Place1",
"ready":1,
"agent":"KSippola",
"dnsrdy":3
}
Extended Stat Request API

• PeekStat Request: Retrieve configured statistics
• PeekStat Request: Querying Multiple Statistic Values in a Single Request (V1)
• PeekStat Request: Querying Multiple Statistic Values in a Single Request (V3)
• PeekStat Request: Filtering Multiple Statistic Values in a Single Request
PeekStat Request: Retrieve configured statistics

Starting with 8.5.101, you can provision statistics in the stat section of your configuration options instead of passing properties as parameters of the
statistics requests.
For instance, you can define stat1 in your configuration as follows:
[stat.stat1]
_type=builtin
_service=statistic

metric=TotalLoginTime
notificationMode=Immediate
objectId=KSippola
objectType=Agent
tenant=Environment
filter=Bronze
Then, you can retrieve the statistics for stat1 with a simple statistics query:
POST http://localhost:8080/genesys/1/statistic/stat1
Response:
{"value":41889}
Operation
Method POST
URL /genesys/1/statistic/stat_name
Header
The max-age value in seconds of the
statistic. If the peek statistic time
window is greater than max-age,
Cache-Control: max-age Integer no
GMS recalculates the statistic value.
If max-age is not specified, GMS
returns the latest value in the cache.
URL parameters
Name of the statistic defined in the
stat_name String yes
stat section of your configuration.
Body
objectId, objectType, tenant, metric The body can be either a MultiPart
yes
(or statisticType), filter, form or an x-www-form-urlencoded

Method POST
form consisting of different items
representing the key/value pairs
associated with the statistic
(objectId, objectType, tenant,
tenantPassword, metric,
notificationMode, filter,
timeProfile, timeRange,
Immediate.
Response
HTTP code 200

HTTP Message OK
Body A JSON object representing the statistic.
If a problem occurs during operation the following status codes are returned:
HTTP code HTTP message Body

message: {"message":"stat.total-time not
400 Bad request found","exception":"com.genesyslab.gsg.services.context
check GMS options

PeekStat Request: Querying Multiple Statistic Values in a Single Request
Important
Starting with 8.5.216, this query is available in V3, which fixes some issues that happened when some object types were
removed.
This request gets the current values of several peek statistic objects.
Operation
Method POST
URL /genesys/1/statistics
Body
form, an x-www-form-urlencoded
form, or a JSON object consisting of
different items representing the key/
objectId, objectType, tenant, metric value pairs associated with the
(or statisticType), filter, statistic (objectId, objectType,
yes tenant, tenantPassword, metric,
notificationMode, timeProfile,
timeRange, timeRange2 notificationMode, filter,
timeProfile, timeRange,
timeRange2).

Method POST
Immediate.
Response
HTTP code 200

HTTP Message OK
If a problem occurs during an operation the following status codes are returned:
You get an error message instead of one of the expected

values if the requested statistic is incorrect; for example:
message: {"stat1":8940,"stat2":"do not have 5
semicolon delimiters"}
200 OK
This means that, instead of getting a 400 Bad request
response, you are able to retrieve statistics, even if one of
them is incorrect.
message: message: {"message":"Error for

stat1: Agent ‘Kippola’ (Tenant
400 Bad request
‘Environment’) not
found","exception":"com.genesyslab.gsg.services.statist


403 Forbidden
message: {"message":"Metric
(CurrentGrouargetState) not found on
500 Server Error
running
StatServer","exception":"com.genesyslab.gsg.services.st
Important
You can make this request without using authentication by replacing /genesys/1/statistics with /genesys/1/
internal_statistics.
Examples with Multiple Statistics
The following example uses application/x-www-form-urlencoded:
Request
$ curl -v -u default:password -X POST --data

"stat1=TotalLoginTime;Agent;KSippola;Environment;Immediate;&stat2=CurrentGroupTargetState;GroupAgents;Billing;Environment;Immediate;Silver"
http://localhost:8080/genesys/1/statistics
Response
HTTP/1.1 200 OK
{
"stat1":248,
"stat2":
[

{
"agentDbId":102,
"placeDbId":102,
"agentId":"KSippola",
"placeId":"SIP_Server_Place1",
"extensions":
[
{"VOICE_MEDIA_STATUS":4},
{"AGENT_VOICE_MEDIA_STATUS":4},
{"DEVCAP":"AAIAAAAAAAEABXZvaWNlAAAAAAAAAAEAAAABVxTnEgAAAAAAAQAAAAIABXZvaWNlAAAAAAAAAAAAAAAAVxTnEgAEY2hhdAAAAAAAAAD/
AAAAAFcU5xIAAAAA"}
],
"mediaCapacityList":
[
{"mediaType":"chat",
"currentInteractions":0,
"maxInteractions":1,
"currentMargin":1,
"timestamp":1460961964},
{"mediaType":"vmail",
"currentMargin":0,
"timestamp":1460554482},
{"mediaType":"voice",
"currentMargin":1,
"timestamp":1460961964},
{"mediaType":"webcallback",
"currentMargin":1,
"timestamp":1460961964}
],
"dnstatusExList":
[
{"dnId":"7001",
"gswDnTypes":1,
[

"currentMargin":1,
"timestamp":1460987666}
],
"multimedia":0,
"status":4,
"switchId":"SIP_Switch",
"time":1460554482},
{"dnId":"7001_IM",
"gswDnTypes":1,
[
"currentMargin":0,
"timestamp":1460987666},
"currentMargin":0,
"timestamp":1460987666}
],
"multimedia":1,
"status":8,
"time":1460553961}
]
}
]
}
The following example uses JSON:
Request
$ curl -v -u default:password -H "Content-Type: application/json" -X POST --data

'{"stat1":{"objectId":"KSippola","objectType":"Agent","tenant":"Environment","tenantPassword":"","metric":"TotalLoginTime","filter":"","notificationMode":"Imm

Response
HTTP/1.1 200 OK
{
"stat1":3426,
"stat3":
[
{"agentDbId":102,
"placeDbId":102,
"agentId":"KSippola",
"placeId":"SIP_Server_Place1",
"extensions":
[
{"VOICE_MEDIA_STATUS":4},
{"AGENT_VOICE_MEDIA_STATUS":4},
{"DEVCAP":"AAIAAAAAAAEABXZvaWNlAAAAAAAAAAEAAAABVxTzkwAAAAAAAQAAAAIABXZvaWNlAAAAAAAAAAAAAAAAVxTzkwAEY2hhdAAAAAAAAAD/
AAAAAFcU85MAAAAA"}
],
[
"currentMargin":1,
"timestamp":1460961964},
{"mediaType":"vmail",
"currentMargin":0,
"timestamp":1460554482},
"currentMargin":1,
"timestamp":1460961964},
{"mediaType":"webcallback",
"currentMargin":1,

"timestamp":1460961964}
],
"dnstatusExList":
[
{"dnId":"7001",
"gswDnTypes":1,
[
"currentMargin":1,
"timestamp":1460990867}
],
"multimedia":0,
"status":4,
"time":1460554482},
{"dnId":"7001_IM",
"gswDnTypes":1,
[
"currentMargin":0,
"timestamp":1460990867},
"currentMargin":0,
"timestamp":1460990867}
],
"multimedia":1,
"status":8,
"time":1460553961}
]
}
]
}

PeekStat Request: Filtering Multiple Statistic Values in a Single Request
Important
This is a JSON query. This JSON query is available since 8.5.004.05.
Operation
Method POST
Body: A JSON item representing the key/value pairs associated with statistics (objectId, objectType, tenant, tenantPassword, metric, notificationMode, filter).
• filter is the business attribute value to use to filter the results.

• notificationMode can be set to NoNotification, Reset, or Immediate.
Response
HTTP code 200

HTTP Message OK
HTTP Header Age: containing the age (in seconds) of the statistic value.
A JSON array of key/value pairs where key is the key stat (see request) and
Body
value is the statistic value.
If a problem occurs during subscription, the following status codes are returned:


The provided filter is incorrect; for example:
{"message":"Filter name is not
400 Bad Request
Part of the submitted data is incorrect, for

example:
{"message":"Place 'SIP_Server_Place'
403 Forbidden
(Tenant 'Environment') not
If Stat Server is not connected, it returns, for

example,
500 Internal server error {"message":"Statistic Service
unavailable","exception":"com.genesyslab.gsg.services.s
Example with Filter
Query
Input: JSON File
{
"stat1": {
"objectId":"KSippola",
"objectType":"Agent",
"tenant":"Environment",
"tenantPassword":"",
"metric":"TotalLoginTime",
"filter":"Bronze"
},
"stat2": {

"objectId":"9002@SIP_Switch",
"objectType":"Queue",
"metric":"ExpectedWaitTime"
}
}
Response
HTTP/1.1 200 OK
Date: Thu, 19 Jun 2014 09:06:43 GMT
Content-Length: 25
{"stat1":0,"stat2":10000}
PeekStat Request: Querying Multiple Statistic Values in a Single Request (V3)
Added in 8.5.216
This request gets multiple statistic values from several statistics and replaces the former V1 query (see the description above).
In V1, if one statistic object type no longer exists in the system, the query of multiple statistics containing one of these removed object types will fail,
even if other queried object types exist. Using V3, when subscribing to several statistics, the operation will not stop on the first statistic item that
fails, for example, if the given statistic does not exist.
Important
In V3, even if the query is similar to V1, the object response is formatted differently. See below for further details.

Operation
Method POST
Body
form, an x-www-form-urlencoded
form, or a JSON object consisting of
different items representing the key/
value pairs associated with the
statistic (objectId, objectType,
tenant, tenantPassword, metric,
objectId, objectType, tenant, metric notificationMode, filter,
(or statisticType), filter, timeProfile, timeRange,
yes
Immediate.
Response
HTTP code 200

HTTP Message OK
A JSON object representing a structure with a status and a value for each
requested statistic.
Body
{

HTTP code 200
"statId": { "status": "<ok or error >",

"value": <value or error message if status =
error > },
...
}
If a problem occurs during operation the following status codes are returned:

The statistics
Check the status of each stat object. You get an error message
instead of one of the expected values if the requested statistic
is incorrect; for example:
{ "stat2": { "status": "ok", "value": 0 }, "stat1":
{ "status": "error", "value": "Agents Group fakeAG
200 OK
(Tenant Environment) not found" } }
It means that, instead of getting a 400 Bad request response,

you are able to retrieve statistics, even if one of them is
incorrect.

403 Forbidden
message: {"message":"Metric
(CurrentGrouargetState) not found on
500 Server Error
running
StatServer","exception":"com.genesyslab.gsg.services.st

Examples with Multiple Statistics
Request
$ curl -v -u default:password -H "Content-Type: application/json" -X POST --data '{

"stat1": {
"objectId":"fakeAG",
"objectType":"GroupAgents",
"filter":""
},
"stat2": {
"filter":""
}
}' http://localhost:8080/genesys/3/statistics
> Content-Type: application/json
>
< HTTP/1.1 200 OK
{
"stat2": {
"status": "ok",
"value": 0
},
"stat1": {
"status": "error",
"value": "Agents Group 'fakeAG' (Tenant 'Environment') not found"
}
}
EWT APIs

In 8.5.2, the Estimated Waiting Time (EWT) APIs were refactored. These APIs, available to query EWT, use different calculation types to provide the
Estimated Waiting Time. These APIs return either a JSON object presentation that describes the information in the virtual queue or a collection of
such objects (one per every matched virtual queue the call is in). GMS retrieves all of the results from URS.
Important
In your GMS configuration, add a connection to an active URS to enable this service.
To provide Estimated Waiting Time, three methods are available:
• ewt1—urs calculation:
http://<urshost>:<ursport>/urs/call/max/lvq?name=VQ_Name&aqt=urs&tenant=TenantName
URS checks how fast interactions go through the virtual queue and how many interactions are still pending. URS ignores the current agent availability
and does not immediately adjust the EWT if, for example, all of the agents handling the queue suddenly logout.
• ewt2—urs2 calculation:
http://<urshost>:<ursport>/urs/call/max/lvq?name=VQ_Name&aqt=urs2&tenant=TenantName
Similarly to the first method, URS checks how fast interactions go through the virtual queue and how many interactions are pending. Additionally,
URS takes into account the agents who have historically been handling interactions of the Virtual Queue. If all of these agents logout, URS notices
and adjusts the EWT value to a very high number like 10000 for example.
• ewt3—stat calculation:
http://<urshost>:<ursport>/urs/call/max/lvq?name=VQ_Name&aqt=stat&tenant=TenantName
Estimated Waiting Time is returned in seconds.

GET – Query EWT from Stat Server
GET /genesys/2/ewt/ewt1?vq={vq}
Retrieves the Estimated Waiting Time in seconds based on the aqt=urs calculation.
URI Parameters
Alias name of a virtual queue or comma-
separated list of Virtual Queue alias names
string configured in a service . For example, vq=vq1 or
vq path vq=vq1,vq2,vq3
If you omit the vq parameter, the response provides EWT in
seconds for all of the VQs which have a callback interaction.
Retrieves the Estimated Waiting Time in seconds based on the aqt=urs2 calculation.
URI Parameters
configured in a service . For example, vq=vq1 or
vq=vq1,vq2,vq3
string
If you omit the vq parameter, the response provides EWT for
vq *required path all of the configured VQs.
You can also query the EWT of a DN group by adding .GQ to

the name of the VQ group. For example, if the name of the VQ
group is VQG_HR_ALL_en, pass vq=VQG_HR_ALL_en.GQ in your
query.

Retrieves the Estimated Waiting Time in seconds based on the aqt=stat calculation.
URI Parameters
string configured in a service . For example, vq=vq1 or
vq *required path vq=vq1,vq2,vq3
seconds for all of the configured VQs.
POST – Query EWT from Stat Server
POST/genesys/2/ewt/ewt1/
Retrieves the Estimated Waiting Time in seconds based on the aqt=urs calculation.
JSON Body
Can be empty or null

configured in a service. For example:
vq *required String array {

"vq": ["VQ_GMS_Callback1",
"VQ_GMS_Callback2", "VQ_GMS_Callback3"]
}


POST/genesys/2/ewt/ewt2
Retrieves the Estimated Waiting Time in seconds based on the aqt=urs2 calculation.
JSON Body

configured in a service . For example:
{
*required String array "vq": ["VQ_GMS_Callback1",
vq
}

POST/genesys/2/ewt/ewt3
Retrieves the Estimated Waiting Time in seconds based on the aqt=stat calculation.
JSON Body

vq String array

configured in a service. For example:
{
"vq": ["VQ_GMS_Callback1",
}

Responses
200 OK
200 OK
JSON-formatted string of information per virtual queue.
The JSON objects describing information in the virtual queue have the
following properties:
Property Description
UTC timestamp when the call
time
entered in the virtual queue.
Response Body Time in seconds that the call is in
wt the virtual queue (effectively
(JSON content)
CurrentTime-time).
Current number of all calls in the
calls
virtual queue.
Number of waiting calls in the
wcalls
virtual queue.
Position of the call in the virtual
pos
queue.

Property Description
Waiting position of the call in the
wpos
virtual queue.
Calls priority in the virtual queue.
priority
Absent if scaling is used.
Average quitting rate of calls from
aqt the virtual queue. May be skipped if
unknown.
Expected waiting time for the call
ewt
in seconds.
Percentage of calls distributed into
hit the virtual queue. Its value is -1 if
no calls were distributed yet.
Short data information about the
clc source of the reported aqt and/or
ewt.
Name Value

code 50001
phrase NO_EWT_CONTENT
There have been no interactions in VQ VQ_GMS_Callback so the EWT is
message unknown. To make URS report EWT for virtual queue, URS need (at least one
time) to run strategy where this VQ is used
exception com.genesyslab.gsg.services.services.EwtException
properties { "time": <UTC timestamp> }

Name Value

code 50002
phrase NO_TENANT_FOUND
message The tenant name is null or empty, check configuration
exception com.genesyslab.gsg.services.services.ResourceNotFoundException
properties { "time": <UTC timestamp> }
Examples
GET with one provided VQ name:
GET http: //localhost:8080/genesys/2/ewt/ewt1?vq=VQ_GMS_Callback

Result
200 OK
{
"hit": -1,
"ewt": 37.5,
"calls": 1,
"pos": 2,
"aqt": 10000,
"wpos": 2,
"time": 1515617935,
"clc": "CCAA100",
"wt": 0,
"wcalls": 1
}
GET with no provided VQ name:
GET http: //localhost:8080/genesys/2/ewt/ewt2

Result

200 OK
{
"VQ_GMS_Callback1": {
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 20.9,
"hit": -1,
"clc": "AFAA100"
},
"time": 1515648959,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 99.3,
"hit": -1,
"clc": "BvAA100"
},
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 46.2,
"hit": -1,
"clc": "CCAA100"
}
}
GET for a list of VQs; one of them does not exist:

GET http: //localhost:8080/genesys/2/ewt/ewt3?vq=VQ_GMS_Callback1,VQ_GMS_Callback3

Result
200 OK
{
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 20.9,
"hit": -1,
"clc": "AFAA100"
},
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 46.2,
"hit": -1,
"clc": "CCAA100"
}
}
GET http: //localhost:8080/genesys/2/ewt/ewt3?vq=VQ_GMS_Callback1,VQ_GMS_Callback3

Result
200 OK
{
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,

"aqt": 10000,
"ewt": 20.9,
"hit": -1,
"clc": "AFAA100"
},
"VQ_GMS_Callback3": null
}
POST with a list of VQs:
POST http: //localhost:8080/genesys/2/ewt/ewt1

Body: {
"vq": [
"VQ_GMS_Callback", “VQ_GMS_Callback_Out”
]
}
Result
200 OK
{
"VQ_GMS_Callback": {
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 20.9,
"hit": -1,
"clc": "AFAA100"
},
"VQ_GMS_Callback_Out": {
"time": 1515617939,
"wt": 0,
"calls": 1,
"wcalls": 1,
"pos": 2,
"wpos": 2,
"aqt": 10000,
"ewt": 46.2,
"hit": -1,

"clc": "CCAA100"
}
}
GET Operation failed (no EWT info returned from URS):

Result

{
"exception": "com.genesyslab.gsg.services.services.EwtException",
"code": 50001,
"phrase": "NO_EWT_CONTENT",
"message": "There have been no interactions in VQ VQ_GMS_Callback so the EWT is unknown. To make URS report EWT for virtual queue,
URS need (at least one time) to run strategy where this VQ is used.",
"properties": {
"time": "2018-01-10T22:12:56.315Z"
}
}
GET Operation failed (no tenant name was found):

Result

{
"exception": "com.genesyslab.gsg.services.services.ResourceNotFoundException",
"code": 50002,
"phrase": "NO_TENANT_FOUND",
"message": "The tenant name is null or empty, check configuration.",
"properties": {
"time": "2018-01-10T22:12:56.315Z"
}
}
Peek Multiple Statistics - V3 (StatisticController)

This request gets multiple statistic values from several statistics.

With previous version, when one statistic object type no longer exits in the system, the query of multiple statistics containing one of this removed
object type will fail even if other object types exist. With V3, when subscribing to several statistics, the operation would not be stopped on the first
statistics item that fails (for example statistic does not exist).
Table 25. Operation
Discontinued item placeholder request Method POST URL
/genesys/3/statistics
Parameter Type Mandatory Description Header Parameters
Cache-Control: max-age=XX
A number of seconds
no
The max-age value used to check if GMS has to recalculate the statistic. If the peek statistic time window is greater than maxAge, GMS recalculates
the statistic value. If the value is not present, it returns the latest value in cache.
URL Parameters
Body
The body should be JSON consisting of different items representing the key/value pairs associated with the statistic (objectId, objectType, tenant,
tenantPassword, metric, notificationMode, filter).
• NotificationMode can be NoNotification, Reset, or Immediate.

• filter is the business attribute value to use to filter the results.
Table 26. Operation response HTTP code 200 HTTP Message
OK

HTTP Header
Body
A json object representing a structure with values
Table 27. Operation errors HTTP code HTTP Message HTTP Body 200
OK
message: { "stat2": { "status": "ok", "value": 0 }, "stat1": { "status": "error", "value": "Agents Group fakeAG (Tenant Environment) not found" } }. It
means that, instead of getting a 400 Bad request response, you are able to retrieve statistics, even if one of them is incorrect.
401
Unauthorized
Access to API refused
403
Forbidden
message: {"message":"Wrong parameter","exception":null}
500
Server Error
message: { "stat1": { "status": "error", "value": "Metric (CurrentGrouargetState) not found on running StatServer" } }
Example of request:
Operation example

$ curl -v -u default:password -H "Content-Type: application/json" -X POST --data '{

"stat1": {
"objectId":"fakeAG",
"objectType":"GroupAgents",
"filter":""
},
"stat2": {
"filter":""
}
}'
> Content-Type: application/json
>
< HTTP/1.1 200 OK
{
"stat2": {
"status": "ok",
"value": 0
},
"stat1": {
"status": "error",
"value": "Agents Group 'fakeAG' (Tenant 'Environment') not found"
}
}

Configuration
Stat Server Connection

In order to use the Stat Server API, there must be a connection to Stat Server in the GMS Application. You can create the connection in Configuration
Manager on the Connections tab. See Creating and Configuring the GMS Application Cluster Object.
You can add several Stat Servers in the Connection tab; this feature is used in case of different statistic definitions in the Stat Servers. GMS will open
the statistic on the Stat Server to which the statistic belongs to. In the case of the same statistic definition in Stat Servers, GMS will take the first Stat
Server that contains the statistic definition.
ADDP Setting
Open Stat Server in the GMS Connection tab and set the connection protocol to addp. Set the values for the Local Timeout and Remote Timeout, and
then select the Trace mode. See Implementing ADDP for more information.
Important
The ADDP traces are only visible on the Stat Server side.
The following example shows an ADDPtrace in Stat Server logs:
-AP[10]-<-2168 @15:37:30.4540
-Ap[10]->-2168 @15:37:30.4560
High Availability
If Stat Servers (defined in GMS connections) are configured to use High Availability (HA) (Primary/Backup Stat Server), in the case of a lost
connection with the primary Stat Server, the Stat Server API will switch to the backup Stat Server.

Subscribe to Statistic Server Event Notifications

You can receive event notifications sent by the Statistics Server by using the CometD channel. To do so:
1. Register for GMS CometD channel.

2. Subscribe for a list of statistics through the new API: POST /genesys/2/statistics.
Important
This Statistics API currently supports polling mode.
Register for GMS CometD Channel

Create a client that will listen to CometD events sent by GMS, as shown in the following Node JS example:
var faye = require("faye");

var request = require('request');
// subscribe GMS comet
var referenceId;
var client = new faye.Client("http://localhost:8080/genesys/cometd");
client.setHeader("gms_user", "123456");
var subscr = client.subscribe("/_genesys", function (message) {
var stats = message["message"]
var statReferenceId = stats["statReferenceId"]
///...
client.disconnect();
});

Subscribe to Statistics through the Statistics API

Use the API to subscribe to a list of statistics and retrieve for each of them the reference ID of the Stat Server. Then, you will receive CometD event
notifications associated with these reference IDs.
Important
You must subscribe with the same gms_user ID as the one used for the CometD client.
Operation
POST /genesys/2/statistics
Header Parameters
Content-type Yes application/json;charset=UTF-8
The user ID that has been used in
gms_user String (UUID) Yes
CometD at registration time.
Body: The body is a JSON structure that lists the statistics to get notifications for.
For example:
{
"stat1": {
"objectId": "kmilburn",
"objectType": "Agent",
"tenant": "Environment",
"tenantPassword": "",
"metric": "TotalLoginTime",
"filter": ""
},
"stat2": {
"objectId": "KSippola",

POST /genesys/2/statistics
"filter": "Bronze"
}
}
Response
The response contains the reference IDs from the Stat Server subscribed statistics.
HTTP code 200

HTTP Message OK
A JSON array of key/value pairs, where:
Body • The key is the name of the subscribed statistics.

• The value is the reference ID of the Stat Server subscribed statistics.
For example:
200 OK
{"stat1":1958339548,"stat2":1329710246}
Errors
HTTP Code 500

HTTP Message Server Error
Body • {"message":"Could not read JSON: Unexpected character ('\"'

HTTP Code 500
(code 34)): [...]"}.

• {"message":"Error for stat1: Supplied Object type does not
belong to specified Stat Type.",
"exception":"com.genesyslab.gsg.services.statistic.StatServer
EventErrorException"}.
Example
The following node JS sample shows how to subscribe statistics with this API.
var request = require('request');

// send request to subscribe stat using gms_user of comet subscription
request({
url: 'http://localhost:8080/genesys/2/statistics', //URL to hit
headers: {
'Content-Type': 'application/json',
'gms_user': '123456'
},
method: 'POST',
json: true, // output data is JSON
json: { // input data is JSON too
"stat2": {
"objectId": "KSippola",
"filter": ""
}
}
}, function (error, response, body) {
if (error) {
///...
} else {
referenceId = body["stat2"];
///...

}
});
As a result of the subscription, you would receive the following reference IDs:
200 OK
{"stat1":1958339548,"stat2":1329710246}
As a result, CometD Polling responses include these reference IDs too:
[
{"data":
{"id":"8f8dc3a0d00311e5845a0de0f4fa8277",
"message":
{"statValue":"0","statReferenceId":"1958339548"},
"tag":"service.statistic.push.1958339548"},
]
[
{"data":
{"id":"9560da60d00311e5845a0de0f4fa8277",
"message":
{"statValue":"0","statReferenceId":"1329710246"},
"tag":"service.statistic.push.1329710246"},
]
Limitations
• CometD requests TTL is 120 seconds (by default).

• The statistics filter subscription is set to 10000 seconds, then the subscription is removed and you must send back the same stat request before the end of
TTL subscription.
• You cannot define a statistic in Configuration Server for the GMS application that will be automatically subscribed at GMS startup. You must subscribe to
the statistics as detailed above.

Genesys Mobile Services API Reference Push Notification Service
Push Notification Service
Overview
This page contains useful information about Push Notification service. There are different types of
push notification supported in Genesys Mobile Services:
• HttpCallback Notification
• Android Notification (deprecated)
• Apple Notification
• Orchestration Server Callback Notification
• Windows Push Notification
In addition to discussing these different types of notification, this page also describes Notification
Propagation. For details about the configuration options available for various types of notification, see
the push Section in the Configuration Options Reference.
HttpCallback Notification
This channel is used to push notifications as POST requests to a provided URL. The notification server
expects a response status of 200 (HTTP_OK). The body is ignored. If the response status is not 200
then the notification is considered as failed (see Notification Propagation for more details).
Subscription Request
The URL to POST the message is specified by deviceId in the subscription request. When an event
comes to the NotificationService and its tag matches the corresponding subscription, the POST
request will be sent to the URL, specified by notificationDetails.deviceId.
Usage
The HTTP callback notification channel will send the HTTP request to the specified URL as a reaction
to notification publishing. The format of callback HTTP is described above. The connection will be
plain HTTP without TLS/SSL. The HTTP request will be done with the POST method (hardcoded, not
configurable), where the body will be the plain string, passed as "message" in the notification (see
Notification API). Sample Request body:
{"subscriberId":"A1",

"deviceId":" http://localhost:8080/gms-web/gms/httpcb_notification/value/suffix",
"type":"httpcb"},
"filter":"*"}
Firebase Cloud Messaging Notification

Introduced in: 8.5.114
Due to recent changes in Google Cloud Messaging, GMS now supports Firebase Cloud Messaging
(FCM).
• Refer to the official documentation to Set Up a Firebase Cloud Messaging Client App on Android.
• You will need to retrieve an API Key through the Firebase Console.
• If GMS is deployed behind a firewall, edit your rules to allow the server fcm.googleapis.com and range
5228-5230 for ports, as detailed in the FCM ports and your firewall section of the Firebase Cloud
Messaging documentation.
To configure Native Push Notification through Firebase Cloud Messaging, you can either specify an
apiKey or create a dedicated section to secure passwords (recommended for production
environments) in the push section of your GMS application.
Development
[push]
fcm.apiKey=<serverKey>
pushEnabled=fcm
Production
[push]
fcm=fcmsection
pushEnabled=fcm
[fcmsection]
password=***** (<serverKey>)
• If you define these options in the push section, they will be used as default settings if you do not specify
provider information in your API queries or service configuration.
• You can also define these options for non-default providers in the [push.provider.{ProviderName}]
section, where {ProviderName} is the string you need to provide in the user data of your API queries or
in your service configuration.
For example, you can configure _provider_name={ProviderName} for a given Callback service, or in
a Chat V2 scenario, you could pass this provider name in the push_notification_provider user
data of the requestChat operation.
GMS allows the following options for the provider-level configuration:
• fcm.apiKey

• debug.fcm.apiKey
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:
• [push.provider.{ProviderName}.event.{ServiceName}]
• [push.provider.{ProviderName}.event.{ServiceName}.{EventName}]
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. This configuration sample is applicable for Chat
V2 service only, as event names are different for Chat V1 service even if you can configure it
similarly.
[chat.savings-english]
endpoint = Environment:SavingsEnglish
[chat.savings-russian]
endpoint = Environment:SavingsRussian
[push.provider.bankoperations]
pushEnabled=ios,fcm
fcm.apiKey=****
apple.keystore=/var/genesys/gms/appleKeystore.p12
apple.keystorePassword=****
[push.provider.bankoperations.event]
fcm.body="Please open app for more details
[push.provider.bankoperations.event.chat.savings-english.ParticipantJoined]
fcm.title="Agent has joined an waiting"
[push.provider.bankoperations.event.chat.savings-english.Message]
fcm.title="You got new message from us"
fcm.body="Please answer us soon!"
[push.provider.bankoperations.event.chat.savings-russian.ParticipantJoined]
fcm.title="Агент присоединился и ждет"
fcm.body="Ответьте нам поскорее"
[push.provider.bankoperations.event.chat.savings-russian.Message]
fcm.title="У Вас новое сообщение!"
fcm.body="Ответьте нам поскорее"
Android Notification (Deprecated)
GCM Service
Deprecated in: 8.5.114

Important
GCM is now deprecated. You can no longer create new GCM projects. However,
previous projects are still available.
Android GCM notification relies on the new Google Cloud Messaging (GCM) service, described here.
GCM notifications are made on behalf of an apiKey that is created in Google services and described
by the configuration options for the Genesys Mobile Services Application object. Some key points
about GCM to take into consideration when creating your applications:
• No quota.
• Message size limit is 4096 bytes.
• The push-to-android functionality requires an HTTPS connection to Google Services, so your
environment must be configured to allow HTTPS connections to the following addresses to use this
functionality:
• http://developer.android.com/google/gcm/index.html.
Warning
When subscribing for notifications via GCM, it is important to ensure that the device's
registration ID is provided as notificationDetails.deviceId. This registration ID must
be obtained by registering the device with GCM servers through the Google Services
API. For specific client implementation details, please refer to:
• http://developer.android.com/google/gcm/client.html
Keystore/Truststore Configuration Hints
The default Java keystore/trustore on Windows Server 2003 allows connections to required endpoints
without any additional configuration. However, if you are using a different environment (OS, security
policies, Servlet container, and JVM settings) there may be additional configuration steps to permit
the necessary connections. This section contains the instructions for configuring your system when
the default JVM keystore is replaced with
the -Djavax.net.ssl.keyStore and -Djavax.net.ssl.trustStore JVM startup options on Windows systems.
For other operating systems or keystore/truststore configurations, refer to the documentation for your
environment. To configure the keystore:
1. Use your web browser or another tool to retrieve the certificates required for the following addresses:
• http://developer.android.com/google/gcm/index.html.
2. Import those certificates into the keystore you plan to use.

Important
If the keystore password is null or an empty string and if the keystore contains a key,
then Java may fail to establish the HTTPS connection. In this case, you can either:
• Update the keystore password to provide the correct value (recommended)

• Disable the certificate validation by setting the push.android.ssl_trust_all option
to true (highly unadvised)
Apple Notification
Modified in 8.5.114, 8.5.228.02
Versions older than 8.5.228.02

For versions older than 8.5.228.02, Genesys Mobile Services communicates with the Apple Push
Notification Service over an asynchronous binary interface, that is no longer supported.
Warning
The Apple Push Notification service (APNs) no longer supports the legacy binary
This means that the APN service is no longer be accessible for the legacy binary protocol. Genesys Mobiles
Services stopped supporting the legacy binary protocol, which is the default protocol for Apple Push
Genesys recommends that you upgrade to the latest GMS version (8.5.228.02 or higher) or migrate to a
supported notification type such as:

Version 8.5.228.02 and higher

In 8.5.228.02, GMS has been updated to use the HTTP/2 Apple Push Notification service API and now
supports Apple Notifications.
This interface is a high-speed, high-capacity interface for providers; it uses a streaming TCP socket
design in conjunction with binary content. The binary interface of the production environment is
available through gateway.push.apple.com, port 2195; the binary interface of the sandbox

(development) environment is available through gateway.sandbox.push.apple.com, port 2195. You

may establish multiple, parallel connections to the same gateway or to multiple gateway instances.
See more details here: Apple Push Notification Service.
Digital Channels Chat V2 API with CometD supports native push notifications through Apple Push
Notification Service. To establish a TLS session with APNs, install an Entrust Secure CA root certificate
on the provider’s server. If the server is running macOS, this root certificate is already part of the
keychain. On other systems, the certificate might not be available. You can download this certificate
from the Entrust SSL Certificates website.
APNS Certificate
Starting in release 8.5.206.04, GMS cannot retrieve the APNS certificate generated for the APNS
Sandbox Server. To generate a valid certificate, do not use the private key p12 file generated by the
APNS Console. Instead, generate a new p12 file from your private key (mykey.p12) and the certificate
downloaded from the Apple Console (developer_identity.cer) by executing the following OpenSSL
command:
openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM
openssl pkcs12 -nocerts -in mykey.p12 -out mykey.pem openssl pkcs12 -export -inkey mykey.pem
-in developer_identity.pem -out iphone_dev.p12
Then, you can use the generated iphone_dev.p12 certificate to communicate with the Apple
Sandbox Server.
Client Application Implementation

Incoming notifications are the string representation of a JSON object. To receive the message itself,
please extract the node with key=message.
CometD Notification
This channel is used to push notifications on the CometD channel. When using CometD to get
notifications, the CometD connection should be set up with a subscription for /_genesys.
You also need to make sure that the 'gms_user' header in all CometD related requests is set to the
value uniquely representing the application end-user. Typically, this value would be set up (or at least
verified) by the security gateway located between the client application and GMS.
CometD handshake request
gms_user: BuzzBrain
{"version":"1.0","minimumVersion":"0.9",
"channel":"/meta/handshake","id":"0"}
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT

Content-Length: 230
[{"id":"0","minimumVersion":"1.0",
"supportedConnectionTypes":["websocket","callback-polling","long-polling"],
"successful":true,"channel":"/meta/handshake","ext": "ack":true},
"clientId":"44xkkazwfabw73jrvjsvoy4ul",
"version":"1.0"}]
CometD /meta/connect subscription request
gms_user: BuzzBrain
{"channel":"/meta/connect",
"clientId":"44xkkazwfabw73jrvjsvoy4ul",
"id":"1","connectionType":"long-polling"}
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 116
[{"id":"1","successful":true,
"advice":{"interval":0,"reconnect":"retry","timeout":60000},
CometD /_genesys subscription request
gms_user: BuzzBrain
[{"channel":"/meta/subscribe","subscription":"/_genesys",
"clientId":"44xkkazwfabw73jrvjsvoy4ul","id":"2"}]
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 85
[{"id":"2","subscription":"/_genesys","
successful":true,"channel":"/meta/subscribe"}]
CometD long polling request
gms_user: BuzzBrain
{"clientId":"44xkkazwfabw73jrvjsvoy4ul",
"id":"3","channel":"/meta/connect",
"connectionType":"long-polling"}
HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Length: 85
[{"id":"4","successful":true,"channel":"/meta/connect"}]

Localization of push messages

GMS supports localized messages. To allow this feature, your device must supply a language at
subscription time, corresponding to the application language. For example, the language can be:
Country Language
English (United States) en_US
English en
Estonian et
French fr
... ...
Localization file format is described here.
{"subscriberId":"A1",
"deviceId":" http://localhost:8080/gms-web/gms/httpcb_notification/value/suffix",
"type":"httpcb"},
"language":"de",
"filter":"*"}
See more details on configuring the push section.
Orchestration Server Callback Notification
Subscription
When subscribing to Orchestration Server callback, the user provides the Orchestration Server
sessionId. This parameter is specified by notificationDetails.deviceId, with the type to be used
specified as orscb.
Notification Propagation
The notification event contains 2 parameters: tag and message. The tag parameter is used for
matching the subscription. If the subscription is for Orchestration Server callback, the following
mappings have place:
• notificationDetails.deviceId - mapped to Orchestration Server sessionId

• notificationevent.tag - mapped to Orchestration Server eventName
• message - mapped to the message
Configuration
At the moment no specific configuration options exist for Orchestration Server. Callback relies on the
corresponding ORS Service.

Providers
You will need to add the certificate-related configuration options in the current push configuration
section to a NEW type section that defines the credentials for the set of customer-specific notification
providers. The provider can be specified as part of the notification subscription request.
For each notification provider, create a section with the following name format:
push.provider.providername. For example, push.provider.SalesAppl. This will allow you to define a
different push notification provider (connection) for each group of notification messages that are sent
to applications.
You can define a provider for a group of events that are to be sent to a specific application or to be
sent as part of a given service. This ensures that a given application does not get messages that it
was not intended to receive. This provider definition can be associated with a given service’s
configuration definition or can be passed to the Create Service API for a given application.
If there is no provider defined for a subscription, then the default configuration options defined as
part of the Push configuration section will be used.
The provider-related configuration options can be found here: Configuration Options. There will also
be a set of these credential configuration options for debugging purposes. So, there will be two
provider connections for a provider. The application will be able to specify which provider (production
or debug) connection.
Support of OS-specific capabilities associated with the

notification message
Each Push Notification System has a set of attributes that are sent to the application along with the
base notification message. These attributes are usually related to the message definition itself and
not to a given instance of the message being sent. So these additional OS attributes will be
configured as part of the provider configuration definition. For each event, you will create a section
with the following name format – push.provider.providername.event.eventname. For example,
push.provider.SalesAppl.event.mobile.statuschanged. This is done so that the Notification APIs do not
have to have these OS-specific attributes provided on the API calls. This can define for each
notification message associated with each provider or defined at the general provider level for each
event. Besides, you can provide these OS-specific attributes for various event groups. For example,
you can do it at the individual event level (mobile.statuschanged) or an event sub-grouping (mobile.).
These attributes are all independent of the level they are defined at so you could end up picking up
values for the different attributes from different levels in the hierarchy. This is in the order in which
they will be selected. (first to last):
• Use the event definition values associated with a specific provider definition
• Use the event definition values associated with a general provider definition
• Use the OS-specific attribute values associated with the push section
Also, the event definition can contain multiple different OS-specific attributes so you can have iOS
and Android attributes defined under the same event definition. So the notification framework high-
level logic for processing published events would be:

• Find the subscriptions that have registered to receive this event

• Get the subscriptions associated provider’s event configuration options for this event
• If available use them, otherwise, check the general event configuration options under the provider
configuration section. If available use them otherwise get the general configuration options under the
Push configuration section. If available use them otherwise this event message does not have OS-
specific attributes to apply.
• Form the PNS specific message with the input from the Publish API and the event configuration options
if available
• Send the message over the appropriate provider connection to the PNS.
Consider the example to illustrate the rules. Let's say that we have the subscription associated with
provider SalesApp and with filter A2C.* (match all events starting with A2C). Consider that we have
the following set of sections with OS-specific message formatting options:
• (0) push
• (1) push.provider.event
• (2) push.provider.event.internal
• (3) push.provider.event.internal.advanced
• (4) push.provider.event.A2C
• (5) push.provider.event.A2C.service
• (6) push.provider.event.A2C.service.statuschanged
• (7) push.provider.event.A2C.service.internal
• (8) push.provider.event.A2C.service.statuschanged.agentavailable
• (9) push.provider.SalesApp.event
• (10) push.provider.SalesApp.event.A2C.service.internal
• (11) push.provider.SalesApp.event.A2C.service.statuschanged
Consider that we have the incoming event with tag A2C.service.statuschanged.agentavailable. This
event's tag will match the filter of our subscription associated with provider SalesApp and with filter
A2C.*. So, we will go through the chain of sections in the following order (from most default to most
concrete): 0->1->4->5->6->8->9->11 We'll traverse this chain replacing and overwriting the
options from more default sections with the corresponding options from more concrete sections (this
is equivalent to seeking for all options in more concrete sections first, and accessing more default
only if not found in more concrete). The result set of options will be used for OS-specific message
formatting.
Sensitive Options
You can set sensitive options in different sections of your application configuration. In the following
example, the configuration structure allows to set the password for apple in a new section called
apple-desc.

[push]
apple=apple-desc;
debug-apple=debug-apple-desc
[apple-desc]
password=*********
apple.keystore=xxxxxxxxxxx
[debug-apple-desc]
password=*********
apple.keystore=xxxxxxxxxxx
In case of:
• IOS (APNS): The password option is used instead of apple.keystorePassword.

• Android (GCM): The password option is used instead of android.gcm.apiKey.
• Microsoft (WNS): The password option is used instead of wns.clientSecret.
You do not need to change the name of other options. Genesys recommends that you create a new
section to set the mandatory options and that you keep optional options in the push section. See the
options' detail for more information.
Windows Notification
WNS notification relies on the new Windows Push Notification Services (WNS).
Before you can send notifications using WNS, your app must be registered with the Windows Store
Dashboard. This will provide you with credentials for your app that your cloud service will use in
authenticating with WNS. These credentials consist of a Package Security Identifier (SID) and a secret
key. To perform this registration, go to the Windows Dev Center and select Dashboard. This SID and
secret key need to be set by the configuration options for the Genesys Mobile Services Application
object.
Custom HTTP Notification

If you wish to use a third-party server to handle notifications, configure the push section to use
Custom HTTP notifications.
[push]
pushEnabled = "customhttp"
defaultSubscriptionExpiration = 30
customhttp.url = <third-party server URL>

Your third-party server will receive HTTP POST requests formatted as follows:

POST / HTTP/1.1 <the_customhttp_target_host>

Content-Length: 69
Host: 135.39.40.24:51275
Connection: Keep-Alive
{"message":"<event_message>","deviceId":"<customer_device_id>"}
The received JSON contains the following parameters:
• message–can be a JSON string or a just a string.

• deviceId–ID of the device that the custom notification server will use to identify the mobile.
Important
It is important to provide adequate throughput of the Web Server which processes the
customhttp notification. The latency (in other words, the processing time for a single
HTTP POST request) must be as low as possible as GMS sends all notifications
sequentially. The next request is only sent after a reply from the previous one. For
example, if the latency is 5 milliseconds on average, then a single GMS node can send
200 notifications per second.

Genesys Mobile Services API Reference Callback Push Notifications for Android
Callback Push Notifications for Android

Genesys Mobile Services (GMS) employs various mechanisms to achieve asynchronous messaging
(push notifications). For Android devices, it is a combination of FCM and Comet. Likewise, iOS devices
employ APNs and Comet. The scope of this article is limited to how push notifications are handled in
Android devices, particularly for the Callback application.
Note: For iOS devices, see CallbackPushNotificationsforiOS.
Procedure
Implementing an FCM client is well documented by Google. Alternately, you can also refer to the
Genesys Mobile Services Android Sample for a Genesys FCM implementation.
Push notifications can be divided into two distinct parts:
1. Chat (implements push notifications over Comet)

2. Callback (implemented over FCM)
For Chat, a Bayeux Client is created to listen to all push notifications related to Chat. The default
channel for Chat is /_genesys. The format of Chat push notifications can be seen in the Chat (Comet)
section.
For Callback push notifications, refer to the Genesys Mobile Services Android Sample for reference.
Processing of FCM notifications is a three-step procedure:
1. Obtain Service ID and Action identifier from FCM Intent.

2. Issue HTTP POST to GMS with specified action to obtain action data as JSON.
3. Execute action using data provided by GMS.
The data contained within the FCM Intent is structured as follows:
Intent intent;
Bundle extras = intent.getExtras();
String message = extras.getString("message");
System.out.println(message);
---------------------------------------------
Result:
{
"_id":"$(_id)",
"_action":"$(_action)",
}
In the case of the Genesys sample client, the GenesysCloudMessageReceiver repackages the FCM
Intent into an application-specific Intent:

Intent newIntent = new Intent(context, GenesysSampleActivity.class);

newIntent.setAction(Globals.ACTION_GENESYS_CLOUD_MESSAGE);
newIntent.putExtra(Globals.EXTRA_MESSAGE, extras.getString("message"));
newIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
context.startActivity(newIntent);
This intent is then handled by the GenesysSampleActivity (handleIntent() >

interpretCloudMessage()) where the encapsulated data is used to form an HTTP POST with the
following URL:
$(ServerURL)$(URLPath)$(_id)/$(_action)
for example,
http://135.34.145.123:8080/genesys/1/service/3SQI3S31693JL9
L3R0O5O6T4OC000U73/get-dialog-start-chat
Identifier Description Example Values

URL to Genesys Mobile Services
$(ServerURL) http://135.34.145.123:8080
host
$(URLPath) Path to Services API /genesys/1/service/
$(_id) GMS-issued Service ID 3SQI3S31693JL9L3R0O5O6T4OC000U73
get-dialog-user-confirmation-
provide_code-true
$(_action) Callback action to perform provide_code-false
get-dialog-start-chat
connect-inbound
connect-outbound
wait-for-agent
The response of the HTTP POST request contains JSON, which describes an action to perform and/or
UI elements to display in the client application. Each of these requests is referred to as Dialogs.
Dialogs (REST)
The following examples are JSON structures returned by the GMS Callback service to the client
application. The contents of the JSON response depend on the Callback action performed (as
described in the Procedure section).
Refer to the Genesys Mobile Services Android Sample for examples of how these JSON responses can
be interpreted as actions (for example: Call agent, Display menu, Display dialog) and/or UI elements
(for example, Confirmation dialogs or Menu items).
get-dialog-user-confirmation-provide_code-true
{
"_dialog_id":"0",
"_label":"Agent is available right now",
"_user_action_url":
"$(ExtURLBase)/1/service/$(ServiceID)/not-used",
"_method":"POST",
"_action":"DisplayMenu",
"_expires": "$(Date)",

"_resource_url":
"$(ExtURLBase)/1/service/$(ServiceID)/get-dialog-user-confirmation",
"_content":[
{
"_group_name":"Are you ready?",
"_group_content":[
{
"_dialog_id":"1",
"_label":"Yes, I'm ready to talk",
"_action":"MenuItem",
"_user_action_url":
"$(ExtURLBase)/1/service/$(ServiceID)/connect",
"_method":"POST",
"_id_to_jump_before":"exit://",
"_confirmation_dialog":{
"_text":
"You will hear tones immediately after call is connected. This is normal.",
"_dialog_type":"Notification",
"_dismiss_timeout": 2
}
},{
"_dialog_id":"2",
"_label":"No, try again in 5 minutes",
"_user_action_url":
"$(ExtURLBase)/1/service/$(ServiceID)/snooze",
"_method":"POST",
"_id_to_jump_before":"exit://"
},{
"_dialog_id":"3",
"_label":"Cancel, my problem has been solved",
"_user_action_url":
"$(ExtURLBase)/1/service/$(ServiceID)/cancel",
"_method":"POST",
}
]
}
]
}
get-dialog-user-confirmation-provide_code-false
{
"_dialog_id":"0",
"_user_action_url":
"_method":"POST",
"_resource_url":
"_content":[
{
"_group_content":[
{
"_dialog_id":"1",
"_user_action_url":

"_method":"POST",
},{
"_dialog_id":"2",
"_user_action_url":
"_method":"POST",
},{
"_dialog_id":"3",
"_user_action_url":
"$(ExtURLBase)/1/service/$(ServiceID)/cancel",
"_method":"POST",
}
]
}
]
}
{
"_dialog_id": "1",
"_action":"StartChat",
"_label":"Start Chat",
"_start_chat_url":
"$(ExtURLBase)/1/service/$(ServiceID)/ixn/chat",
"_comet_url":"$(CometURL)",
"_user_header":"$(GMSUser)",
"_chat_parameters":{
"subject":"None"
},
"_id":"$(ServiceID)"
}
connect-inbound
{
"_dialog_id":"0",
"_label":"Connecting ...",
"_action":"DialNumber",
"_tel_url":"n/a",
"_access_code":"n/a",
}
connect-outbound
{
"_dialog_id":"0",
"_action":"ConfirmationDialog",
"_text":"You will receive the call shortly",
"_ok_title":"Ok",

wait-for-agent
{
"_dialog_id":"0",
"_text":"We will notify you when agent is available",
"_ok_title":"Ok",
}
Push Notifications
Chat (Comet)
Message Receipt
{
"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"chatSessionId":"000FRa9NYM9A001K",
"transcriptToShow":[["Message.Text","Stan","Hello.","8","CLIENT"]],
"chatServiceMessage":"Chat service is available"
},
"id":"b2e607a0d21611e3000010932938a0ff",
"tag":"service.chat.refresh.3SQIS3S1693JL9L3R00506T40C000UL4"
},
}
Party Joined/Left
{
"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"transcriptToShow":[["Notice.Joined","Kristi Sippola",
"has joined the session","17","AGENT"]],
},
"id":"b7dd6460d21611e3000010932938a0ff",
},
}
Typing Started/Stopped

"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"transcriptToShow":[["Notice.TypingStarted",
"Kristi Sippola","is typing","20","AGENT"]],
},
"id":"b91bd7d0d21611e3000010932938a0ff",
},
}
Notes
Identifier Description Values

Message.Text
Type of event to display in the Notice.TypingStarted

$(TranscriptType) Notice.TypingStopped
chat log. Notice.Joined
Notice.Left
$(Timestamp) UTC Time format YYYY-MM-DDTHH:MM:SSZ

$(TranscriptPosition) Line Number Some integer.
TRANSCRIPT
$(ChatIxnState) State of chat interaction.
DISCONNECTED

Genesys Mobile Services API Reference Callback Push Notifications for iOS
Callback Push Notifications for iOS

This article is for developers who wish to develop an iOS client application for Genesys Mobile
Services (GMS) Callback Services.
GMS employs various mechanisms to achieve asynchronous messaging (push notifications). For iOS
devices, Apple Push Notification service (APN) and Comet are used. For Android devices, FCM and
Comet are used. This article describes how push notifications should be handled on iOS devices. The
Genesys Mobile Services iOS Sample provides example code for the concepts discussed.
Important
For Android devices, see CallbackPushNotifications for Android.
GMS Support
Versions older than 8.5.228.02

For GMS versions older than 8.5.228.02, Genesys Mobile Services communicates with the Apple Push
Notification Service over an asynchronous binary interface, that is no longer supported.
Warning
The Apple Push Notification service (APNs) no longer supports the legacy binary
This means that the APN service is no longer be accessible for the legacy binary protocol. Genesys Mobiles
Services stopped supporting the legacy binary protocol, which is the default protocol for Apple Push
Genesys recommends that you upgrade to the latest GMS version (8.5.228.02 or higher) or migrate to a
supported notification type such as:

Version 8.5.228.02 and higher

In 8.5.228.02, GMS has been updated to use the HTTP/2 Apple Push Notification service API and now
supports Apple Notifications.

Push Notifications in iOS Applications

Push notifications are used for two purposes in GMS iOS applications:
• Chat
• Callback
Chat
The GMS chat implementation uses Comet push notifications for the text message exchange. GMS
implements a Comet server that the mobile client connects to when a chat session is opened.
The iOS sample code includes a Comet library. The library includes a Comet client class called
DDCometClient. The iOS sample application GMSChatViewController class illustrates how to use
DDCometClient to connect to the server and to send and receive chat messages. The default channel
used for chat is "/_genesys".
Callback
The GMS Callback functions utilize APN for push notifications to iOS applications. The processing of
APN notifications operates as follows:
1. Obtain the Service ID and Action identifier from the notification “message” component (the “message”
component is in JSON format).
2. Issue an HTTP POST to GMS with specified action. The response includes further action data in JSON
format.
3. Execute action using data provided by GMS.
The APN notification contains several components. The “aps” component specifies the confirmation
dialog to display to the user. You can refer to Apple developer documentation for more information on
this topic. The iOS sample application GMSAppDelegate didReceiveRemoteNotification method
provides an example. The “message” component provides the data from GMS and has the following
format:
{
"_id":"$(_id)",
"_action":"$(_action)",
}
The _id and _action parameters are extracted and used to construct a URL for a POST to GMS. The
iOS sample application GMSAppDelegate processAPN method provides an example of this.
$(ServerURL)$(URLPath)$(_id)/$(_action)
such as
http://135.34.145.123:8080/genesys/1/service
/3SQI3S31693JL9L3R0O5O6T4OC000U73/get-dialog-start-chat

URL to Genesys Mobile Services
$(ServerURL) http://135.34.145.123:8080
host


$(URLPath) Path to Services API /genesys/1/service/
$(_id) GMS-issued Service ID 3SQI3S31693JL9L3R0O5O6T4OC000U73
provide_code-true
$(_action) Callback action to perform provide_code-false
connect-inbound
connect-outbound
wait-for-agent
The response of the HTTP POST request contains JSON data, which describes an action to perform
and/or UI elements to display in the client application. Each of these requests will be referred to as
Dialogs.
Dialogs (REST)
The following are examples of JSON structures returned by the GMS Callback service to the client
application. The contents of the JSON response depend on the Callback action performed (as
described in the Callback section).
Refer to the Genesys Mobile Services iOS Sample for examples on how these JSON responses can be
interpreted as actions (for example, Call agent, Display menu, Display dialog) and/or UI elements (for
example, Confirmation dialogs or Menu items).
get-dialog-user-confirmation-provide_code-true
{
"_dialog_id":"0",
"_user_action_url":
"_method":"POST",
"_resource_url":
"_content":[
{
"_group_content":[
{
"_dialog_id":"1",
"_user_action_url":
"_method":"POST",
"_confirmation_dialog":{
"_text":"You will hear tones immediately
after call is connected. This is normal.",
"_dialog_type":"Notification",
"_dismiss_timeout": 2
}

},{
"_dialog_id":"2",
"_user_action_url":
"_method":"POST",
},{
"_dialog_id":"3",
"_user_action_url":
"_method":"POST",
}
]
}
]
}
get-dialog-user-confirmation-provide_code-false
{
"_dialog_id":"0",
"_user_action_url":
"_method":"POST",
"_resource_url":
"_content":[
{
"_group_content":[
{
"_dialog_id":"1",
"_user_action_url":
"_method":"POST",
},{
"_dialog_id":"2",
"_user_action_url":
"_method":"POST",
},{
"_dialog_id":"3",
"_user_action_url":
"_method":"POST",
}

]
}
]
}
{
"_dialog_id": "1",
"_action":"StartChat",
"_label":"Start Chat",
"_start_chat_url":
"$(ExtURLBase)/1/service/$(ServiceID)/ixn/chat",
"_comet_url":"$(CometURL)",
"_user_header":"$(GMSUser)",
"_chat_parameters":{
"subject":"None"
},
}
connect-inbound
{
"_dialog_id":"0",
"_label":"Connecting ...",
"_action":"DialNumber",
"_tel_url":"n/a",
"_access_code":"n/a",
}
connect-outbound
{
"_dialog_id":"0",
"_text":"You will receive the call shortly",
"_ok_title":"Ok",
}
wait-for-agent
{
"_dialog_id":"0",
"_text":"We will notify you when agent is available",
"_ok_title":"Ok",
}

Push Notifications
Chat (Comet)
Message Receipt
{
"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"transcriptToShow":[["Message.Text","Stan","Hello.","8","CLIENT"]],
"chatServiceMessage":"Chat service is available"
},
"id":"b2e607a0d21611e3000010932938a0ff",
},
}
Party Joined/Left
{
"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"transcriptToShow":[["Notice.Joined","Kristi Sippola",
"has joined the session","17","AGENT"]],
},
"id":"b7dd6460d21611e3000010932938a0ff",
},
}
Typing Started/Stopped
{
"data":{
"message":{
"startedAt":"2014-05-02T16:27:38Z",
"transcriptToShow":[["Notice.TypingStarted",
"Kristi Sippola","is typing","20","AGENT"]],
},
"id":"b91bd7d0d21611e3000010932938a0ff",
},

Notes
Identifier Description Values

Message.Text
Type of event to display in the Notice.TypingStarted

$(TranscriptType) Notice.TypingStopped
chat log. Notice.Joined
Notice.Left
$(Timestamp) UTC Time format YYYY-MM-DDTHH:MM:SSZ

$(TranscriptPosition) Line Number Some integer.
TRANSCRIPT
$(ChatIxnState) State of chat interaction.
DISCONNECTED

Genesys Mobile Services API Reference Localization File
Localization File
Overview
The localization file allows you to customize the way you send a message to subscribers. You can
define several messages based on the language of the customer.
Localization file
Format
<?xml version="1.0" encoding="UTF-8" ?>
<messages>
<message id="welcome">
<locale language="en_US">
<entry key="text">Welcome</entry>
</locale>
<locale language="de">
<entry key="text">Willkommen</entry>
</locale>
<locale language="fr">
<entry key="text">Bonjour</entry>
</locale>
<locale language="es">
<entry key="text">\u00A1Hola</entry>
</locale>
<locale language="ja">
<entry key="text">\u3053\u3093\u306B\u3061\u306F</entry>
</locale>
</message>
<message id="welcomeArgs">
<locale language="en_US">
<entry key="text">Dear customer $customer.lastname,
how can you be reminded</entry>
</locale>
<locale language="de">
<entry key="text">Sehr geehrter Kunde $customer.lastname,
wie können Sie daran erinnert werden</entry>
</locale>
<locale language="fr">
<entry key="text">Cher client $customer.lastname,
comment pouvez-vous être rappelé</entry>
</locale>

Genesys Mobile Services API Reference Localization File
<locale language="es">
<entry key="text">$customer.lastname Estimado cliente,
\u00BFc\u00F3mo puede ser recordado</entry>
</locale>
</message>
</messages>
Arguments
Arguments can be added to the message, GMS will replace the arguments in the message with
correct value provided when you publish the message.
Simple style Expanded style
{
{ "message":"welcome",
"message":"welcome", "tag":"yourtag",
"tag":"yourtag", "mediaType":"localizestring",
"mediaType":"localizestring", "locArgs":{
"locArgs":{ "customer":{
"customer.lastname":"Doe" "lastname":"Doe"
} }
} }
}
For example for language option (provided at subscription time) equals to "de" (German), the
customer will receive the following message: Sehr geehrter Kunde Doe, wie können Sie daran
erinnert werden
Genesys Mobile Services Configuration

Please refer to the push section documentation on Genesys Mobile Services Configuration Options.

En GMS 8.5.2 API Book

Uploaded by

Copyright:

Available Formats

En GMS 8.5.2 API Book

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

En GMS 8.5.2 API Book

Uploaded by

Copyright:

Available Formats

This PDF is generated from authoritative online content, and

is provided for convenience only. This PDF cannot be used

Genesys Mobile Services API

Genesys Mobile Services API Reference

Genesys Mobile Services API Reference 3

Service Requires Authentication Header?

Learn about Templates, Scenarios, and APIs

• Service API to check that a

Genesys Mobile Services API Reference 4

Template Name Detailed Built-in Related API(s)

• Storage API to allow users to

Calendar Service API to create

Genesys Mobile Services API Reference 5

New in This Document

Genesys Mobile Services API Reference 6

Genesys Mobile Services API Reference 7

HTTP code 200

The following example stores:

• Key1, Key2, Key3 and FileKey

The time-to-live of the data is 1 hour.

Genesys Mobile Services API Reference 8

HTTP code 200

The following example updates the keys:

• Key1, Key2, Key3 and FileKey

The time-to-live for all of the keys in this update is 1 hour.

Genesys Mobile Services API Reference 9

Query (all keys)

Genesys Mobile Services API Reference 10

HTTP code 200

The following example queries all of the keys associated with id

Query (one key)

HTTP code 200

Genesys Mobile Services API Reference 11

Query (one binary key)

HTTP code 200

Genesys Mobile Services API Reference 12

HTTP code 200

The following example deletes all of the keys associated with id

Genesys Mobile Services API Reference 13

Storage API HTML Sample

Genesys Mobile Services API Reference 14

<meta http-equiv="content-script-type" content="text/javascript">

var storageId = "";

$.post( url, data, callback );

Genesys Mobile Services API Reference 15

Genesys Mobile Services API Reference 16

Genesys Mobile Services API Reference 17

HTTP code 200

Genesys Mobile Services API Reference 18

Change Node Status

HTTP code 200

Genesys Mobile Services API Reference 19

Genesys Mobile Services API Reference 20

Property Mandatory Description

Genesys Mobile Services API Reference 21

Property Mandatory Description

• properties – (Optional) The

- returns the ID of created subscription.

Genesys Mobile Services API Reference 22