Jump to: navigation, search

Callback Services API

Overview

The URI parameter, {callback-execution-name}, is required for all of the Callback APIs. The value for this parameter equals the name of a Callback service configured in your GMS application or cluster. For example, if you have a section "service.sales_callback" of type Callback configured, the {callback-execution-name} will be equal to "sales_callback".

API

Start-Callback

The Start-Callback API 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 This is the name of the callback execution service of 'ors' type that is provisioned in GMS.
Body (JSON content)
_customer_number string yes This is the number to call back.
_desired_time string no This is the desired time to have the callback.
Format is ISO 8601 "yyyy-MM-ddTHH:mm:ss.SSSZ"
for example: "2013-05-28T15:30:00.000Z"
<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.
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 service, by doing the following:

  • Validates that the request is still in the scheduling queue.
    • If not, returns the appropriate error.
    • If valid, removes the request from the scheduling queue.


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

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


Description Reschedule-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 yes The new time for which to reschedule the callback.
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 

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


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

Query-Callback

The Query-Callback API queries the current set of outstanding callback services associated with a given property.

Important: Currently, only "customer_number" is indexed.


Description Query-Callback
Method GET
URL http://host:port/{base-web-application}/service/callback/{callback-execution-name}?{property=value}
Name Type Mandatory Description
URI Parameters
{callback-execution-name} string yes This is the name of the callback execution service of 'ors' type that is provisioned in GMS.
{property=value} string yes This is the property name used to query the callback.

Important.png Currently, the only property to search is by "customer_number".

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",
          "url": "/1/service/callback/BasicCallback/a550a12e-ca77-4146-98d0-58960e0939f7"
      },
      {
          "_id": "4a1ea889-1ef7-432d-a543-cff96b4a2daf",
          "desired_time": "2013-05-27T15:10:00.000Z",
          "url": "/1/service/callback/BasicCallback/4a1ea889-1ef7-432d-a543-cff96b4a2daf"
      }
   ]

Query-Availability

By specifying a desired time, the client can check if an office is open, and if open, if there is available time slot.

Options:

  • business_hours: to match office open/close slots
  • request-time-bucket: the bucket size returned
  • max-request-by-time-bucket


Description Query-Availability
Method GET
URL http://host:port/{base-web-application}/service/callback/{callback-execution-name}/availability?{timestamp=value}
Name Type Mandatory Description
URI Parameters
{callback-execution-name} string yes This is the name of the callback execution service of 'ors' type that is provisioned in GMS.
{timestamp=value} string no This is the desired time to have the callback.
Format is ISO 8601 "yyyy-MM-ddTHH:mm:ss.SSSZ"
For example: "2013-05-28T15:30:00.000Z"
Body (JSON content)
Response Body (JSON content)
Name Type Mandatory Description
See example. string yes
  • If accepted, a list of available slots with remaining possible requests.
  • If not, an error code indicating the reason.
HTTP code 200
HTTP message OK


Example Operations 

GET http://localhost:8080/genesys/1/service/callback/BasicCallback/availability?timestamp=2013-06-15T09:00:00.000Z
Results success:
   200 OK
   {
      "2013-06-15T08:00:00.000Z": 5,
      "2013-06-15T09:45:00.000Z": 5,
      "2013-06-15T09:00:00.000Z": 4,
      "2013-06-15T08:30:00.000Z": 5,
      "2013-06-15T08:45:00.000Z": 5,
      "2013-06-15T09:15:00.000Z": 4,
      "2013-06-15T08:15:00.000Z": 5,
      "2013-06-15T09:30:00.000Z": 5
   }
GET http://localhost:8080/genesys/1/service/callback/BasicCallback/availability?timestamp=2013-06-15T12:00:00.000Z
Results error:
   400 BAD REQUEST
   {
      "message": "Office is closed at 2013-06-15T12:00:00.000Z. No time slots proposed.",
      "exception": "com.genesyslab.gsg.services.callback.CallbackExceptionAvailability",
      "availability":
      {
      }
   }

ADMIN - Query-Callback

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


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",
              "_desired_time": "2013-06-07T16:25:00.000Z",
              "_id": "fd30abb97bd04885b544893276fb534b",
              "url": "/1/service/callback/BasicCallback/fd30abb97bd04885b544893276fb534b"
          }
      ],
      "AdvancedCallback":
      [
          {
              "_customer_number": "654321",
              "_desired_time": "2013-06-07T16:25:00.000Z",
              "_id": "07d2ddd506f04b4ba91aba59c4fa8871",
              "url": "/1/service/callback/AdvancedCallback/07d2ddd506f04b4ba91aba59c4fa8871"
          },
          {
              "_customer_number": "654321",
              "_desired_time": "2013-06-07T16:25: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 January 27, 2016, at 13:54.
Comments or questions about this documentation? Contact us for support!