Usage of push notifications by Flexisip

Since SIP clients may run on mobile devices like smartphones, it is illusory to think that SIP clients are ready to process incoming requests at anytime as it was assumed by the initial SIP standard (RFC 3261). Indeed, for the sake of power saving, mobile operating systems (Android, iOS, etc.) use to freeze all the running applications when the phone hasn't been solicited by the user for a time. While the phone is sleeping, no more SIP requests can be received, preventing the SIP client from receiving incoming call, group chat invitations and chat messages.

To get this problem around, Flexisip is able to wake up the recipient's phone by sending a push notification to it before sending the SIP request. For instance, given that User A needs to call User B, which the phone is inactive for a few hours:

  1. User A's client sends an INVITE request to User B's proxy, running Flexisip;
  2. The proxy looks up its registrar database to find the contact address of User B's client;
  3. The proxy tries to forward the INVITE to User B's client but fails because User B's phone is sleeping;
  4. Then, the proxy keeps the request pending and sends a push notification to User B's phone;
  5. The push notification resumes User B's client, which immediately sends a REGISTER to the proxy to create a new TCP/TLS session and update its contact address;
  6. Once the registration completed, the pending INVITE is sent the the new contact address and User B's client receives the incoming call.

Of course, some information like IDs and credentials are needed for having Flexisip to send push notification to a specific device. Such information is given by the client while registration, by using specific parameters in the contact URI, called “push parameters” in this document. These are saved in the registrar database of the proxy with the other routing information for the given SIP identity.

Abbreviations

APNSApple Push Notification ServerPush notification server for Apple devices.
FCMFirebase Cloud MessagingPush notification server which are able to send push notifications to several kind of mobile OS but Flexisip only uses it to send PNs to Android devices.
PNPush Notification 
PNSPush Notification ServerServers which are in charge of sending the actual push notification on demand of SIP proxies. They often depends on the target modile OS.

Requesting Push Notifications while registering the SIP user agent

All these three Contact parameters MUST be set while registering the application to have the proxy server sends Push Notifications:

Parameter nameDescriptionApple Push Notification ServerAndroid (Firebase Cloud Messaging)
pn-providerTells which push notifications provider is used by the SIP client.
  • apns for production APNS
  • apns.dev for development APNS
fcm
pn-pridID that identifies a specific instance of the SIP client. It is given to the SIP client when it subscribes to its PNS. The format depends on the PN provider.
  • <RemoteToken> for requesting Remote PN only.
  • <PushKitToken> for requesting PushKit PN only.
  • <RemoteToken>:remote&<PushKitToken>:voip for requestion Remote and Pushkit both.
Registration token, which is generated by the FCM SDK for each client app instance.
pn-paramExtra information required for sending a push notification. Depends on the PN provider.
  • <ProjectID>.<BundleID> for requesting Remote PNs.
  • <ProjectID>.<BundleID>.voip for requesting PushKit PNs.
  • <ProjectID>.<BundleID>.remote&voip for requesting Remote and PushKit both (RFC extension).

<ProjectID>

Next parameters are optional:

Parameter nameDescriptionDefault value
pn-timeoutAllow to require the proxy to send the push notification a given time after the reception of the SIP request.Value of module::PushNotificaiton/timeout parameter.
pn-call-str(Apple only) Allow to customize the PN title (loc-key) when the PN has been triggered by a call invitation. That may be a plain text or an internationalization key.IC_MSG
pn-msg-str(Apple only) Same as pn-call-str but for chat message delivery.IM_MSG
pn-groupchat-str(Apple only) Same as pn-call-str but for group chat invitation.GC_MSG
pn-call-snd(Apple only) Allow to customize the ringtone for PushKit notification (incoming call).empty
pn-msg-snd(Apple only) Allow to customize the sound of the notification for incoming messages.empty

Content of the push notifications sent by Flexisip

<ttl>
<uid>UID that identifies the singular SIP client, which the SIP request is to be sent to.
<from-uri>The From-URI of the request that has triggered the push notification.
<from-name>The display name in the From header of the request which has triggered the push notification.
<call-id>The Call-ID of the request that has triggered the push notification.
<from><from-name> if not empty, <from-uri> instead.
<date>UTC time when the server sent the push notification at. Format: YYYY-MM-DD HH:mm:ss
<chatroom-addr> 
<badge-boolean>(Apple only) 0 if module::PushNotification/no-badge is true, 1 otherwise.
<alert-msg-id>(Apple only) The title of the push notification. Customized by pn-call-str, pn-msg-str, pn-chatroom-str according to the event which triggers the PN.
<sound-id>(Apple only) The sound of the notification or ringing.
<device-token>(Apple only) The token of the device which the PN is intended for.

Push for Android devices

Flexisip systematically sends a silent push to wake the phone up. Such PNs are to communicate custom data to the application without display any message to the user.

Here is the body used by Flexisip while requesting a PN sending to FCM:

{
   "to": "<device-token>",
   "time_to_live": <ttl>,
   "priority": "high",
   "data": {
       "uuid": "<uid>",
       "form-uri": "<from-uri>",
       "display-name": "<from-name>",
       "call-id": "<call-id>",
       "sip-from": "<from>",
       "loc-key": "",
       "loc-args": "<from>",
       "send-time": "<date>"
    }
}

Push for Apple devices

Historically, Flexisip was sending silent pushes as it does for Android but this way has been disused because, today, Apple doesn't allow more than 3 silent push per hour. Because of this restriction, Flexisip has to use two distinct kind of PN according the kind of the request.

For every call invitation, Flexisip sends a PushKit push notification. Such PNs make the user's phone ringing and the CallKit view to be displayed.

A remote push notificaiton is used for all other kinds of SIP request. Such PNs make a pop-up to be shown on the user's phone.

PushKit notifications body

Such push notifications are sent when Flexisip tries to send a call INVITE to an offline SIP client.

{
   "aps": {
       "sound": "",
       "loc-key": "<alert-msg-id>",
       "loc-args": ["<from>"],
       "call-id": "<call-id>",
       "uuid": "<uid>",
       "send-time": "<date>"
    },
   "from-uri": "<from-uri>",
   "display-name": "<from-name>",
   "pn_ttl": <ttl>,
   "customPayload": {}
}

Remote notifications body

Such push notification are sent when Flexisip tries to send chat messages or group chat invitation.

{
   "aps": {
       "alert": {
           "loc-key": "<alert-msg-id>",
           "loc-args": ["<from>"]
        },
       "sound": "<alert-sound>",
       "mutable-content": 1,
       "badge": <badge-boolean>
    },
   "from-uri": "<from-uri>",
   "display-name": "<from-name>",
   "call-id": "<call-id>",
   "pn_ttl": <ttl>,
   "uuid": "<uid>",
   "send-time": "<date>",
   "chat-room-addr": "<chatroom-addr>"
}

See also

Tags:
Created by François Grisez on 2021/01/19 18:22