Notifications: Subscription API

Subscription

RingCentral provides the ability to subscribe for event data using PubNub.

Create Subscription

About Pubnub SSL

Pubnub supports SSL. But we are not taking advantages of it. Before publishing data to Pubnub, we do encryption on our server side. And this SDK is responsible for decryption of data automatically. Users of this SDK don't need to do anything to enable SSL, still can be assured that data is being protected by encryption.

In the future, we might switch to Pubnub SSL. And it won't affect SDK users since we will keep the API identical.

Sample code

var subscription = sdk.CreateSubscription();
subscription.EventFilters.Add("/restapi/v1.0/account/~/extension/~/message-store");
subscription.EventFilters.Add("/restapi/v1.0/account/~/extension/~/presence");
subscription.ConnectEvent += (sender, args) => {
    Console.WriteLine("Connected:");
    Console.WriteLine(args.Message);
};
subscription.NotificationEvent += (sender, args) => {
    Console.WriteLine("Notification:");
    Console.WriteLine(args.Message);
};
subscription.ErrorEvent += (sender, args) => {
    Console.WriteLine("Error:");
    Console.WriteLine(args.Message);
};
subscription.Register();

Alternatively you can set Event Filters by:

subscription.EventFilters = listOfEvents;

Where listOfEvents is a List<string> containing each event to subscribe to.

Lifecyle management

Users of this SDK are responsible for managing the lifecyle of subscription. In order to keep it alive, you need to make sure that it will not be garbage collected. So most likely you want to make subscription a class variable instead of a local variable.

Casting SubscriptionEventArgs

Casting on Notification

args.Message is an object that can easily be cast to a string or a JArray/JObject (Json.Net). See below for examples of JSON data.**

Use a JObject to grab a token

public void ActionOnMessage(object sender, SubscriptionEventArgs args) {
    var message = ((JObject)args.Message).SelectToken("body.changes[0].type").ToString();
}

Or string for other JSON parsing

public void ActionOnMessage(object sender, SubscriptionEventArgs args) {
    var message = args.Message.ToString();
}

Casting on Connect

Use a JArray to grab a token.

public void ActionOnConnect(object sender, SubscriptionEventArgs args){
    var message = ((JArray)args.Message).SelectToken("[1]").ToString();
}

Or string for other JSON parsing

public void ActionOnConnect(object sender, SubscriptionEventArgs args) {
    var message = args.Message.ToString();
}

Casting on Error

Note: PubNub error messages are not deserializable JSON.

public void ActionOnError(object sender, SubscriptionEventArgs args) {
    var error = args.Message.ToString();
}

Example Notification Messages

message-store example:

{
  "uuid": "32a089d4-bd5d-4259-8db4-feed54e8dcd9",
  "event": "/restapi/v1.0/account/~/extension/850957020/message-store",
  "timestamp": "2016-05-30T03:18:22.424Z",
  "subscriptionId": "a4b70629-ac59-4a0c-a479-bf81c591df7c",
  "body": {
    "extensionId": 850957020,
    "lastUpdated": "2016-05-30T11:18:10.624+08:00",
    "changes": [
      {
        "type": "SMS",
        "newCount": 1,
        "updatedCount": 0
      }
    ]
  }
}

presence example:

{
  "uuid": "a78f2232-c627-48b8-9aa9-74a8adef63fa",
  "event": "/restapi/v1.0/account/~/extension/850957020/presence",
  "timestamp": "2016-05-30T03:18:42.184Z",
  "subscriptionId": "a4b70629-ac59-4a0c-a479-bf81c591df7c",
  "body": {
    "extensionId": 850957020,
    "telephonyStatus": "Ringing"
  }
}

Delete Subscription

subscription.Remove();

FAQ

How can I subscribe to all extensions

To subscribe to presence events for all extensions, create a set of event filters including filters for every extension, and then create a subscription including all the event filters. A presence event filter includes the accound id and extension id.

Here is an example of a single presence event filter using the account id for the authorized session

/restapi/v1.0/account/~/extension/111111/presence

A set of presence event filters looks like the following:

/restapi/v1.0/account/~/extension/111111/presence
/restapi/v1.0/account/~/extension/222222/presence

A full set of extension ids can be retrieved via the extension endpoint: /restapi/v1.0/account/~/extension. This has been tested with a single subscription API call and a set of over 2000 extensions.