Notification API

Overview

Note: This API should not be used from external mobile applications. It is designed and intended for use only from Orchestration Server-based Services. In release 8.1.100.28, comet was added as a notification subscription for device_os parameters.

This set of APIs is used to manage notifications between applications and Genesys systems. It is event driven. That is, consumers subscribe to an event and provide an indication of how the notification should be delivered, and events are published to the system. For the GSM, delayed use case, it could work as follows:

1. The mobile application would trigger a subscription for an ORS event; something like ors.contact.12345678; the application would specify the device id and the type (ie. iOS).
2. When ORS determines that an agent is available or will be available soon it will push a message to GMS with the event ors.contact.12345678.
3. GMS would push the message to the mobile device.

Structures

The following are the API data structures. All structures are in JSON format. The servlet expects JSON (consumes = "application/json"), so media type application/json is expected. It's absence or incorrect value can result in 415 (Unsupported Media Type) error.

subscription

The subscription data is used to identify the subscriber of the given set of events.

subscription request

{ "subscriberId":"${subscriberId}",
  "providerName":"${providerName}",
  "notificationDetails":{
    "deviceId":"${id}",
    "properties":
       {"${key2}":"${val2}",
        "debug":"${debug}",
        "${key1}":"${val1}"},
    "type":"${type}"},
   "expire":30,
   "filter":"${filter}"
}

Here:

• subscriberId– id of subscriber (mandatory)
• expire - this parameter defines the time in seconds after which the subscription expires (not mandatory, default value is configurable)
• filter - (mandatory) the filter which is applied to the tags of incoming events. If filter matches the tag - the event will be published to destination, specified by subscription. Note: event is published to ALL subscription which specify the matching filter. The format of filter see further.
• providerName – this is the name of the provider which this subscription is for (optional). If not specified, the subscription is for default provider.
• language - (optional) describes the language used by this subscription. if not present, GMS will treat localizedstring as a normal message. Please see Push Notification Service for details on language.
• notificationDetails - (mandatory) describes all the information needed for delivering the event to concrete subscriber
  • type - (mandatory) this parameter defines what type of notification mechanism that the application wants to use. Valid values are ios (to-apple), android (to-android-device), gcm (to-android-gcm-device), comet (to-cometd-client), httpcb (callback POST to provided url) and orscb (callback to ORS) (see more information here Push Notification Service).
  • deviceId - (mandatory), id of device to deliver message to (in the case of http or ORS callback - see the details here Push Notification Service
  • properties – (optional) the String-String map of properties – additional properties which can be needed for notification delivering. If the information provided is not enough for corresponding publisher – the error will be returned.
    • debug - this indicates if the production or debug provider connection is to be used to send the notifications. The subscription will be sent to debug channel if ${debug} value is debug or true.

Please note that notificationDetails.properties are not needed for android, gcm or ios or httpcb or orscb notifications - for them only the correct deviceId is required. Both notificationDetails.properties and deviceId is not needed for comet but gms_user header is required. For example, the request for android push notification subscription might look like this (please note absence of properties entry):

{"subscriberId":"$The_subscriber_9774",
 "notificationDetails":{
    "deviceId":"9774d56d682e549c",
    "type":"android"},
 "expire":30,
 "filter":"ors.context.123456"}

subscription response

If OK:

{"id":"${id}"}

- returns the ID of created subscription.

event

The events are published by internal Enterprise components. The Notification service matches the event to subscription using event's tag and subscriptions filters and notifies the subscriptions with matching filters. Event looks like this:

{
  "message":"${message}",
  "tag":"${tag}",
  "mediaType":"${mediaType}",
  "notificationDetails":
  {
    "deviceId":"${devideId}",
    "type":"${type}",
    "properties":
    {
     "debug":"{true/false}"
    }
  }
}

• tag – (mandatory) the message tag
• message– (optional) some string. It may contain string representation of ANY data: notification service is message-agnostic – it ALWAYS interprets message as String. If no message is specified – the empty string will be sent to subscribers. The only restriction on message format is: it must not crash the JSON parser which attempts to parse the request body. If this happens - the BAD_REQUEST response will be returned.
• mediaType - (optional) "string" for a simple string, "localizestring" for a string with localized parameter. see Genesys_Mobile_Services_Localization_File
• providerName - (optional) this is the name of the provider which this subscription is for (optional). If not specified, the subscription is for default provider.
• notificationDetails - (optional) if not present we send notification to default subscribers. It allows to send notification to a specific device.
• devideId - (mandatory) the id of the device (Android device id or IPad id for instance).
• type - (mandatory) type of the notification (gcm, ios...).
• properties - (optional).
• debug - (optional) allow to display debug log for this notification.

Filters and tags

Tag can not be null or empty string. The format of tag, specified in event, is like the java package name alphanumeric string with '.' delimiters. Underscores are allowed and first symbol may be number. Please note: at the moment only English alphanumeric chars are allowed. The filter can not be null or empty string. The format of filter entry is similar to the tag format, but in addition allowed wildcart ‘*’ after last ‘.’ (or only ‘*’ – denotes subscription to all events), the last char can not be '.'. So, the channels like the following are allowed:

• * - subscription to all channels
• ors.* - subscriptions to all channels starting with ors.
• ors.events.agentavailabilty.context.1234560 – subscription to the only 1 channel specified.

When publishing event - the tag is matched versus the filters of all active subscriptions and all matching subscriptions are notified (the best we can: push delivery is not 100% reliable). For example, consider the Notification Event published with tag ors.agentavailability.agent123.available. Such notification will be propagated to the subscriptions with any of following filters:

• *
• ors.*
• ors.agentavailability.*
• ors.agentavailability.agent123.*
• ors.agentavailability.agent123.available

APIs

The standard InternalServerError with code 500 or BAD_REQUEST with code 400 can be returned as response to each request, so it's not mentioned in further descriptions (except some cases when syntax of body is involved). NOTE: this API is intended for internal usage. NOTE: All POST request MUST specify media type application/json.

Create subscription

This allows an application to subscribe to a given set of events.

Operation

Method	POST
URL	/genesys/{api version}/notification/subscription
Parameter	Type	Mandatory	Description
URI Parameters
Body: JSON with subscription (see above)

Response

A JSON object with the property id, identifying the assigned id for this storage request.

HTTP code	200
HTTP message	OK

In the case of incorrect request syntax (see requirements above) the BAD_REQUEST error will be returned.

HTTP code	400
HTTP message	BAD REQUEST

If the subscription is being created for the push type which is not enabled at the moment, the NOT_FOUND error will be returned.

HTTP code	404
HTTP message	NOT FOUND

Delete subscription

This call cancels/terminates a given subscription.

Operation

Method	DELETE
URL	/genesys/{api version}/notification/subscription/{subscription-id}
Parameter	Type	Mandatory	Description
URI Parameters
{subscription-id}	String	yes	the id of the subscription to cancel

Returns

Nothing

HTTP code	200
HTTP message	OK

Delete subscription for given subscriber

This call cancels/terminates all subscription for a given subscriber.

Operation

Method	DELETE
URL	/genesys/{api version}/notification/subscription/subscriber/{subscriberId}
Parameter	Type	Mandatory	Description
URI Parameters
{subscriberId}	String	yes	the id of the subscriber whose subscriptions will be cancelled

Returns

Nothing

HTTP code	200
HTTP message	OK

Publish event

This allows an application to publish event (for internal usage only!).

Operation

Method	POST
URL	/genesys/{api version}/notification/publish
Parameter	Type	Mandatory	Description
URI Parameters
Body: JSON with event(see above)

Response

Nothing

HTTP code	200
HTTP message	OK

In the case of incorrect request body syntax (see requirements above) the BAD_REQUEST error will be returned.

HTTP code	400
HTTP message	BAD REQUEST

In the case if error happened during notification publishing (http post to specified url failed or returned not 200, some network troubles, APNS or C2DM services reported some error (authorization problems, temporary service unavailability for C2DM, e.t.c.) the SERVICE_UNAVAILABLE error will be returned.

HTTP code	503
HTTP message	SERVICE UNAVAILABLE

For more details please see Push Notification Service

Configuration

Configuring Genesys Mobile Services

Links

Push Notification Service