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:
- Enabling correct triggers for the app domain
- 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.
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.
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 APNsfcm
- subscribers identified using FCM issued device tokens and notified via Firebase cloud messagingxmpp
- 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 overHTTP 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:
- Independent publishes made by application servers outside the context of RTC session
- 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.