555 Notification Guide


This document details steps required to setup and provision your mobile/webapp in 555 for notifications. It also enlists Notification Manager(NTM) APIs required to manage notification subscriptions, supported publish protocols and best practices.

NTM currently interfaces with FCM and APNs gateways for mobile notifications.
For web applications, notifications can either be delivered over WebSockets which require integration with the 555-RTC SDKs and a live connection to RTC-WebSocket (WSS) servers or applications can register WebHook callbacks also.


Provisioning apps in 555 for Notifications

Before an app can integrate with NTM, the app developer must undertake two necesssary steps to ensure that an app domain is provisioned for notifications:

  1. Enabling correct triggers for the app domain
  2. Setup of Push credentials (required for mobile notification only).

To enable notification triggers, log a ticket under Tools And Support -> Report a Problem section of the Developer portal.

555 Developer portal - Report a Problem Screenshot

The second step in the process is to upload Push credentials for mobile applications as detailed below. These credentials will be used by NTM to authenticate with APNs and FCM gateways and deliver push notifications.

1. Obtain APNs/FCM credentials

APNs Auth

For Apple Push Notification service (APNs), NTM supports both TLS auth using certificates as well as Token Auth using JWT tokens signed with developer's private key. Refer following guides on Apple Developer portal for details around how to obtain these credentials:

Depending on the chosen authentication scheme, app developer should have following handy:
{TeamID, keyID, privateKeyFile.p8} for TokenAuth and
{certificateFile.cer, privateKeyFile.p12} for TLS Auth.

FCM Auth

For Android apps, developers need to register their project in FireBase console and obtain a server key. Once the registration process is completed, app developer should have the server key handy for next step.

2. Configure credentials in 555 Portal

  • Login to 555 Developer portal and choose your app domain from Applications panel.
  • On the Application details pane, scroll to Notifications Tab and upload your FCM/APNs credentials.

555 portal - Notification Registration Screenshot

Notes:

  • APN token auth takes precedence over TLS auth. So if you uploaded both TLS certificates AND credentials for Token Auth, NTM will use JWT tokens when talking to APNs.

  • For APNs TLS auth, the certificate and key MUST be converted to pem format using following commands:

$ openssl x509 -in cert.cer -inform DER -outform PEM -out apns-cert.pem
$ openssl pkcs12 -in key.p12 -out apns-key.pem -nodes

  • The Production toggle on this form controls if APNS sandbox or Production gateway is used for sending push messages. Typically, you would want this unchecked in your development/test environment.

  • The onus is on the application developer to generate correct credentials and upload them on developer portal. In case any of these credentials expire or get revoked, the application developer must upload renewed credentials.

Subscription Management

NTM implements a pure publish/subscribe pattern over arbitrary, app-managed topics. The data model consists of set of subscriber entities within an appdomain that subscribe to one or many notification topics called subscriptions. A subscriber is uniquely identified by the tuple {app_domain(555 application id), protocol (apns, fcm, xmpp, webn), push-token}. A subscription topic is an arbitrary string, managed by the app that defines an system event for which listeners are registered and the string on which publishes are made.

The following listing details Notification Manager APIs for creating and deleting subscribers and subscriptions.

1. Creating a subscriber

To create a subscriber in NTM, the following API is used:

    POST https://ntm.iris.comcast.net/v1/subscriber http/1.1  
    Content-Type: application/x-www-form-urlencoded  
    Authorization: Bearer <555_JWT_TOKEN>  
    proto=fcm&token=<FCM_TOKEN>&app_domain=555.myapp.domain

And the response will bear a subscriber Id :

   200 OK     
   Content-Type: application/json  
   "{\"id\":\"58a7508dc233c400001bff1a7\"}"

For detailed specification, refer NTM API reference.

Notes:

Subscribers can be created in NTM for one of the following protocols:

  • apns - These subscribers are identified using Apple issued device tokens and will get notified via APNs
  • fcm - subscribers identified using FCM issued device tokens and notified via Firebase cloud messaging
  • xmpp - these subscribers are identified by routingID and are notified over web-socket representing active RTC Connection.
  • webn - these are webhook based subscribers that will receive notification payload over HTTP POST

2. Creating subscriptions

After a subscriber is created, the subscriber must be registered for one or more topics. The create subscription API must be executed once per topic.

It is also important to note that Subscriptions are aged and allowed for a maximum of 15 days. Subscriptions older than 15 days are purged automatically by NTM and therefore, it is expected that applications will renew subscriptions periodically for active users.

POST /v1/subscription/subscriber/:id/topic/:topic

If the topic string was myapp/video, this is how a subscription request will look like for a an XMPP based subscriber with subscriberID=58177a7bb54b0f :

    POST  
    https://ntm.555.comcast.net/v1/subscription/subscriber/58177a7bb54b0f/topic/myapp%2fvideo
    Content-Type: application/json  
    Authorization: Bearer <555_JWT_TOKEN>

And for an APN subscriber with bundle ID my.awesome.app, and subscriberID=58177asbb54b0f, the same subscription request will look like following :

    POST https://ntm.555.comcast.net/v1/subscription/subscriber/58177asbb54b0f/topic/myapp%2fvideo   
    Content-Type: application/json  
    Authorization: Bearer <555_JWT_TOKEN>   
Request Body:
    {"apns_topic": "my.awesome.app"}

For detailed specification, refer NTM API reference.

Note For iOS clients only:

With the new HTTP2 interface and introduction of Universal certs, developers can now obtain one certificate that allows standard push, VoIP push and watchkit notifications in both Apple Sandbox and Production environments, if they desire so. Which means that the same cert can have more than one apn-topic in them. Therefore, when 555 NTM interfaces with APNs gateway using a Universal certificate, it needs to specify apn-topic in HTTP header so that Apple can make distinction between watchkit, pushKit or standard notification paths. The apn-topic needs to match one present in Universal certificate. You can view apn-topics contained with a certificate through Keychain access app. You should find one or more topics as follows:

  • app.bundle.id (standard notifications)
  • app.bundle.id.voip and (VoIP notifications delivered in background)
  • app.bundle.id.complication (Apple watch notifications)

You will need to specify this apn-topic in the body of subscription request.

3. Querying existing subscribers and subscriptions

NTM provides three APIs that allow an application or application server to query subscribers and subscriptions using subscriber ID and topic. These are detailed below:

Client API: Applications can retrieve subscriberID using the following NTM API-

GET /v2/subscriber/proto/:proto/token/:token

App Server APIs:

  • To retrieve a subscriber using subscriber ID use following API:

GET /v1/subscriber/:id

  • To retrieve a list of subscribers for a given topic using following API:

GET /v1/subscribers/topic/:topic

For detailed specification, refer NTM API reference.

4. Deleting Subscriber

When client wishes to stop listening for notifications, such as when user signs out of the app, the application can delete the subscriber thereby purging all subscriptions in one API call.

DELETE /v1/subscriber/:id

    DELETE https://ntm.iris.comcast.net/v1/subscriber/58177asbb54b0f http/1.1  
    Content-Type: application/x-www-form-urlencoded  
    Authorization: Bearer <555_JWT_TOKEN>

For detailed specification, refer NTM API reference.

4. Canceling Subscription

When a client wishes to unsubscribe from an event, such as when a user toggles notification OFF for lets say video call, client can DELETE the topic subscription using following API.

DELETE /v1/subscription/subscriber/:id/topic/:topic

    DELETE https://ntm.iris.comcast.net/v1/subscriber/58177asbb54b0f/topic/myapp%2fvideo  http/1.1  
    Content-Type: application/x-www-form-urlencoded  
    Authorization: Bearer <555_JWT_TOKEN>

For detailed specification, refer NTM API reference.

Publishes

There are two types of Publishes made by NTM:

  1. Independent publishes made by application servers outside the context of RTC session
  2. Publishes made in context of an RTC call session (Chat, PSTN, Video calls etc.). These events are generated and detected by 555 platform.

Independent Publishes (App-controlled)

Application servers can publish notifications to subscribers directly by invoking the following NTM API.

POST /v1/publish

Description

This API allows an external server to publish a Notification for a supplied topic. All the subscribers
with active subscriptions will be notified with the relayed payload.

- API Authentication
  - JWT signature verification
  - JWT claims expiration time validation
  - JWT claims type MUST be "server" only

- Content-Type associated with request payload MUST be *application/json*

Request

----------------------------------------------------------------------------------------------
Property        Type        Description
----------------------------------------------------------------------------------------------
topic           string      (MANDATORY) Subscription topic
data            JSON        (MANDATORY) The push message that will be passed as-is in the Notification
preferences     JSON        (Optional) This is an optional JSON that overrides the topic level Preferences.
                            and governs delivery QoS and message formatting for mobile notifications.

The Preferences structure controls delivery and message formatting parameters in APNs and FCM. Preferences are applied only for mobile notifications.

----------------------------------------------------------------------------------------------
Preference      Type        Description
----------------------------------------------------------------------------------------------
priority        string      (MANDATORY) Subscription topic
ttl             int         (MANDATORY) The push message that will be passed as-is in the Notification
silent          bool        Controls if notification is silent
badge           int         notification badge count
alert           string/JSON the alert field in aps dictionary
category        string      the notification category
sound           string      name of the sound file from application resource bundle

For detailed specification, refer NTM API reference.

555 Notification Publishes

For events such as incoming PSTN call, video call and chat, 555 platform will publish notifications to the subscribers. The topic for these events are managed by the app with the exception of PSTN calls. The topic for a PSTN call is always federation/pstn/<routingID>

555 provides flexibility to applications to control both the format of the notification payload and the topics to which publishes are made. Whenever an application creates an RTCSession through the 555-Rtc-SDK or creates an Event by invoking the Event Manager REST API, they are tasked with supplying a "UserData" JSON in the body of the request. The userdata field is a stringified JSON object that looks like the following :

{
    "userdata": {
        "data ": {
            "caller": "alice@comcast.net",
            ... (other KVPs)
        },
        "notification": {
            "type": "video",
            "topic": "my555app.comcast.com/video"
        }

    }
}

The structure and contents of this JSON object controls notification behavior as follows:

  • Any key-value pair passed within the data element of this JSON object will be relayed as-is in the Notification Payload to the receiver.
  • Presence of the notification element decides whether a publish should be made by NTM or not.
  • If the notification element is present, it MUST contain 'topic' field. This field should contain the topic string which should be used by 555 NTM for notification publishes.

Through the userdata attribute above clients control any information that gets relayed to the notification recipient. Note that 555 platform will append session related information also in the notification payload, and therefore mobile platforms that impose limit to the number of characters such as iOS(2K) and Android(4K bytes) need to account for those.

Payload Format

An example of APNs, GCM and XMPP payloads are included below :

XMPP IQ containing payload data :

     <iq id='lx43' type='set' from='prosody'><query strict='false' xmlns='jabber:iq:private'><data userdata='{
    "data": {
        "caller": "alice@comcast.net"
    },
    "notification": {
        "topic": "my555app.comcast.com/video",
        "type": "video"
    }
}' traceid='$TRACE_ID' 
    roomid='$ROOM_ID' 
    routingid='$ROUTING_ID' 
    rtcserver='$RTC_SERVER' xmlns='urn:xmpp:comcast:info'/></query></iq>

APNS payload :

    {
        "aps" : {
        "alert" : "Incoming call,
        "badge" : 1,
        "sound" : default
        },
        "user_data " : "{\"data\":{\"caller\":\"alice@comcast.net\"},\"notification\":{\"type\":\"video\",\"topic\":\"my555app.comcast.com\\/video\"}}",
        "trace_id" : $TRACE_ID,
        "xmpp_token_expiry_time" : $TOKEN_EXPIRY_EPOCH,
        "room_id" : $ROOM_ID,
        "routing_id" : $ROUTING_ID_RECEIPIENT,
        "xmpp_token" : $XMPP_TOKEN,
        "rtc_server" : $RTC_SERVER,
    }

GCM payload :

    {
        "user_data " : "{\"data\":{\"caller\":\"alice@comcast.net\"},\"notification\":{\"type\":\"video\",\"topic\":\"my555app.comcast.com\\/video\"}}",
        "trace_id" : $TRACE_ID,
        "xmpp_token_expiry_time" : $TOKEN_EXPIRY_EPOCH,
        "room_id" : $ROOM_ID,
        "routing_id" : $ROUTING_ID_RECEIPIENT,
        "xmpp_token" : $XMPP_TOKEN,
        "rtc_server" : $RTC_SERVER
    }

CallerID support

Calls from PSTN networks that terminate at 555 apps will contain CallerID information, relayed by the Call gateway, in the notification payload. Essentially, the stringified UserData JSON object will look like the following :

    ...
    {
        "data": {
            "cid": "+18009346489",
            "cname": "Milford NJ"
        },
        "notification": {
            "topic": "555.app.domain/eventName",
            "type": "eventType"
        }
    }
    ...

cid will contain the E164 format Telephone number of the caller and the cname field will bear the caller name.

Handling Notification Payload

While, consumption of userdata in the notification blob is at application's descretion, the RTC session information contained in the notification payload needs to be related to the 555RTCSdk in order to join RTC sessions.

← API Reference