Jump to: navigation, search

Notification API

Overview

Important.png 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 GMS delayed use case, it can work as follows:

  1. The mobile application triggers a subscription for an ORS event; something like ors.contact.12345678; the application specifies the device id and the type (for example, iOS).
  2. When ORS determines that an agent is available, or will soon be available, it will push a message to GMS with the event ors.contact.12345678.
  3. GMS pushes 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. Its absence or incorrect value can result in a 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 – The id of subscriber (mandatory).
  • expire - This parameter defines the time, in seconds, after which the subscription expires (optional; 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. See Genesys Mobile Services 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 PushNotificationService.
    • properties – (Optional) The String-String map of properties – additional properties that can be needed for notification delivering. If the information provided is not enough for corresponding publisher, an 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.

Note: The notificationDetails.properties are not needed for android, gcm or ios or httpcb or orscb notifications - 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 (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 - a BAD_REQUEST response will be returned.
  • mediaType - (optional) "string" for a simple string, "localizestring" for a string with localized parameter. See Localization File.
  • providerName - (optional) This is the name of the provider that this subscription is for. If not specified, the subscription is for the default provider.
  • notificationDetails - (optional) If not present, notification is sent to default subscribers. It allows sending the notification to a specific device.
  • devideId - (mandatory) The id of the device (for example, Android device id or iPad id).
  • type - (mandatory) Yype of the notification (gcm, ios...).
  • properties - (optional).
  • debug - (optional) Allows the display of the debug log for this notification.

Filters and Tags

The tag cannot be null or an 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 is not mentioned in further descriptions (except some cases when syntax of body is involved). Notes: this API is intended for internal usage. All POST requests 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
This page was last modified on August 20, 2018, at 07:02.

Feedback

Comment on this article:

blog comments powered by Disqus