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

# Push payload

> The events, fields, and delivery settings of each push that pgw sends to iOS, Android, and browser apps.

Every push that pgw sends to an iOS or Android app carries a `pgw_event` field that names why pgw sent it. A push to a browser has no body. To act on each event, see [Integrate your app with pgw](https://docs.pgw.sipmicro.services/apps/integrate.md).

## Events

| `pgw_event` | Sent when | iOS | Android |
| - | - | - | - |
| `call` | A call arrives for the app. | VoIP push to the VoIP token, priority 10. When the app registered only a remote token, an alert push to the remote token, titled "Incoming call" with the caller's display name as its body. Kept until pgw stops holding the call (`hold_seconds`). | Data message, high priority, kept until pgw stops holding the call (`hold_seconds`). |
| `missed` | The call ended after a call push and before the app responded: the caller hung up, or the hold time ran out. pgw skips it when the PBX's CANCEL says that another phone answered. | Alert push to the remote token, priority 10, titled "Missed call" with the caller's display name as its body. Kept for 1 hour. | Data message, high priority, kept for 1 hour. |
| `refresh` | The registration expires soon. | Background push to the remote token, priority 5. | Data message, normal priority. |
| `test` | An operator checks the device's push token with `pgw binding test-push`. | Background push to the remote token, priority 5, delivered now or never. | Data message, normal priority, kept for 60 seconds. |

The push service keeps a `refresh` push until the registration that it refreshes expires. In passthrough mode, that is the registration at the PBX. In managed mode, it is the registration that pgw granted the app.

A call to a user with several sleeping devices sends one call push to each device. When one device answers, the others get no missed-call push.

On iOS, pgw skips `missed`, `refresh`, and `test` when the app registered no remote token. An app that gets `call` as an alert registers again when the user taps the alert, and pgw delivers the call if pgw still holds the call.

## When pgw sends each push

| Push | Timing |
| - | - |
| Call | When pgw holds a call for the device. A second call that arrives within 10 seconds of a successful call push, while pgw still holds the first, is held without another push. |
| Missed call | When a held call ends without an answer, if its call push went out. Not sent when the PBX's CANCEL carries `Reason: SIP;cause=200`, which means that another phone answered. |
| Refresh | 2 minutes before the registration expires on iOS, and 10 minutes before on Android. When the PBX grants less than twice that lead time, pgw pushes halfway through the registration and logs a warning. When a refresh push fails for a reason other than the push service refusing it, pgw retries every 30 seconds until the registration expires. |

## Fields

| Field | Set for | Description |
| - | - | - |
| `pgw_event` | All events | `call`, `missed`, `refresh`, or `test`. An app should ignore a value that it doesn't know. |
| `call_id` | `call`, `missed` | The SIP Call-ID of the call. |
| `from_uri` | `call`, `missed` | The caller's SIP URI. |
| `from_display` | `call`, `missed` | The caller's display name, or empty when the INVITE has none. |
| `to_aor` | `call`, `missed`, `refresh` | The SIP address of the called user: the user and host of the To URI that the app registered with. The user has no needless `%` escapes, and the host is in lower case. |
| `call_str` | `call` | The value of the app's `pn-call-str` parameter, or empty when the app sent none. |

On Android, every message carries all six fields in the `data` object of the FCM message, and a field that isn't set for the event is an empty string. On iOS, the fields are top-level keys of the APNs payload, beside `aps` on an alert or background push. Each iOS push carries only these fields:

| Event | Fields |
| - | - |
| `call` | All six |
| `missed` | `pgw_event`, `call_id`, `from_uri`, `from_display` |
| `refresh`, `test` | `pgw_event` |

### Long caller fields

A push must fit the push service's size limit, so pgw shortens `from_display` to 128 characters, `from_uri` and `to_aor` to 256, and `call_str` to 64. A shortened value ends with `…`. When the push is still too big, pgw empties the four fields and sends it anyway. pgw never changes the INVITE, so the app reads the full caller from it.

## Web Push

A push to a browser has no body, so it carries none of the fields. pgw sends it only for `call` and `test`. The service worker can't tell the two apart, so it treats each push as a call.

| Header | `call` | `test` |
| - | - | - |
| `TTL` | Seconds until pgw stops holding the call (`hold_seconds`) | `60` |
| `Urgency` | `high` | `normal` |
| `Authorization` | `vapid t=<JWT>, k=<public key>` | `vapid t=<JWT>, k=<public key>` |

The web app's VAPID key signs the JWT. Its `aud` claim is the push service's origin, its `sub` claim is the app's `vapid_subject`, and it expires 12 hours after pgw makes it.

## Next steps

> [card] [Integrate your app](https://docs.pgw.sipmicro.services/apps/integrate.md)
>
> Implement the handling that each event needs.

> [card] [Push log](https://docs.pgw.sipmicro.services/push-log.md)
>
> Check which pushes pgw sent to a device, and what the push service answered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.