Push notifications
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:
- User A's client sends an INVITE request to User B's proxy, running Flexisip;
- The proxy looks up its registrar database to find the contact address of User B's client;
- The proxy tries to forward the INVITE to User B's client but fails because User B's phone is sleeping;
- Then, the proxy keeps the request pending and sends a push notification to User B's phone;
- 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;
- 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
| APNS | Apple Push Notification Server | Push notification server for Apple devices. |
| FCM | Firebase Cloud Messaging | Push 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. |
| PN | Push Notification | |
| PNS | Push Notification Server | Servers 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 name | Description | Apple Push Notification Server | Android (Firebase Cloud Messaging) |
|---|---|---|---|
| pn-provider | Tells which push notifications provider is used by the SIP client. |
| fcm |
| pn-prid | ID 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. |
| Registration token, which is generated by the FCM SDK for each client app instance. |
| pn-param | Extra information required for sending a push notification. Depends on the PN provider. |
| <ProjectID> |
Next parameters are optional:
| Parameter name | Description | Default value |
|---|---|---|
| pn-timeout | Allow 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> | module::Router/call-fork-timeout for calls, module::Router/message-delivery-timeout for messages. |
| <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>"
}