Skip to main content
A phone in a pocket has no SIP socket. Android kills a background connection within minutes; iOS suspends it the moment the app leaves the screen. A mobile that is not registered does not ring, however many times you call it. The way out is a push. When a call arrives for an extension whose mobile app has said how it can be woken, FireTone sends the push, waits for the app to wake and register again, and only then rings the extension. The caller hears ringback for the wait, a few seconds at most.

​
What the app tells FireTone

The app has two ways of saying how to wake it, and both work.
  • In its SIP registration. The Contact it registers with carries the standard parameters (RFC 8599): pn-provider (fcm for Android, apns or apns.dev for iPhone), pn-prid (its push token) and pn-param (the app’s parameter: the Firebase app id, or the APNs topic). The extension’s page shows these under the device, so you can see the app registered the way push needs before anything is pushed.
  • By posting its token. POST /push/register, which is how an iPhone’s PushKit token reaches FireTone at all — it is not in the SIP registration. The extension’s page lists what has been posted under Can be woken by push.

​
What the push carries

A data-only message, no notification block, high priority (FCM) or the voip push type (APNs). Its keys, on both platforms: The key is caller, not from: FCM reserves from (with notification, message_type and anything beginning google or gcm) and refuses the whole message with 400 Invalid data payload key. The iPhone payload also carries from for a build that already reads it.

​
The posting contract

For whoever builds the app. The call is on the FireTone API, not on a separate service:
It authenticates as the extension, with HTTP Basic carrying the SIP username and password the app already holds. Unauthenticated, anyone could attach a token to a number and be told who calls it. Wrong credentials and no such extension get the same 401, so a probe learns neither.
There is no separate relay, and no /wake. FireTone wakes devices itself, at the moment a call arrives, from what is registered and what has been posted. The app’s only call is the one above; the base URL is the FireTone API. A 200 means the token is stored.

​
What you set up, once

Under Settings → Mobile push, add the FireTone app for each platform. These are the operator’s, not a tenant’s: one app serves every organisation. Android (FCM). In the Firebase console, the project the Android app belongs to, and a service account with the Firebase Cloud Messaging API role. Paste the service account’s JSON key. The device parameter is what the app puts in pn-param; leave it empty to make this the default Android app. iPhone (APNs). In the Apple Developer portal under Keys, a key with Apple Push Notifications enabled, downloaded as a .p8. Enter the team id, the key id, the topic (the app’s bundle id with .voip, for example au.remotiq.firetone.client.voip), and paste the key’s text. One key serves every app on the team and does not expire, which is why a key is preferred to a VoIP Services certificate. The topic you type here is what is sent; the device’s pn-param chooses which app, and stands in as the topic only for an app with none. Apple’s TopicDisallowed names the topic it refused. A build signed for development holds a sandbox token; the app reports apns.dev for it and FireTone pushes it through Apple’s sandbox host with the same key. Pushing a sandbox token to the production host is refused with BadDeviceToken, which the Test button explains in words.

​
Testing

Each app has a Test button: paste a device’s token from its extension’s page and one push is sent exactly as a call would send it. The app should wake; nothing rings. The provider’s answer is shown, with the reason when it refused. That proves the credential. To prove the match — that a call to this device would find this app — use Test push beside the device on its extension’s page instead: the app is chosen from the device’s provider and parameter exactly as a call chooses it, and no fcm app is set up for “83705583400” there means the device parameter on your app differs from what the app sends (or is not empty, which would make it the default). The refusal goes on to list the apps you have for that provider, each with its device parameter and whether it is enabled, so the difference is in front of you.

​
What happens on a call

  1. A call arrives for an extension. FireTone reads the switch’s registrations for it and the tokens posted for it.
  2. Every device that can be woken is pushed, once. Each push is recorded on the extension’s page under “Recent pushes” with the provider’s answer and how long it took.
  3. FireTone waits for the app to re-register: up to eight seconds when the extension has no other device that could ring, three when a desk phone is also registered and should not be kept waiting. The wait ends the moment the app is back.
  4. The extension is rung on every device registered by then. The call’s journey carries a push line saying what was pushed and whether the device woke in time.
The app gives up 45 seconds after a push with no call, so all of this fits comfortably inside its patience.

​
Reading a failure

The extension’s page shows each push’s outcome. “refused” is the provider’s answer, with its reason: a dead token (the app was uninstalled, the token rotated), the wrong APNs environment, a topic that does not match the app. “failed” means the provider could not be asked, or no app is set up for the device’s provider and parameter. A push that was accepted but did not wake the device in time reads “no re-register in time”: the app took longer than the wait, or is not allowed to run in the background on that phone.