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
Callback Services API

2/24/2022
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",

Genesys Mobile Services API Reference 2

Callback Services API

"_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.

Genesys Mobile Services API Reference 3

Callback Services API

Genesys Mobile Services API Reference 4

Callback Services API

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
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
_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.

Genesys Mobile Services API Reference 5

Callback Services API

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

Genesys Mobile Services API Reference 6

Callback Services API

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.

Genesys Mobile Services API Reference 7

Callback Services API

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.

Genesys Mobile Services API Reference 8

Callback Services API

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

Genesys Mobile Services API Reference 9

Callback Services API

• 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
application/x-www-form-urlencoded

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.

Genesys Mobile Services API Reference 10

Callback Services API

• 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

Genesys Mobile Services API Reference 11

Callback Services API

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
Response Body (JSON content)
_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

Genesys Mobile Services API Reference 12

Callback Services API

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

Response body (JSON Content)

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

Genesys Mobile Services API Reference 13

Callback Services API

Name Value

429 Too Many Requests

Response body (JSON Content)

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

429 Too Many Requests

Response body (JSON Content)

code 40003

phrase THROTTLE_SERVICE_INTERVAL_LIMIT

"Limit of queued callbacks for {service} is reached for interval

message {interval}s."

exception com.genesyslab.gsg.services.callback.CallbackExceptionThrottled

"service": <service name>,

properties
"interval": <interval throttling limit>

Genesys Mobile Services API Reference 14

Callback Services API

Name Value

429 Too Many Requests

Response body (JSON Content)

code 40004

phrase THROTTLE_SERVICE_PARAMETER_LIMIT

"Limit of queued callbacks for {service} is reached for

message parameter {parameter}. Reached {attempts} times today."

exception com.genesyslab.gsg.services.callback.CallbackExceptionThrottled

{ "service": <service name>,

"parameter": <parameter triggering the

properties throttling>,

"attempts": <number of attempts reached> }

Name Value

400 Bad Request

Response body (JSON Content)

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

"service": <service name>,

properties
"time": <ISO UTC time>,

"state": <callback state>,

Genesys Mobile Services API Reference 15

Callback Services API

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

"filter": <filtering expression>

}

Name Value

400 Bad Request

Response body (JSON Content)

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

"service": <service name>,

properties
"time": <ISO UTC time>

Name Value

400 Bad Request

Response body (JSON Content)

code 40050, 40051

• SLOT_UNAVAILABLE (40050)
phrase
• SLOT_UNAVAILABLE_PROPOSAL(40051)

Genesys Mobile Services API Reference 16

Callback Services API

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
"service": <service name>

Name Value

500 Internal Server Error

Response body (JSON Content)

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."
• "Service option {service} / _default_country is
not configured. But option
_disallow_premium_phone_numbers is set. We
message cannot validate phone numbers without
knowing the country."
• "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

Genesys Mobile Services API Reference 17

Callback Services API

Name Value

section because this service has parameter

_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

"service": <service name>

properties
}

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50005

phrase CALENDAR_ERROR

message message returned by Calendar service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties

Genesys Mobile Services API Reference 18

Callback Services API

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50004

phrase CAPACITY_ERROR

message message returned by Capacity service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50030

phrase ORS_ERROR

• "Invalid ORS response"

message
• message returned by ORS strategy

exception com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50040

Genesys Mobile Services API Reference 19

Callback Services API

Name Value

phrase SERVICE_REDIRECT_FAILED

message message from redirected service

exception com.genesyslab.gsg.services.callback.CallbackExceptionServiceRedirect

properties

Name Value

400 Bad Request

Response body (JSON Content)

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
_disallow_impossible_phone_numbers"
• "Customer Number is not allowed. Check option
_exceptions"

exception com.genesyslab.gsg.services.callback.CallbackExceptionNumber

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

Genesys Mobile Services API Reference 20

Callback Services API

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.

Genesys Mobile Services API Reference 21

Callback Services API

• 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
Name Type Description

callback-execution-name string Name of the callback execution

*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

Response body (JSON Content)

code 40010

phrase BAD_PARAMETER

Genesys Mobile Services API Reference 22

Callback Services API

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

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

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

Genesys Mobile Services API Reference 23

Callback Services API

Name Value

reached state COMPLETED"

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

"time": <ISO UTC time>,

"state": <callback state>,

properties
"message": <ORS server's message>,

"filter": <filtering expression>

Name Value

400 Bad Request

Response body (JSON Content)

code 40030

phrase CALLBACK_NOT_FOUND

• "Callback {id} cannot be found"

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionNotFound

"id": <callback service id>,

"service": <service name>,

properties
"time": <ISO UTC time>

Genesys Mobile Services API Reference 24

Callback Services API

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50030

phrase ORS_ERROR

• "Invalid ORS response"

message
• message returned by ORS strategy

exception com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

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

Genesys Mobile Services API Reference 25

Callback Services API

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
application/x-www-form-urlencoded

URI Parameters
Name Type Description

callback-execution-name string Name of the callback execution

*required path service of 'ors' type provisioned
in GMS.

Genesys Mobile Services API Reference 26

Callback Services API

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

Response body (JSON Content)

code 40010

phrase BAD_PARAMETER

• "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) -

Genesys Mobile Services API Reference 27

Callback Services API

Name Value

epoch %ds"
• "Cannot create service, missing mandatory
callback option {option}"
• "Cannot create service, empty mandatory
callback option {option}"
• Generic parser exception message: Typically, a
bad date parsing may fall there as a bad
parameter error with the appropriate
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

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

• "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."

Genesys Mobile Services API Reference 28

Callback Services API

Name Value

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

reached state COMPLETED"

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

"time": <ISO UTC time>,

"state": <callback state>,

properties
"message": <ORS server's message>,

"filter": <filtering expression>

Name Value

400 Bad Request

Response body (JSON Content)

code 40030

phrase CALLBACK_NOT_FOUND

• "Callback {id} cannot be found"

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionNotFound

"id": <callback service id>,

"service": <service name>,

properties
"time": <ISO UTC time>

Genesys Mobile Services API Reference 29

Callback Services API

Name Value

400 Bad Request

Response body (JSON Content)

code 40050, 40051

• SLOT_UNAVAILABLE (40050)
phrase
• SLOT_UNAVAILABLE_PROPOSAL(40051)

• "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
"service": <service name>

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50020

phrase BAD_CONFIGURATION

• "Service option {service} / _default_country is

message not configured. But option
_disallow_impossible_phone_numbers is set. We

Genesys Mobile Services API Reference 30

Callback Services API

Name Value

cannot validate phone numbers without

knowing the country."
• "Service option {service} / _default_country is
not configured. But option
_disallow_premium_phone_numbers is set. We
cannot validate phone numbers without
knowing the country."
• "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
section because this service has parameter
_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

"service": <service name>

properties
}

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50005

Genesys Mobile Services API Reference 31

Callback Services API

Name Value

phrase CALENDAR_ERROR

message message returned by Calendar service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50004

phrase CAPACITY_ERROR

message message returned by Capacity service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50030

phrase ORS_ERROR

• "Invalid ORS response"

message
• message returned by ORS strategy

exception com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

Genesys Mobile Services API Reference 32

Callback Services API

Name Value
properties

Name Value

400 Bad Request

Response body (JSON Content)

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
_disallow_impossible_phone_numbers"
• "Customer Number is not allowed. Check option
_exceptions"

exception com.genesyslab.gsg.services.callback.CallbackExceptionNumber

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

Genesys Mobile Services API Reference 33

Callback Services API

Name Value

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

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
{
"_new_desired_time":"2014-07-22T10:00:00.000Z"
}
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
{
"_new_desired_time":"2013-05-27T16:45:00.000Z"
}
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,

Genesys Mobile Services API Reference 34

Callback Services API

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

Introduced in 8.5.201
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.

Genesys Mobile Services API Reference 35

Callback Services API

Responses

Name Description

200 OK
Response Body (JSON content)
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

500 Internal Server Error

Response body (JSON Content)

code 50020

phrase BAD_CONFIGURATION

• "Service option {service} / _default_country is

not configured. But option
message _disallow_impossible_phone_numbers is set. We
cannot validate phone numbers without
knowing the country."

Genesys Mobile Services API Reference 36

Callback Services API

Name Value

• "Service option {service} / _default_country is

not configured. But option
_disallow_premium_phone_numbers is set. We
cannot validate phone numbers without
knowing the country."
• "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
section because this service has parameter
_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

"service": <service name>

properties
}

Name Value

400 Bad Request

Response body (JSON Content)

code 40010

phrase BAD_PARAMETER

Genesys Mobile Services API Reference 37

Callback Services API

Name Value

• "No such lookup possible for {properties}"

• "No lookup possible. No properties to look for."
• Generic parser exception message: Typically, a
message bad date parsing may result in a bad parameter
error with the appropriate 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

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

properties
"time": <ISO UTC time>,

Genesys Mobile Services API Reference 38

Callback Services API

Name Value
"state": <callback state>,

"message": <ORS server's message>,

"filter": <filtering expression>

Name Value

500 Internal Server Error

Response body (JSON Content)

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

Genesys Mobile Services API Reference 39

Callback Services API

{
"_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

Introduced in 8.5.207
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
Name Type Description

callback-execution-name string Name of the callback execution

*required path service of 'ors' type provisioned
in GMS.
string
id *required path Callback ID.

Responses

Name Description

200 OK
Response Body (JSON content)

• If accepted, the currently outstanding callback

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

Genesys Mobile Services API Reference 40

Callback Services API

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

Response body (JSON Content)

code 40010

phrase BAD_PARAMETER

• "No such lookup possible for {properties}"

• "No lookup possible. No properties to look for."
• Generic parser exception message: Typically, a
message bad date parsing may result in a bad parameter
error with the appropriate 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>

Genesys Mobile Services API Reference 41

Callback Services API

Name Value

400 Bad Request

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

"time": <ISO UTC time>,

"state": <callback state>,

properties
"message": <ORS server's message>,

"filter": <filtering expression>

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

Genesys Mobile Services API Reference 42

Callback Services API

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",
"_customer_number": "12345",
"_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

Genesys Mobile Services API Reference 43

Callback Services API

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
Name Type Description
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.

Genesys Mobile Services API Reference 44

Callback Services API

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.

Genesys Mobile Services API Reference 45

Callback Services API

_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

Name Type Description

200 OK
Response Body (JSON content)

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

Genesys Mobile Services API Reference 46

Callback Services API

Name Value

400 Bad Request

Response body (JSON Content)

code 40010

phrase BAD_PARAMETER

• "No such lookup possible for {properties}"

• "No lookup possible. No properties to look for."

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

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>

Genesys Mobile Services API Reference 47

Callback Services API

Name Value

400 Bad Request

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

"time": <ISO UTC time>,

"state": <callback state>,

properties
"message": <ORS server's message>,

"filter": <filtering expression>

Genesys Mobile Services API Reference 48

Callback Services API

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

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",
"_expiration_time": "2014-11-03T18:36:45.000Z",
"_customer_number": "555-5461206",
"url": "/1/service/callback/BasicCallback/a550a12e-ca77-4146-98d0-58960e0939f7"

Genesys Mobile Services API Reference 49

Callback Services API

},
{
"_id": "4a1ea889-1ef7-432d-a543-cff96b4a2daf",
"desired_time": "2013-05-27T15:10:00.000Z",
"_callback_state": "SCHEDULED",
"_expiration_time": "2014-11-03T18:36:45.000Z",
"_customer_number": "555-5461206",
"url": "/1/service/callback/BasicCallback/4a1ea889-1ef7-432d-a543-cff96b4a2daf"
}
]

Genesys Mobile Services API Reference 50

Callback Services API

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
Name Type Description

callback-execution-name string Name of the callback execution

*required path service of 'ors' type provisioned
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.

Genesys Mobile Services API Reference 51

Callback Services API

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

Genesys Mobile Services API Reference 52

Callback Services API

Name Type Description

callback-execution-name string Name of the callback execution

*required path service of 'ors' type provisioned
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).

Genesys Mobile Services API Reference 53

Callback Services API

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.

Name Type Description

200 OK
Response Body (JSON content)

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

Genesys Mobile Services API Reference 54

Callback Services API

Name Type Description

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

Response body (JSON Content)

code 40010

Genesys Mobile Services API Reference 55

Callback Services API

Name Value

phrase BAD_PARAMETER

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

bad date parsing may fall there as a bad
parameter error with the appropriate
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

Response body (JSON Content)

code 40050, 40051

• SLOT_UNAVAILABLE (40050)
phrase
• SLOT_UNAVAILABLE_PROPOSAL(40051)

• "No time slots available."

message
• "Too many requests at desired time slot {slot}.

Genesys Mobile Services API Reference 56

Callback Services API

Name Value

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
"service": <service name>

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50020

phrase BAD_CONFIGURATION

• "Option service.{service} /
_business_hours_service not configured."
• "Option _business_hours_service is invalid:
{message}"
• "Service undefined: {service}"
message
• "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
"service": <service name>

Genesys Mobile Services API Reference 57

Callback Services API

Name Value
}

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50005

phrase CALENDAR_ERROR

message message returned by Calendar service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50004

phrase CAPACITY_ERROR

message message returned by Capacity service

exception com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties

Genesys Mobile Services API Reference 58

Callback Services API

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

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

Genesys Mobile Services API Reference 59

Callback Services API

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.

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

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
Name Type Description
{iso_start_time} string This is the minimum time for

Genesys Mobile Services API Reference 60

Callback Services API

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
Response Body (JSON content)

Genesys Mobile Services API Reference 61

Callback Services API

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

Response body (JSON Content)

code 40020

phrase INVALID_OPERATION

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

exception com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

{"id": <callback id>,

"service": <service name>,

"time": <ISO UTC time>,

"state": <callback state>,

properties
"message": <ORS server's message>,

"filter": <filtering expression>

Genesys Mobile Services API Reference 62

Callback Services API

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

Example

GET http://localhost:8080/genesys/1/admin/callback/queues

Result

200 OK

{
"BasicCallback":
[
{
"_customer_number": "654321",
"_callback_state": "PROCESSING",
"_desired_time": "2013-06-07T16:25:00.000Z",
"_id": "fd30abb97bd04885b544893276fb534b",
"url": "/1/service/callback/BasicCallback/fd30abb97bd04885b544893276fb534b"
}
],
"AdvancedCallback":
[
{
"_customer_number": "654321",
"_callback_state": "QUEUED",
"_desired_time": "2013-06-07T16:35:00.000Z",
"_id": "07d2ddd506f04b4ba91aba59c4fa8871",
"url": "/1/service/callback/AdvancedCallback/07d2ddd506f04b4ba91aba59c4fa8871"
},
{
"_customer_number": "654321",
"_callback_state": "SCHEDULED",
"_desired_time": "2013-06-07T16:45:00.000Z",
"_id": "8f68d4969d904d039ccf0101fac39283",
"url": "/1/service/callback/AdvancedCallback/8f68d4969d904d039ccf0101fac39283"

Genesys Mobile Services API Reference 63

Callback Services API

}
]
}

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.

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

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

Genesys Mobile Services API Reference 64

Callback Services API

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>,
Response Body (JSON content)
"services": {
<service-1>: <number of callbacks in
progress for service-1 >,
...
<service-n>: <number of callbacks in
progress for service-n>,
}
}

Name Value

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

Genesys Mobile Services API Reference 65

Callback Services API

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.

Name Type Description

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.

Genesys Mobile Services API Reference 66

Callback Services API

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.
Response Body (JSON content)
• 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.

Genesys Mobile Services API Reference 67

Callback Services API

• 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

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties { "message": <message catched> }

Example

Operation

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

Connection: close
Content-Length: 0
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Response:

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

Genesys Mobile Services API Reference 68

Callback Services API

"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":"GMSCallbackAgents@stat.GA",
"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.

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

Name Type Description

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

Genesys Mobile Services API Reference 69

Callback Services API

Name Type Description

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
Response Body (JSON content)
...

<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

500 Internal Server Error

Response body (JSON Content)

code 50050

phrase UNKNOWN_ERROR

message "Error processing callback {message} "

exception com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

Genesys Mobile Services API Reference 70

Callback Services API

Name Value

properties { "message": <message catched> }

Example

Operation

POST /genesys/1/admin/callback/reportcancelled
{
"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

POST /genesys/1/admin/callback/reportcancelled

HTTP/1.1
Connection: keep-alive
Content-Type: application/json
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
2017-05-11T12:21:00+00:00,3329284576,exported_value1,exported_value2
2017-05-10T07:21:00+00:00,3329284577,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

Genesys Mobile Services API Reference 71

Callback Services API

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 72