Calendar Service API

Overview

The Calendar Service API queries for all office hours so that your mobile app can make an intelligent first offer to the user based on what's available in the next couple days, or with an explanatory hint such as "Our offices are open from 8:00 am to 5:00 pm, please enter the desired time.".

The calendar service API is intended to be tight to your office hours. It lets you handle the following use cases.

• Find whether the office is open at the time of the query.
  • If you call the API without any parameters, the start and end parameters are assumed to be now.
  • Check in the response that the field error is null. If the list of periods is empty, it means that the office is closed, otherwise, the office is open.
• Find the office's schedule for a given period.
  • If you call the API and set the number-of-days-ahead_days parameter to 5, the start date is assumed to be now. The response should contain any periods when the office is open.

Configuration

To configure office hours, create and configure an Office Hours service using the Service Management UI, as detailed in the Help.

Be sure to update the existing calendar configuration to set the correct timezone for your business-hours service. For instance, if you configured "EST", or "PST" timezones with the Genesys Administrator Extension, your parameters must use the timezones defined for Java such as, "America/Toronto" or "Europe/Paris". See Wikipedia list of correct timezones.

A complete list of options is available in the [office-hours] section of the Genesys Mobile Services Options Reference guide.

REST API

The Calendar Service REST query retrieves the office hours per day for a provided period.

Calendar Service REST Request

GET /genesys/1/service/{service-execution-name}
Parameter	Type	Mandatory	Description
Body
start	Date	no	Start date is specified in "ISO 8601" format, using UTC as timezone: "YYYY-MM-ddTHH:mm:ssZ". If not specified then it is assumed to be now.
number-of-days	integer	no	Specifies how many days ahead to include into interval beginning form the "start" time. Used as an alternative to the end date. If neither "end", nor "number-of-days" is specified, then 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:ssZ". If neither "end", nor "number-of-days" is specified, then end date is assumed to be the same as start date.

Important

Other options from configuration section can be specified in the request.

Request example: GET http://127.0.0.1:8080/genesys/1/service/business-hours?start=2014-12-03T15:00:00.000Z&number-of-days=2

Calendar Service REST Response

The Calendar service returns an array of periods ordered in ascending chronological order.

• If the array is empty then there are no calendar events for the specified duration.
• If an error occurs while processing the request then the string error is specified in the "error" data field, the contents of periods array, in that case, are undefined.
• Additional calendar information such as agent availability is returned in tags data field as a key-value map.
• The open_for property reports how long the office will stay open in hours and minutes. Its format is "hh:mm". Note that the value of the open_for property does not depend on any of the input parameters. It returns the duration between the time at which the request was issued and the office closing time. If the office is closed, then open_for = "00:00".

> GET /genesys/1/service/business-hours?start=2016-10-05T15:00:00.000Z&number-of-days=2 HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/7.50.3
> Accept: */*
>
< HTTP/1.1 200 OK
< Set-Cookie: JSESSIONID=1wftsntzmfydfybt0v75gbprp;Path=/genesys;HttpOnly
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
<
{
  "error": null,
  "open_for": "11:20",
  "periods": [
    {
      "start": "2016-10-05T15:00:00.000Z",
      "end": "2016-10-05T21:00:00.000Z"
    },
    {
      "start": "2016-10-05T23:00:00.000Z",
      "end": "2016-10-06T21:00:00.000Z"
    },
    {
      "start": "2016-10-06T23:00:00.000Z",
      "end": "2016-10-07T15:00:00.000Z"
    }
  ]
}