Jump to: navigation, search

Callback Services API

Getting Started

When you add a callback service, you define a Service Name, which is referred 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>/{base-web-application}/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>/{base-web-application}/service/callback/callback-for-mobile

Overwriting Configuration in Queries

You can create variables in your configuration parameters, then overwrite the current configuration by setting these variables in your queries.

Tip
You should use this feature to avoid duplicating configuration for multiple services that handle the same functionality but use different queues.

To create a variable, all you need to do is to specify a string matching the following format in your service configuration: $my_variable$.

Then, you can use the parameter my_variable=MYVALUE in your REST queries; any occurrence of $my_variable$ in this service will be replaced with this value.


Callback-vqname.png

2

For instance, you can create the _vq_name parameter in the callback-for-mobile service and sets its value to the $vq_name_token$ variable or use $vq_name_token$ in your service configuration.

Then, if you wish to create a callback request for the callback-for-mobile service using the MYVQNAMEVALUE queue, you should use the following query: 

POST /genesys/1/service/callback/callback-for-mobile
HTTP/1.1
Host: 127.0.0.1:8080
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
_customer_number=01822256&vq_name_token=MYVQNAMEVALUE

When GMS receives the query information, it uses vq_name_token = MYVQNAMEVALUE instead of the default configuration set for callback-for-mobile.


List of API Queries

The Callback Services API provides the following REST 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.


Description Start-Callback
Method POST
URL http://<host>:<port>/{base-web-application}/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.
Format is ISO 8601 "yyyy-MM-ddTHH:mm:ss.SSSZ"
For example: "2013-05-28T15:30:00.000Z"
Default is current time.


Note that 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))

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 this option is set, it always overwrites the parameter.
Response Body (JSON content)
Name Type Mandatory Description
_id string yes The service id for which a successful callback request was registered.
HTTP code 200
HTTP message OK


Example Operation 

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 immediate/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 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.
Description Cancel-Callback
Method DELETE
URL http://host:port/{base-web-application}/service/callback/{callback-execution-name}/{service_id}
Name Type Mandatory Description
URI Parameters
{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.
Body (JSON content)
Response Body (JSON content)
Name Type Mandatory Description
HTTP code 200
HTTP message OK


Example Operation 

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

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.


Description Update-Callback
Method PUT
URL http://host:port/{base-web-application}/service/callback/{callback-execution-name}/{service_id}
Name Type Mandatory Description
URI Parameters
{service_id} string yes This is the service id returned from 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.
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: The request is handled by the Callback Management service (there are no sessions started in ORS). While in this state, the request will be handled by Management when the specified desired_time is approaching.
  • QUEUED: Callbacks actively waiting for an agent in ORS/URS; agent is not assigned yet.
  • ROUTING - Agent is reserved but the call is not yet routed to the agent.
  • PROCESSING: The Callback is being handled by the assigned agents.
  • COMPLETED: The Callback was completed with _callback_reason; for example, timed-out, cancelled, and so on.

Note: The _callback_state is incompatible with the _new_desired_time property.

<other properties> any no Properties to be updated in request.
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.
HTTP code 200
HTTP message OK


Example: Operation Successful

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

Example: 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 typicaly 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

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 service option _customer_lookup_keys.
Description Query-Callback
Method GET
URL
  • http://host:port/{base-web-application}/service/callback/{callback-execution-name}?{property=value}
  • GET http://host:port/{base-web-application}/service/callback?{property=value}
Name Type Mandatory Description
URI Parameters
{callback-execution-name} string no
since 8.5.101.03 		This is 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:

  • Intermediate states:
    • PROCESSING</tt:> Customer is connected to an agent and talking with this agent.
    • QUEUED: Callback request has been submitted to the callback Queue.
    • SCHEDULED: Callback request is scheduled.
    • ROUTING: Customer phone is reached and waiting for an agent.
  • Final state: COMPLETED: The call is done.
    • Reason FAIL_LOAD_MESSAGE_FILE: Callback Service cannot load the strings resource file.
    • Reason CANCELLED: Callback Service received a cancel request for this callback.
    • Reason NOT_AVAILABLE: Callback Service exited with no specified reason.
    • Reason FAIL_INTERACTION_DELETED: The callback interaction was deleted prior to routing the interaction to the agent.
    • Reason AGENT_CONNECTED: Callback Service successfully routed the interaction to the agent.
    • Reason FAIL_TARGET_NOT_FOUND: Callback Service cannot reserve the requested target to handle the request.
    • Reason FAIL_ERROR: Callback Service failed due to an unknown error.
    • Reason FAIL_TIMEOUT_TTL: Callback Service did not manage to handle the request in the specified time (_ttl).
    • Reason 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.
    • Reason FAIL_NO_CUSTOMER_NUMBER: Customer number is missing.
    • Reason 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.
    • Reason FAIL_QUEUEING: The callback request could not be queued.
    • Reason FAIL_AGENT_CONNECT: The callback interaction could not be connected to the agent.
    • Reason AGENT_PREVIEW_CANCEL_AFTER_<n>REJECTS: The agent rejected the request '<n>' times.
    • Reason FAIL_CALL_TO_CUSTOMER: Replaces FAIL_USER_UNREACHABLE since GMS 8.5.102.14. Callback Service could not connect the customer.
    • Reason FAIL_INCORRECT_CONFIG_MEDIA_TYPE: The _media_type option is set to an incorrect value.Callback Service only processes voice and chat interactions.
    • Reason FAIL_FAX_REACHED: Callback Service could not connect the customer. The provided number was answered by a fax machine.
    • Reason SUBMIT_ERROR: GMS did not manage to submit the callback service request to Orchestration Server for processing.
    • Reason FAIL_USER_UNREACHABLE: Reported as FAIL_CALL_TO_CUSTOMER prior to GMS 8.5.102.14.
_desired_time_from

Since 8.5.101.03

string no

Specifies ISO timestamps. All callback matching lookup properties and 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 and scheduled after this time will be filtered out. (warning)


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


Example Operation 

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

Description Availability REST Request
Method GET
URL /genesys/1/service/callback/<service-name>/availability
Name Type Mandatory Description
URI Parameters
None.
Body
start date no Start date is specified in ISO 8601 format, using UTC as 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 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 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 performance of the query over a lengthy period of time.
Response Body
See example below.

Request example: 

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. In the same manner 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 capacity is full (for example, zero) are not provided in the response. In a similar way, 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"
}


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.

ADMIN - Query-Callback

The Query-Callback API queries the current set of outstanding Callback services in given queue(s).

Important
Outstanding Callback services are requested if their _callback_state is one of the following values: SCHEDULED, QUEUED, ROUTING, PROCESSING, COMPLETED.
Description Query-Callback
Method GET
URL http://host:port/{base-web-application}/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 maximum number of requests to return for each queue.

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

Body (JSON content)
Response Body (JSON content)
Name Type Mandatory Description
See example. string yes If accepted, a tree list of target queues and requests.
HTTP code 200
HTTP message OK


Example Operation 

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

Sample Errors

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
      }
   }
This page was last edited on November 24, 2017, at 09:41.
Comments or questions about this documentation? Contact us for support!