Callback Services API

Modified in: 8.5.2

Getting Started

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

Accessing your Callback Service

The URLs used by the Callback API are dependent on the execution name of the Callback service that you have just created. Callback services are available at the following URL:

http://<host>:<port>/genesys/1/service/callback/{callback-execution-name}

For instance, if you create a callback service named callback-for-mobile, then {callback-execution-name} is callback-for-mobile, its configuration in GMS is located in the service.callback-for-mobile section, and you can access the callback service at the following URL:

http://<host>:<port>/genesys/1/service/callback/callback-for-mobile

Overwriting Configuration in Queries

To overwrite service configuration parameters in your POST REST queries (Start-Callback), use the _overwritable_options option. This option lets you define a list of overwritable parameters that you will be able to pass in the Body of your REST request.

Important

This list can include the _ors and _target options only.

For example, if you set:

_overwritable_options = _ors,_target

Then, you can pass _ors and _target in your REST query:

POST /1/service/callback/callback-for-mobile
{
     "_ors": "http://myors:4421",
    "_target": Billing@Stat_Server1.GA
}

Passing Configuration Tokens in Queries

Added in: 8.5.104

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

To create a token variable, create a new service parameter and configure its value with a string matching the following format: $<any-token-name>$

For instance, create:

my_token_name = $my_token$

Then, you can use the body parameter my_token=<anyvalue> in your REST queries. As a result, the occurrences of $my_token$ in this service configuration will be replaced with the query's provided value.

For example, if you wish to create a callback request for the CLBCK-terminated-preview service using the Stat_Server1 server target, use the following query:

POST /genesys/1/service/callback/CLBCK-terminated-preview
HTTP/1.1
Host: 127.0.0.1:8080
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.

Callback states	While in ORS	Description
PROCESSING		The customer is connected to an agent and talking with this agent.
QUEUED		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		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		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

The Callback Services API provides the following REST queries:

• Start or Schedule Callback–Initiate a Callback request.
• Cancel-Callback–Cancel a Callback request.
• Delete-Callback–Delete a Callback request.
• Reschedule-Callback–Reschedule a Callback request.
• Query-Availability—Get the availability for a new callback request.
• Query-Callback-By-Id–Query a callback by its ID.
• Query-Callback by Lookup Properties—Query outstanding callbacks by lookup properties.
• Query-Callback by Queue(s)—Query outstanding callbacks by queue(s).
• Query Counter Watermarks—Query the current set of executed callback instances in queues.
• Export Callback Records—Export Callback records.

Important

The documentation for "Query-EWT for Virtual Queues" was moved to the Stat Service API page.

Start or Schedule Callback

Initiates a callback request. It validates the request by doing the following:

• Checks parameters, in general (in particular, if the target queue is valid).
• Checks the customer number against exceptions.
• Checks the time criteria of the request against the business.
  • If invalid:
    • Returns the appropriate error.
    • Sends a reporting event to the GMS data manager indicating that the callback request has been rejected.
  • If valid:
    • Creates a unique ID for the request.
    • Sends a reporting event to the GMS data manager indicating that the callback request has been accepted and started.

      This event also indicates the state of the request (immediate or scheduled).

    • If the request needs to be scheduled for a later date/time, the request and its associated data will be stored in the module persistent data storage.
    • If the request can be started now, an ORS session is initiated using the associated SCXML-based service with this particular callback request.

      Note: the provisioned data for the execution service to be started will be used as input along with the input parameters from the request itself.

    • Returns the ID generated for this request.

Starting in 8.5.2, you can redial a COMPLETED callback by submitting the callback ID to create a copy of this callback. The properties and user data of the copied callback are merged with the parameters of the new callback submitted in the POST query.

• The parameters specified in the POST query override the copied properties.
• Internal retry flags and properties such as _callback_state, _ors_session_id, _desired_time will be ignored when creating the callback copy.

Tip

You can include any of the _xxx callback option parameters in your start query if they are not configured in the service; for example _target, _wait_for_agent, _paused_services_list, _paused_services_id, or any other _xxx parameter listed in the Callback Service Options Reference Guide. If the option is already configured in the service, the query parameter's value is ignored and the service option value is used. See Overwriting Configuration in queries to learn about overwriting configuration in queries.

Important:

The _desired_time parameter is used together with service options to decide if a callback should be created for a later execution or the callback should be triggered as soon as the corresponding API request is processed.

The Callback will be IMMEDIATE based on the following rule:

immediate = _desired_time < {current_time} + {_request_execution_time_buffer} + {Estimated Wait Time} where, {Estimated Wait Time} is computed from either of following options (in priority): {_request_ewt_service} or {_request_queue_time_stat} or {_urs_ewt_vq} or {_urs_virtual_queue} or {_vq}.

Example 1:
Assuming current time is 16:15, and _desired_time is today at 17:05, _request_execution_time_buffer is 300 (5 mins), EWT is computed as 10 mins.
Then the Callback is SCHEDULED (not IMMEDIATE) and will be kept in the GMS queue to be submitted later for execution because:
immediate = (17:05 < 16:15 (now) + 5 min + 10 min)
immediate = (17:05 < 16:30)
immediate = false

Example 2:
Assuming current time is 13:10, _desired_time is today at 13:15, _request_execution_time_buffer is 120 (2 mins), EWT is computed as 5 mins.
Then the Callback is IMMEDIATE and is submitted for execution upon API request creation because:
immediate = (13:15 < 13:10 (now) + 2 min + 5 min)
immediate = (13:15 < 13:17)
immediate = true

When used together with Office Hours, note that the _enable_reject_out_of_office_hours option allows to accept or reject callbacks taking into account the statistics.

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"
<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. The key must be a valid ECMAScript variable name. This means that variable semantics that include elements like "." (for example, foo.foo) and "-" (for example, foo-foo) are not allowed.
_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	"Customer Number is not allowed, because it is invalid. Check option "Customer Number is not allowed, because it is invalid. Check option _disallow_impossible_phone_numbers" "Customer Number is not allowed, because it's a premium number. Check option _disallow_premium_phone_numbers" "Customer Number is not allowed, because it failed validating. Check option _disallow_impossible_phone_numbers" "Customer Number is not allowed. Check option _exceptions"
exception	com.genesyslab.gsg.services.callback.CallbackExceptionNumber
properties

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	"Customer Number is not allowed, because it is invalid. Check option "Customer Number is not allowed, because it is invalid. Check option _disallow_impossible_phone_numbers" "Customer Number is not allowed, because it's a premium number. Check option _disallow_premium_phone_numbers" "Customer Number is not allowed, because it failed validating. Check option _disallow_impossible_phone_numbers" "Customer Number is not allowed. Check option _exceptions"
exception	com.genesyslab.gsg.services.callback.CallbackExceptionNumber
properties

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.

For a complete description, refer to the Callback Solution Guide.