Jump to: navigation, search

filter-keys

Section: callback
Default Value: _callback_state,_callback_reason,_request_queue_time_stat,_request_ewt_service,_vq
Valid Values: Comma-separated list of keys
Changes Take Effect: Immediately
Introduced: 8.5.111.04

Defines a list of filtering keys that can be passed in the Query Callback by Queues query of the Callback API.

returned-keys

Section: callback
Default Value: _desired_time,_callback_state,_callback_state,_callback_reason,_ors_session_id
Valid Values: Comma-separated list of keys
Changes Take Effect: Immediately
Introduced: 8.5.111.04

Specifies a list of keys whose values must be returned when fetching callback records with the Query Callback by Queues or Query by properties queries of the Callback Services API.

Note that the following keys are always returned: _id, _desired_time, _service_name, _callback_state, _expiration_time, _customer_number, _url, _callback_reason (optional), in addition to the keys defined in the _customer_lookup_keys option.

_business_hours_service

Section: General
Default Value: No default value
Valid Values: String
Changes Take Effect: Immediately


Name of the office hours service used to provide the available time slots for Callback. The Request Desired Time is verified against the defined regular and specific calendar hours.

_business_hours_service

Section: General
Default Value: No default value
Valid Values: String
Changes Take Effect: Immediately


Name of the office hours service used to provide the available time slots for Callback. The Request Desired Time is verified against the defined regular and specific calendar hours.

_request_time_bucket

Section: Scheduled Call
Default Value: 5
Valid Values: 5,10,15,20,30,60,120
Changes Take Effect: Immediately
Modified: 8.5.202.03

Period of time during which GMS attempts to schedule a specific amount of requests. By default, the time buckets are 5 minutes and the max_request_by_time_bucket option is set to 100; as a result, a maximum of 100 scheduled requests can be done in the given 5 minutes bucket.

Starting in 8.5.202.03, the following values are valid for this option: 5,10,15,20,30,60,120.

Important
Applicable if the _max_request_by_time_bucket option is set.

_request_time_bucket

Section: Scheduled Call
Default Value: 5
Valid Values: 5,10,15,20,30,60,120
Changes Take Effect: Immediately
Modified: 8.5.202.03

Period of time during which GMS attempts to schedule a specific amount of requests. By default, the time buckets are 5 minutes and the max_request_by_time_bucket option is set to 100; as a result, a maximum of 100 scheduled requests can be done in the given 5 minutes bucket.

Starting in 8.5.202.03, the following values are valid for this option: 5,10,15,20,30,60,120.

Important
Applicable if the _max_request_by_time_bucket option is set.

_customer_lookup_keys

Section: General
Default Value: _customer_number
Valid Values: String
Changes Take Effect: Immediately


Comma-separated list of properties to track back customer callback requests. You must only specify identification numbers such as phone numbers, user names, and so on.
For example: _customer_number,_phone_number

_customer_lookup_keys

Section: General
Default Value: _customer_number
Valid Values: String
Changes Take Effect: Immediately


Comma-separated list of properties to track back customer callback requests. You must only specify identification numbers such as phone numbers, user names, and so on.
For example: _customer_number,_phone_number

_fix_plus_on_int_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.200.07

If true, fix international phone numbers in the _customer_number parameter, by adding the '+' sign if missing.

_fix_plus_on_int_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.200.07

If true, fix international phone numbers in the _customer_number parameter, by adding the '+' sign if missing.

returned-keys

Section: callback
Default Value: _desired_time,_callback_state,_callback_state,_callback_reason,_ors_session_id
Valid Values: Comma-separated list of keys
Changes Take Effect: Immediately
Introduced: 8.5.111.04

Specifies a list of keys whose values must be returned when fetching callback records with the Query Callback by Queues or Query by properties queries of the Callback Services API.

Note that the following keys are always returned: _id, _desired_time, _service_name, _callback_state, _expiration_time, _customer_number, _url, _callback_reason (optional), in addition to the keys defined in the _customer_lookup_keys option.

_customer_lookup_keys

Section: General
Default Value: _customer_number
Valid Values: String
Changes Take Effect: Immediately


Comma-separated list of properties to track back customer callback requests. You must only specify identification numbers such as phone numbers, user names, and so on.
For example: _customer_number,_phone_number

_exceptions

Section: General
Default Value:
Valid Values: String
Changes Take Effect: Immediately


List of the exception patterns that should be verified before processing this callback request. See the Pattern configuration for details.

_disallow_impossible_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.107.19
Modified: 8.5.108.02

Disables callbacks for unreachable phone numbers that contain unexpected characters, cannot be parsed, or are too long for the specified country.

Important
If _disallow_impossible_phone_numbers is true, you must set the value of the _default_country option.

_disallow_premium_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Modified: 8.5.108.02

Disables callbacks for premium numbers, such as 900 numbers in the USA. Premium US numbers are listed in Wikipedia and are often called a 900 number or a 1-900 number ("one-nine-hundred"). The customer phone number is checked according to the country configured in the _default_country option.

Important
If _disallow_premium_phone_numbers is true, you must set the value of the _default_country option.

_disallow_impossible_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.107.19
Modified: 8.5.108.02

Disables callbacks for unreachable phone numbers that contain unexpected characters, cannot be parsed, or are too long for the specified country.

Important
If _disallow_impossible_phone_numbers is true, you must set the value of the _default_country option.

_business_hours_service

Section: General
Default Value: No default value
Valid Values: String
Changes Take Effect: Immediately


Name of the office hours service used to provide the available time slots for Callback. The Request Desired Time is verified against the defined regular and specific calendar hours.

_business_hours_service

Section: General
Default Value: No default value
Valid Values: String
Changes Take Effect: Immediately


Name of the office hours service used to provide the available time slots for Callback. The Request Desired Time is verified against the defined regular and specific calendar hours.

_request_queue_time_stat

Section: Scheduled Call
Default Value:
Valid Values:
Changes Take Effect: Immediately


Statistic used to define when a request should be submitted to the Callback Orchestration execution service. The request_execution_time_buffer value and request_queue_time_stat statistic options define when a queued request should be submitted to the execution service. For example, you can use the ExpectedWaitTime statistic to set this option: "ExpectedWaitTime;Queue;8999@SIP_Server;Environment"

_disallow_premium_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Modified: 8.5.108.02

Disables callbacks for premium numbers, such as 900 numbers in the USA. Premium US numbers are listed in Wikipedia and are often called a 900 number or a 1-900 number ("one-nine-hundred"). The customer phone number is checked according to the country configured in the _default_country option.

Important
If _disallow_premium_phone_numbers is true, you must set the value of the _default_country option.

_default_country

Section: Queue Management
Default Value: US
Valid Values: string
Changes Take Effect: Immediately
Introduced: 8.5.107.19
Modified: 8.5.108.02

Sets the default country code as defined in ISO 3166. You must set this option if _disallow_impossible_phone_numbers or _disallow_premium_phone_numbers is enabled.

_disallow_impossible_phone_numbers

Section: Queue Management
Default Value: true
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.107.19
Modified: 8.5.108.02

Disables callbacks for unreachable phone numbers that contain unexpected characters, cannot be parsed, or are too long for the specified country.

Important
If _disallow_impossible_phone_numbers is true, you must set the value of the _default_country option.

_default_country

Section: Queue Management
Default Value: US
Valid Values: string
Changes Take Effect: Immediately
Introduced: 8.5.107.19
Modified: 8.5.108.02

Sets the default country code as defined in ISO 3166. You must set this option if _disallow_impossible_phone_numbers or _disallow_premium_phone_numbers is enabled.

_enable_in_queue_checking

Section: Queue Management
Default Value: true
Valid Values: true, false, strict
Changes Take Effect: Immediately
Introduced: 8.5.109.05
Modified: 8.5.111.04

  • If true, prevents the callback creation if the same customer number has already two callbacks in the queue.
  • If strict, prevents the callback creation if the same customer number has already one callback in the queue.
  • If false, does not check whether the customer is already in queue when creating the callback.

This option applies to both immediate and scheduled callbacks.

_max_ors_submit_attempts

Section: General
Default Value: 3
Valid Values: Integer
Changes Take Effect: Immediately


Maximum number of times that the request for execution will be submitted to ORS. When this number is reached, the request is removed from the persistent queue and discarded.

_request_queue_time_stat

Section: Scheduled Call
Default Value:
Valid Values:
Changes Take Effect: Immediately


Statistic used to define when a request should be submitted to the Callback Orchestration execution service. The request_execution_time_buffer value and request_queue_time_stat statistic options define when a queued request should be submitted to the execution service. For example, you can use the ExpectedWaitTime statistic to set this option: "ExpectedWaitTime;Queue;8999@SIP_Server;Environment"

_request_queue_time_stat

Section: Scheduled Call
Default Value:
Valid Values:
Changes Take Effect: Immediately


Statistic used to define when a request should be submitted to the Callback Orchestration execution service. The request_execution_time_buffer value and request_queue_time_stat statistic options define when a queued request should be submitted to the execution service. For example, you can use the ExpectedWaitTime statistic to set this option: "ExpectedWaitTime;Queue;8999@SIP_Server;Environment"

_request_execution_time_buffer

Section: Scheduled Call
Default Value: 120
Valid Values: Integer (Seconds)
Changes Take Effect: Immediately


Time within which a request should be submitted to the Callback Orchestration execution service.

_desired_time

Section: Scheduled Call
Default Value:
Valid Values: UTCDate
Changes Take Effect: Immediately


Callback desired time. Format is ISO 8601 (in UTC) 'yyyy-MM-ddTHH:mm:ss.SSSZ'. For example: '2013-05-28T15:30:00.000Z'

_mandatory_customer_lookup_keys

Section: General
Default Value: _customer_number
Valid Values: string
Changes Take Effect: Immediately


Sets the comma-separated list of mandatory customer lookup keys that must be provided in the callback schedule request. This list can contain only identification keys such as phone numbers, user names, and so on.

_urs_queued_ttl

Section: URS Queueing
Default Value: 14400
Valid Values: integer
Changes Take Effect: Immediately


The total maximum time (seconds) to wait for a target. After the specified duration has lapsed the virtual interaction will be removed from virtual queue and the callback service will exit.

This option is mandatory.

_notification_message_file

Section: Notification
Default Value: /genesys/1/document/service_template/callback/Resources/Strings/messages.json
Valid Values: url
Changes Take Effect: Immediately


Specifies the URL of the notification message file which contains the externalized strings to be displayed to the customer's mobile.

Tip
This is an advanced parameter. To modify the value of an advanced parameter, you must enable Advanced Parameters in the Service Management UI.

_wait_for_agent

Section: General
Default Value: true
Valid Values: Boolean
Changes Take Effect: Immediately


True to wait for an agent to connect. If this option is set to true, the service will wait for the agent to initiate the interaction and to send the notification to the customer. If the option is set to false, the interaction can start right after the creation of the service instance. In voice scenarios, the access information will be returned immediately with the service ID.


This option is mandatory.

_media_type

Section: General
Default Value: voice
Valid Values: String
Changes Take Effect: Immediately


Media type of the interaction that the service is expected to handle. This option enables URS to select an agent who has the appropriate media capabilities. This is a default value, automatically populated when using the predefined User-Terminated scenario. You do not need to change this value.

This option is mandatory.

_booking_expiration_timeout

Section: Voice - User Originated
Default Value: 30
Valid Values: integer
Changes Take Effect: Immediately


Used to book the access number resource for a period of time. The customer needs to make the call within the specified timeout to ensure a successful match.

This option is mandatory.

_max_time_to_wait_for_agent_on_the_call

Section: General
Default Value: 3600
Valid Values: Integer (seconds)
Changes Take Effect: Immediately


Maximum period of time (seconds) to wait for the agent to accept and answer the call after the customer is connected.

_agent_preview_via_rp

Section: Voice - User Terminated
Default Value: false
Valid Values: boolean
Changes Take Effect: Immediately


If set to true, in an agent preview scenario, the call will be dialed from the route point specified by the _route_point option. Otherwise, the agent DN will make the call.

This option is mandatory.

_agent_preview_timeout_set_notready

Section: Voice - User Terminated
Default Value: false
Valid Values: boolean
Changes Take Effect: Immediately
Introduced: 8.5.201.04

If true, and if the agent does not accept or reject the callback preview invitation in time (defined in the _agent_preview_timeout option), the agent status changes to NOT READY. Additionally, if you configured the _agent_preview_set_notready_reason option, this reason is used as the value of the ReasonCode extension of the EventAgentNotReady event that will be sent. If false (default), the agent status will not change.

_agent_preview_set_notready_reason_key

Section: Voice - User Terminated
Default Value: ReasonCode
Valid Values: Any string
Changes Take Effect: Immediately
Introduced: 8.5.209.02

Key to use for the Agent Not Ready reason attribute if _agent_preview_set_notready_reason_attribute=true.

_agent_preview_set_notready_reason_attribute

Section: Voice - User Terminated
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Introduced: 8.5.209.02

If true, adds the reason key and value to the AttributeReason field of the EventAgentNotReady message. This occurs only if the agent is not ready and does not accept the invitation within the amount of time specified by _agent_preview_timeout, when _agent_preview_timeout_set_notready=true. See _agent_preview_set_notready_reason_key to define an attribute key.

_agent_preview_set_notready_reason

Section: Voice - User Terminated
Default Value: N/A
Valid Values: string
Changes Take Effect: Immediately
Introduced: 8.5.201.04

String representation of a numeric value. If you configure this option and if _agent_preview_timeout_set_notready = true, it will be used as the value of the ReasonCode extension of the EventAgentNotReady event that will be sent.

_agent_preview_allow_reject

Section: Voice - User Terminated
Default Value: 0
Valid Values: Any positive integer
Changes Take Effect: Immediately


Allows the agent to reject the call in the preview dialog.

  • If the option is set to 0, the preview dialog does not display the reject button.
  • If the option is greater than 0, its value determines the number of times that an agent can reject the service request; the reject option will not be displayed to the next agent.

_agent_preview

Section: Voice - User Terminated
Default Value: false
Valid Values: Boolean

Changes Take Effect: Immediately


Enables Agent Preview. If set to true, the Preview Dialog with caller information is displayed to the agent.

_overwritable_options

Section: no category
Default Value:
Valid Values: String
Changes Take Effect: Immediately
Introduced: 8.5.106.19

Defines the parameters (_ors, _redirect, and/or _target) that you wish to be able to overwrite in your REST queries.

This option enables you to pass non-request parameters in your REST queries. For example, if you set _overwritable_options=_ors, a customer application can schedule a callback and pass the _ors parameter of the REST query to submit this callback to a given ORS.

POST /1/service/callback/foo

{
 "_ors": "http://myors:4421"
}

Another scenario is to set _overwritable_options=_redirect in order to disable the redirection for some queries. For example, if you set the _redirect parameter for the foo service as follows....

[service.foo]
_redirect=foo_b
_overwritable_options=_redirect

.... when you invoke foo with a POST query, you can overwrite the value of the _redirect option and disable the redirection to foo_b:

POST /1/service/callback/foo?_redirect=""

_overwritable_options

Section: no category
Default Value:
Valid Values: String
Changes Take Effect: Immediately
Introduced: 8.5.106.19

Defines the parameters (_ors, _redirect, and/or _target) that you wish to be able to overwrite in your REST queries.

This option enables you to pass non-request parameters in your REST queries. For example, if you set _overwritable_options=_ors, a customer application can schedule a callback and pass the _ors parameter of the REST query to submit this callback to a given ORS.

POST /1/service/callback/foo

{
 "_ors": "http://myors:4421"
}

Another scenario is to set _overwritable_options=_redirect in order to disable the redirection for some queries. For example, if you set the _redirect parameter for the foo service as follows....

[service.foo]
_redirect=foo_b
_overwritable_options=_redirect

.... when you invoke foo with a POST query, you can overwrite the value of the _redirect option and disable the redirection to foo_b:

POST /1/service/callback/foo?_redirect=""

Callback Services API

APIs related to Callback Services, builtin services, and ORS scenarios are detailed in GMS API References.

For custom samples, see:

  • ClassicCallbackSample illustrates how to implement an IVR (Genesys Voice Platform VoiceXML) application that communicates with GMS and performs classic Callback scenarios.
  • Custom Callback Sample implements an On-Dial plugin to interface with the GMS Callback service. Developers should use this sample as a reference to build a Composer application that is invoked as a plugin from GMS Callback.

The Service Management UI also includes a Sample panel to test your Callback Services.


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.

1

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.

GMSCallbackStates.png

Callback states While in ORS Description
PROCESSING Ark-ok-icon.png The customer is connected to an agent and talking with this agent.
QUEUED Ark-ok-icon.png The callback is actively waiting for an agent in ORS/URS; the agent is not assigned yet.
SCHEDULED The Callback service handles the callback (there are no sessions started in ORS). While in this state, the request is handled by the callback service running in GMS until the specified desired_time is approaching.
ROUTING Ark-ok-icon.png Customer phone is reached and waiting for an agent.
COMPLETED The call has ended and the Callback is completed with the reason specified in _callback_reason.
PAUSED Ark-ok-icon.png The call is paused. See Pausing 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

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
Content-type
application/json
multipart/form-data
application/x-www-form-urlencoded
URI Parameters
Name Type Description
callback-execution-name *required string
path
Name of the callback execution service provisioned in GMS.
Body (JSON content)
_customer_number*required string Number to call back.

This parameter can also be replaced by any parameter specified in the option _mandatory_customer_lookup_keys (comma-separated list of attributes) that can identify a unique customer.

_copy_from_id
Introduced in 8.5.2
string ID of a Callback in COMPLETED state. The properties and user data of this completed callback are copied in the new callback 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 string 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_buffer=300 (5min), statistic set is "EstimatedWaitTime" returning, for example, 10min
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_buffer=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
<property> string Any properties key/values to be attached. Key/Values may be used in Orchestration

execution service. Keys without an underscore prefix are User Attached Data.

_callback_state string Forces creation of Callback in a specified state.
Important: This is for advanced users that handle

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

_urs_virtual_queue string Queue to use for this callback if several virtual queues are used for callback with identical configuration.
_request_queue_time_stat string Queue statistics. For example, "ExpectedWaitTime;Queue;8999@SIP_Server;Environment".
Note: If the _request_queue_time_stat option is configured in the Callback service, the request parameter is ignored.

Responses

200 OK
Response Body (JSON content)
Name Description
_id
required
The service id for which a successful callback 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
OkTitle
only for immediate callback
Label for the OK button.


500 Internal Server Error
Response body (JSON Content)
Name Value
code

50006

phrase

ORS_MAX_SUBMIT_RETRIES

message

"Callback {id} reached maximum attempts to submit to ORS reached ({max-attempts})"

exception

com.genesyslab.gsg.services.callback.CallbackExceptionMaxORSSubmitAttempts

properties

{ "id": "callback id", "max-attempts": <value for _max_ors_submit_attempts> }



429 Too Many Requests
Response body (JSON Content)
Name Value
code

40001

phrase

NUMBER_ALREADY_BOOKED

message

"There is already {max_queued} or more Callbacks QUEUED for this number, please refer to _enable_in_queue_checking for detail."

exception

com.genesyslab.gsg.services.callback.CallbackExceptionAlreadyBooked

properties

{ "max_queued": <1 if _enable_in_queue_checking=strict or 2 if _enable_in_queue_checking=true>}



429 Too Many Requests
Response body (JSON Content)
Name Value
code

40002

phrase

THROTTLE_SERVICE_LIMIT

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionThrottled

properties
{
"service": <service name>
}



429 Too Many Requests
Response body (JSON Content)
Name Value
code

40003

phrase

THROTTLE_SERVICE_INTERVAL_LIMIT

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionThrottled

properties
{
"service": <service name>,
"interval": <interval throttling limit>
}



429 Too Many Requests
Response body (JSON Content)
Name Value
code

40004

phrase

THROTTLE_SERVICE_PARAMETER_LIMIT

message

"Limit of queued callbacks for {service} is reached for parameter {parameter}. Reached {attempts} times today."

exception

com.genesyslab.gsg.services.callback.CallbackExceptionThrottled

properties
{ "service": <service name>,
"parameter": <parameter triggering the throttling>,
"attempts": <number of attempts reached> }



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message
  • "Request cannot be processed because callback {id} to copy is not COMPLETED. Check parameter _copy_from_id"
exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>

}



400 Bad Request
Response body (JSON Content)
Name Value
code

40030

phrase

CALLBACK_NOT_FOUND

message

"Callback {id} to copy from cannot be found"

exception

com.genesyslab.gsg.services.callback.CallbackExceptionNotFound

properties
{
"id": <callback service id>,
"service": <service name>,
"time": <ISO UTC time>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40050, 40051

phrase
  • SLOT_UNAVAILABLE (40050)
  • SLOT_UNAVAILABLE_PROPOSAL(40051)
message
  • "No time slots available."
  • "Too many requests at desired time slot {slot}. Proposing time slots."
  • "Office is closed at desired time slot {slot}. Proposing time slots."
exception

com.genesyslab.gsg.services.callback.CallbackExceptionAvailability

properties
{
"slot": <ISO UTC time range>,
"service": <service name>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50020

phrase

BAD_CONFIGURATION

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

properties
{
"service": <service name>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50005

phrase

CALENDAR_ERROR

message

message returned by Calendar service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50004

phrase

CAPACITY_ERROR

message

message returned by Capacity service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50030

phrase

ORS_ERROR

message
  • "Invalid ORS response"
  • message returned by ORS strategy
exception

com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50040

phrase

SERVICE_REDIRECT_FAILED

message

message from redirected service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionServiceRedirect

properties



400 Bad Request
Response body (JSON Content)
Name Value
code

40040

phrase

NUMBER_REJECTED

message
exception

com.genesyslab.gsg.services.callback.CallbackExceptionNumber

properties



500 Internal Server Error
Response body (JSON Content)
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
Name Type Description
callback-execution-name *required string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
service_id *required string
path
This is the service id returned from the initial start callback response.
discard_ors_failure boolean False by default. If true, GMS can bypass ORS failures and marks the cancellation of the callback.

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


400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

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

properties
{
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message
  • "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 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}] - reached state COMPLETED"
exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40030

phrase

CALLBACK_NOT_FOUND

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

com.genesyslab.gsg.services.callback.CallbackExceptionNotFound

properties
{
"id": <callback service id>,
"service": <service name>,
"time": <ISO UTC time>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50030

phrase

ORS_ERROR

message
  • "Invalid ORS response"
  • message returned by ORS strategy
exception

com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
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
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
Content-type
application/json
multipart/form-data
application/x-www-form-urlencoded
URI Parameters
Name Type Description
callback-execution-name *required string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
service_id *required string
path
This is the service id returned from the initial start callback response.
Body (JSON content)
_new_desired_time string The new time for which to reschedule the callback.

If provided and validated through office-hours, _callback_state will be automatically switched to "scheduled" or "immediate", discarding _callback_state property.

_callback_state string Possible values are SCHEDULED, QUEUED, ROUTING, PROCESSING, COMPLETED.

Note: The _new_desired_time parameter triggers the re-schedule operation, discarding the _callback_state parameter.

<other properties> any Properties to be updated in request.

Responses

200 OK
No JSON Body


400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

message
  • "Callback {id} does not contain the mandatory customer lookup keys {keys}"
  • "Callback {id} does not contain _desired_time property."
  • "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) - 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

properties
{"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key> }



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message
  • "Invalid service stored for callback {id}."
  • "Request cannot be processed because callback {id} to copy is not COMPLETED. Check parameter _copy_from_id"
  • "Callback {id} is no longer scheduled. State={state}"
  • "Callback {id} has invalid desired time stored."
  • "Rejecting update : {service}=[{id} @ {time}] - reached state COMPLETED"
exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40030

phrase

CALLBACK_NOT_FOUND

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

com.genesyslab.gsg.services.callback.CallbackExceptionNotFound

properties
{
"id": <callback service id>,
"service": <service name>,
"time": <ISO UTC time>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40050, 40051

phrase
  • SLOT_UNAVAILABLE (40050)
  • SLOT_UNAVAILABLE_PROPOSAL(40051)
message
  • "No time slots available."
  • "Too many requests at desired time slot {slot}. Proposing time slots."
  • "Office is closed at desired time slot {slot}. Proposing time slots."
exception

com.genesyslab.gsg.services.callback.CallbackExceptionAvailability

properties
{
"slot": <ISO UTC time range>,
"service": <service name>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50020

phrase

BAD_CONFIGURATION

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

properties
{
"service": <service name>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50005

phrase

CALENDAR_ERROR

message

message returned by Calendar service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50004

phrase

CAPACITY_ERROR

message

message returned by Capacity service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50030

phrase

ORS_ERROR

message
  • "Invalid ORS response"
  • message returned by ORS strategy
exception

com.genesyslab.gsg.services.callback.CallbackExceptionFromORS

properties



400 Bad Request
Response body (JSON Content)
Name Value
code

40040

phrase

NUMBER_REJECTED

message
exception

com.genesyslab.gsg.services.callback.CallbackExceptionNumber

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50050

phrase

UNKNOWN_ERROR

message

"Error processing callback {message} "

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,
          "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
Content-type
application/json
Body (JSON content)
_customer_number String array List of Customer Numbers or Service IDs that identify the callback service instances that must be deleted.
_id String array List of service IDs that identify the callback service instances that must be deleted.

Responses

200 OK
Response Body (JSON content)
Name Description
success
required
Array Array of service IDs and Customer Numbers that were deleted or were considered as successful with a reason.
[{ "_id": "68542134" }, { "reason": "no callback(s) to delete", "_customer_number": "132456" } ]
errors
required
Array 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", "message": "No such 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" } ]


500 Internal Server Error
Response body (JSON Content)
Name Value
code

50020

phrase

BAD_CONFIGURATION

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

properties
{
"service": <service name>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

message
  • "No such lookup possible for {properties}"
  • "No lookup possible. No properties to look for."
  • 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

properties
{
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



500 Internal Server Error
Response body (JSON Content)
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/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

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 *required string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
id *required string
path
Callback ID.

Responses

200 OK
Response Body (JSON content)
Name Description
<none>
  • If accepted, the currently outstanding callback request.

[

     {
        "_id": <callback id>,
        "desired_time": <ISO UTC time>,
        "url": <service URL>,
        "_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.


400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

message
  • "No such lookup possible for {properties}"
  • "No lookup possible. No properties to look for."
  • 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

properties
{
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
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/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

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
callback-execution-name string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
property=value *required string
path
This is a property name used to query the callback. Properties allowing the Callback request 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 string 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 Callback requests:

  • AND means that all property=value must match;
  • OR means any property=value can match.
_callback_state

Since 8.5.101.03

string

Specifies a unique state to filter onto. For example:

  • _callback_state='COMPLETED' filters callbacks and returns only callbacks in COMPLETED state.
  • _callback_state='!COMPLETED' filter callbacks and only return the ones that are not 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

Since 8.5.101.03

string

Specifies ISO timestamps. All callback matching lookup properties that were scheduled before this time will be filtered out.

_desired_time_to

Since 8.5.101.03

string

Specifies ISO timestamps. All callback matching lookup properties that were scheduled after this time will be filtered out.

Responses

200 OK
Response Body (JSON content)
Name Type Description
<none>
  • 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>,
        "_expiration_time":<ISO UTC time>,
        "_customer_number": <customer number>,
        "url": <service URL>
      },

...

 ]
  • If not, an error code indicating the reason.


400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

message
  • "No such lookup possible for {properties}"
  • "No lookup possible. No properties to look for."
  • 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

properties
{
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
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"
       },
      {
         "_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"
      }
   ]

Query-Availability

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 *required string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
JSON Body
start date Start date is specified in ISO 8601 format, using UTC as the timezone: yyyy-MM-ddTHH:mm:ss.SSSZ. If not specified, it is assumed to be now.
timestamp date Alias to start parameter; kept for compatibility reasons.
number-of-days integer Used as an alternative to the end date. If neither end nor number-of-days is specified, the end date is assumed to be the same as the start date.
end date End date is specified in ISO 8601 format, using UTC as timezone: yyyy-MM-ddTHH:mm:ss.SSSZ. If neither end nor number-of-days is specified, the end date is assumed to be the same as the start date.
max-time-slots integer Maximum number of time slots to be included in the response when the office is open and 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"
}

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
Name Type Description
callback-execution-name *required string
path
Name of the callback execution service of 'ors' type provisioned in GMS.
start date 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 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-ms long 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 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 integer Number of days used to define the availability period starting at the start or start-ms date. You can use this parameter instead of the end or of the end-ms parameter.
end date End date, in "ISO 8601" format, using the UTC timezone: yyyy-MM-ddTHH:mm:ss.SSSZ. By 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-ms long End date in epoch time, that is the number of milliseconds since 00:00:00, Thursday, 1 January 1970 (UTC).

Set only one of the end, end-ms, or number-of-days parameters.

max-time-slots integer Maximum number of time slots to include in the response if the office is open and the capacity greater than zero. You can use this parameter to improve query performance over a lengthy period of time.
timezone string Timezone for the start and end date parameters. Additionally, the response object will return the localTime fields formatted in this timezone.
report-busy boolean If true, the response includes the slots where the office is open and 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
Response Body (JSON content)
Name Type Description
slots
required
String array of slots

Array of ordered slots and each slot includes the minute duration (durMinutes), and the timezone.

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


400 Bad Request
Response body (JSON Content)
Name Value
code

40010

phrase

BAD_PARAMETER

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

properties
{
"id": <callback id>,
"keys": <missing lookup key>,
"day": <specified day value>,
"properties": <lookup properties>,
"option": <invalid option key>
}



400 Bad Request
Response body (JSON Content)
Name Value
code

40050, 40051

phrase
  • SLOT_UNAVAILABLE (40050)
  • SLOT_UNAVAILABLE_PROPOSAL(40051)
message
  • "No time slots available."
  • "Too many requests at desired time slot {slot}. Proposing time slots."
  • "Office is closed at desired time slot {slot}. Proposing time slots."
exception

com.genesyslab.gsg.services.callback.CallbackExceptionAvailability

properties
{
"slot": <ISO UTC time range>,
"service": <service name>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50020

phrase

BAD_CONFIGURATION

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



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50005

phrase

CALENDAR_ERROR

message

message returned by Calendar service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCalendarError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
code

50004

phrase

CAPACITY_ERROR

message

message returned by Capacity service

exception

com.genesyslab.gsg.services.callback.CallbackExceptionCapacityError

properties



500 Internal Server Error
Response body (JSON Content)
Name Value
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"
}


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}&start_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 which to query callback requests.

The format is ISO 8601 "yyyy-MM-ddTHH:mm:ss.SSSZ".

For example: "2013-05-27T15:30:00.000Z"

{iso_end_time} string 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.

The format is ISO 8601 "yyyy-MM-ddTHH:mm:ss.SSSZ".

For example: "2013-05-28T15:30:00.000Z"

{states} string Comma-separated list of callback states used to filter the returned results. For example, if states=SCHEDULED,QUEUED, only scheduled and queued callbacks are returned.

If not specified, all the callbacks of the given queue are returned.

{max} integer This is the maximum number of requests to return for each queue.

If not specified, 500 maximum requests per queue are returned.

callback-execution-name string Name of the callback execution service provisioned in GMS. For example, BasicCallback.

If not specified, the queues for all services are returned.

{max} integer This is the maximum number of requests to return for each queue.

If not specified, 500 maximum requests per queue are returned.

Responses
200 OK
Response Body (JSON content)
Name Mandatory Description
List of target queues
required
string

If accepted, a tree list of target queues and the following properties:

<Queue name>: {
"_customer_number": <customer number>,
"_callback_state": <callback state>,
"_desired_time": <callback UTC desired time>,
"_id": <callback service id>,
"url": <request>
}


400 Bad Request
Response body (JSON Content)
Name Value
code

40020

phrase

INVALID_OPERATION

message

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

exception

com.genesyslab.gsg.services.callback.CallbackExceptionInvalidOperation

properties
{"id": <callback id>,
"service": <service name>,
"time": <ISO UTC time>,
"state": <callback state>,
"message": <ORS server's message>,
"filter": <filtering expression>
}



500 Internal Server Error
Response body (JSON Content)
Name Value
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"
          }
      ]
   }

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
{callback-execution-name} string Name of a callback execution service. If you set this parameter, the response will return the 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_name=service2&service_name=service3 

Responses

HTTP code 200
HTTP message OK
Response Body (JSON content) 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>,
    }
  }


500 Internal Server Error
Response body (JSON Content)
Name Value
code

50050

phrase

UNKNOWN_ERROR

message

"Error processing callback {message} "

exception

com.genesyslab.gsg.services.callback.CallbackExceptionUnknown

properties

{ "message": <message catched> }


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

Name Type Description
BODY Parameters
{callback-service-id}
required
string ID of the callback execution 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
Response Body (JSON content)

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

500 Internal Server Error
Response body (JSON Content)
Name Value
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,
   "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".


POST /genesys/1/admin/callback/reportcancelled

Name Type Description
BODY Parameters
callback_reason
required'
string The reason for the cancellation. 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
Response Body (JSON content) CSV-formatted results for exported records:
<property-1>,<property-2>,...,<property-n>
<record-1-property1>,<record-1-property2>,...,<record-1-propertyn>
...
<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.


500 Internal Server Error
Response body (JSON Content)
Name Value
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/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 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.
This page was last edited on April 13, 2017, at 13:08.
Comments or questions about this documentation? Contact us for support!