> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firetone.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile push

> Waking the FireTone app for an incoming call when the phone is in a pocket

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` with `{token, sipUser,
  platform}`, authenticated with HTTP Basic carrying the extension's SIP
  username and password. This is how an iPhone's PushKit token, which is not
  in the SIP registration, reaches FireTone. The extension's page lists these
  under "Can be woken by push".

## 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.

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.

## 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.