Maintenance Notice - PDF Generation
Dynamic PDF generation for web-based content is temporarily unavailable. This maintenance affects dynamic PDF files that are generated from either the HTML-based page or manual that you are viewing. Links that normally allow this functionality have been hidden, and will reappear as soon as the feature is restored.


Note: Access to static files, including PDF files that are not dynamically generated from our web-based content, is unaffected.

Jump to: navigation, search

max_queued_callbacks_per_service

Section: callback
Default Value: 1000
Valid Values: Any integer
Changes Take Effect: Immediately


Added in 8.5.108.02
Maximum number of queued callbacks per service, if the option is not overridden in the callback service. Note that this option will not reject scheduled callbacks and applies only to immediate callbacks.

_max_queued_callbacks_per_service

Section: Queue Management
Default Value: 1000
Valid Values: integer
Changes Take Effect: Immediately
Introduced: 8.5.108.02

Maximum number of queued callbacks per service. By default, this limit is set to 1000.

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.

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.

_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

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

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

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

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

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

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

_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.104, 8.5.108, 8.5.109, 8.5.110, 8.5.111

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.

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.

FAIL_LOAD_MESSAGE_FILE

Callback Service cannot load the strings resource file specified in the _notification_message_file option.

CANCELLED

Callback Service received a cancel request for this callback.

NOT_AVAILABLE

Callback Service exited with no specified reason.

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.

AGENT_CONNECTED

Callback Service successfully routed the interaction to the agent.

AM_CONNECTED

Callback Service successfully routed the interaction to the answering machine.

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_ERROR

Callback Service failed due to an unknown error.

FAIL_TIMEOUT_TTL

Callback Service did not manage to handle the request in the specified time (_ttl).

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_NO_CUSTOMER_NUMBER

Customer number is missing.

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_QUEUEING

The Callback request could not be queued. This error may happen when an error occurs while requesting the route delay to URS.

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.

AGENT_PREVIEW_CANCEL_AFTER_<n>REJECTS

The agent rejected the request '<n>' times.

FAIL_CALL_TO_CUSTOMER

Replaces FAIL_USER_UNREACHABLE since GMS 8.5.102.14. Callback Service could not connect the customer.

FAIL_INCORRECT_CONFIG_MEDIA_TYPE

The _media_type option is set to an incorrect value. Callback Service only processes voice and chat interactions.

FAIL_FAX_REACHED

Callback Service could not connect the customer. The provided number was answered by a fax machine.

SUBMIT_ERROR

GMS did not manage to submit the Callback service request to Orchestration Server for processing.

FAIL_USER_UNREACHABLE

Reported as FAIL_CALL_TO_CUSTOMER prior to GMS 8.5.102.14.

List of API Queries

Start-Callback

Start-Callback initiates a callback request. It validates the request by doing the following:

  • Checks parameters, in general (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.

Start-Callback Operation

POST /genesys/1/service/callback/{callback-execution-name}
Name Type Mandatory Description
URI Parameters
{callback-execution-name} string yes Name of the callback execution service provisioned in GMS.
Body (JSON content)
_customer_number string yes 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.

_desired_time string no 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))


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.

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

<property> string no 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 no 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 no Queue to use for this callback if several virtual queues are used for callback with identical configuration.
_request_queue_time_stat string no 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.

Response

HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
_id string yes The service id for which a successful callback request was registered.

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

Cancel-Callback Operation

DELETE /genesys/1/service/callback/{callback-execution-name}/{service_id}
URI Parameters
Name Type Mandatory Description
{service_id} string yes This is the service id returned from the initial start callback response.
{callback-execution-name} string yes This is the name of the callback execution service of 'ors' type that is provisioned in GMS.
discard_ors_failure boolean no False by default. If true, GMS can bypass ORS failures and marks the cancellation of the callback.

You should 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.

Response

HTTP code 200
HTTP message OK

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.

Reschedule-Callback Operation

PUT /genesys/1/service/callback/{callback-execution-name}/{service_id}
Name Type Mandatory Description
URI Parameters
{service_id} string yes The service id returned from initial start callback response.
{callback-execution-name} string yes The name of the Callback execution service of 'ors' type that is provisioned in GMS.
Body (JSON content)
_new_desired_time string no 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 no Possible values are SCHEDULED, QUEUED, ROUTING, PROCESSING, COMPLETED.

Note: The _callback_state is incompatible with the _new_desired_time property.

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

Response

HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
See example. string yes
  • If accepted, none.
  • If not, a list of possible times around the desired_time.

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

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 and filter-keys options at the GMS application level.


Query-Callback Operation

  • GET /genesys/1/service/callback/{callback-execution-name}?{property=value}
  • GET /genesys/1/service/callback?{property=value}
Name Type Mandatory Description
URI Parameters
{callback-execution-name} string no
since 8.5.101.03
The name of the callback execution service of 'ors' type that is provisioned in GMS.
{property=value} string yes This is a property name used to query the callback.

Several properties may be specified.

operand string no Possible values are AND or OR. Default is AND.

When multiple properties are provided, specifies which operation to perform on matched Callback requests:

  • AND means all properties must match;
  • OR means any property can match.
_callback_state

Since 8.5.101.03

string no

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 no

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 no

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

Response

HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
See example. string yes
  • If accepted, a list of service ids of the currently outstanding callback requests.
  • If not, an error code indicating the reason.

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/<service-name>/availability (v1)
Name Type Mandatory Description
Body
start date no 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 no Alias to start parameter; kept for compatibility reasons.
number-of-days integer no 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 no 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 no 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.

Request example:

GET http://localhost:8080/genesys/1/service/callback/Callback_VQ
/availability?start=2014-12-03T15:00:00.000Z&number-of-days=2


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.
{
    // 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/<service-name>/availability
Name Type Mandatory Description
Body
start date no 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 no 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 no 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 no 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 no 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 no 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 no Timezone for the start and end date parameters. Additionally, the response object will return the localTime fields formatted in this timezone.
report-busy boolean no True to include in the response the slots where the office is open and where callbacks are booked to full capacity. By default, report-busy is false.
Body None.


REST Response

The response returns multiple values that describe the slots, availability, and capacity for a given slot.

The response object consists of an 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.

The following values are reported for every individual slot: "utcTime", "localTime", "capacity", "total".

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


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.
GET /genesys/1/admin/callback/queues?target={target_name}&end_time={iso_end_time}
Name Type Mandatory Description
URI Parameters
{iso_end_time} string no This is the maximum time for which to query callback requests.

If not specified, requests that are due in next 24 hours are returned.

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

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

{target} string no This is the name of a callback execution service. If not specified, the queues for all services are returned. For example, BasicCallback.
{max} integer no This is the maximum number of requests to return for each queue.

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

Response
HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
See example. string yes If accepted, a tree list of target queues and requests.
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.
Important
You can use this API to ensure that you do not book more Callbacks than you have licenses for.

Operation

GET /genesys/1/admin/callback/watermarks?service_name={service_name}
GET /genesys/1/admin/callback/watermarks

Name Type Mandatory Description
URI Parameters
{service_name} string no 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 

Response

HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
See example string yes 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.

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


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.

Important
This API requires authentication (Supervisor Role).

Operation

POST /genesys/1/admin/callback/reportcancelled

Name Type Mandatory Description
BODY Parameters
callback_reason string yes The reason for the cancellation. For example, CANCELLED_BY_ADMIN.
exported_properties string no 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)
Name Type Mandatory Description
See example string yes CSV-formatted results.

Errors

HTTP code 400
HTTP message Callback reason is missing.
HTTP code 204
HTTP message No record found.

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

Sample Errors

Throttling Exceptions

Added in: 8.5.111

Throttling exceptions are returned as JSON objects:

{
    "exception": "com.genesyslab.gsg.services.callback.exceptions.CallbackExceptionAlreadyBooked",
    "code": 40001,
    "phrase": "ALREADY_BOOKED",
    "message": "There is already 2 or more Callbacks QUEUED for this number, please refer to _enable_in_queue_checking for detail."
}


Exception Name HTTP Code (Header) Error Code (JSON body) Error Phrase (JSON body) Message Example (JSON body)
CallbackExceptionAlreadyBooked 429 40001 ALREADY_BOOKED There is already 1 or more Callbacks QUEUED for this number, please refer to _enable_in_queue_checking for detail.

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

CallbackExceptionThrottled 429 40002 SERVICE_LIMIT_REACHED Limit of queued callbacks for ServiceName is reached for interval 300s.
CallbackExceptionThrottled 429 40003 TODAY_LIMIT_REACHED Callback for _customer_number rejected because previous callbacks for this parameter were requested for more than 8 times today.

Maximum number of queued callbacks is exceeded

Added in: 8.5.108

You can set a limit for the number of queued callbacks by setting the _max_queued_callbacks_per_service option in your callback service, or by setting the max_queued_callbacks_per_service option in your GMS application.

By default, this limit is set to 1000. If this limit is exceeded, you will receive the following error:

POST http://localhost:8080/genesys/1/service/callback/cb_gms-imm?_customer_number=5115

response: 429 429
{ "exception": 
    "com.genesyslab.gsg.services.callback.exceptions.CallbackExceptionThrottled", 
    "code": 40002, "phrase": "SERVICE_LIMIT_REACHED", 
     "message": "Limit of queued callbacks for cb_gms-4709-imm is reached." }

Number Exceptions

{
      "message": "Customer Number [12345] is not allowed. 
Check option 'exceptions' :  details={Callback_exceptions=exception2}",
      "exception": "com.genesyslab.gsg.services.callback
.CallbackServiceException"
}

Business Hours Exceptions

{
  "message": "{"status":"closed",
  "reason":"closed_day_of_week"}",
  "exception": "com.genesyslab.gsg.services
.callback.CallbackServiceException"
}
{
  "message": "{"status":"closed",
  "reason":"closed_no_match"}",
  "exception": "com.genesyslab.gsg.services
.callback.CallbackServiceException"
}

Queue Full Exceptions

{
  "message": "Too many requests around this desired time :
  2013-05-24T18:03:29.952Z",
  "exception": "com.genesyslab.gsg.services
.callback.CallbackServiceException"
}
{
  "message": "Too many requests at desired time [2013-05-28T15:30:00.000Z, 
  2013-05-28T15:45:00.000Z]. Proposing time slots.",
  "exception": "com.genesyslab.gsg.services.callback
  .CallbackAvailabilityException",
  "availability":
   {
     "2013-05-28T16:00:00.000Z": 4,
     "2013-05-28T16:45:00.000Z": 5,
     "2013-05-28T15:00:00.000Z": 5,
     "2013-05-28T15:45:00.000Z": 5,
     "2013-05-28T15:15:00.000Z": 5,
     "2013-05-28T16:30:00.000Z": 5,
     "2013-05-28T16:15:00.000Z": 5
   }
}

Requested Slot is Unavailable

POST /genesys/1/service/callback/samples HTTP/1.1
Host: localhost:8080
Authorization: Basic ZGVtbzo=
Content-Type: application/json
Cache-Control: no-cache
{ "_customer_number": "5115", "usr_customer_name": "Bob Markel", "usr_reason": "billing question", "_device_notification_id": "b16416334828b1d26ef14f329628b55b5a8c631d8928a371a5584722dd7fb673", "_device_os": "comet", "_desired_time":"2016-02-17T10:25:00.000Z" }

Response:

{
"availability":
{ "2016-02-22T00:00:00.000Z": 100, "2016-02-22T00:05:00.000Z": 100, "2016-02-22T00:10:00.000Z": 100, "2016-02-22T00:15:00.000Z": 100, "2016-02-22T00:20:00.000Z": 100 }
,
"exception": "com.genesyslab.gsg.services.callback.exceptions.CallbackExceptionAvailability",
"message": "Office is closed at desired time slot [2016-02-17T10:25:00.000Z, 2016-02-17T10:30:00.000Z]. Proposing time slots."
}

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.

Feedback

Comment on this article:

blog comments powered by Disqus