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

# Integrate your app with pgw

> Implement the SIP and push handling that a softphone needs to receive calls through pgw while it sleeps.

This page is for the developer of a SIP app. If your app is built on a SIP library that supports RFC 8599 push, most of this already works, and you can use the page as a checklist.

An app that sleeps gets its calls through pgw when it does the following:

1. It connects to pgw instead of the PBX.
2. It tells pgw its push token in every REGISTER.
3. When a call push wakes it, it shows the call and registers again, so that pgw can deliver the call.
4. It dismisses calls that ended before it answered.

## Connect to pgw

* **Connect over TLS** to pgw's port for apps, `5061` by default. A browser app connects over secure WebSocket instead. See [Web apps](https://docs.pgw.sipmicro.services/apps/web.md#open-the-websocket-listener).
* **Use pgw as the outbound proxy**, with a Route such as `<sip:pgw.example.com:5061;transport=tls;lr>`. Keep the PBX's domain in the Request-URI and the To header, because pgw picks the upstream by the host of the REGISTER's Request-URI.
* **Send every request on the connection that you registered over.** pgw relays your calls, messages, and subscriptions to the PBX, which authenticates them. A request on any other connection gets `403 Forbidden`.
* **Use `sip:` URIs.** pgw reaches the PBX over plain UDP or TCP, so it answers a `sips:` request with `480 Temporarily Unavailable`.
* **Stay under 5 requests a second** for each device, with bursts of 20. A request over the limit gets `503 Service Unavailable` with `Retry-After: 1`.

## Add push parameters to the REGISTER

Put the push parameters in the URI of the REGISTER's single Contact. pgw removes them before it forwards the REGISTER.

| Parameter | Value |
| - | - |
| `pn-provider` | `apns` for iOS, `apns.dev` for an iOS build that uses the APNs sandbox, `fcm` for Android, or `webpush` for a browser |
| `pn-param` | iOS: `<team ID>.<bundle ID>` with a suffix that names the token kind. Android: the Firebase project ID or project number. Web Push: leave it out. |
| `pn-prid` | The push token. It can be percent-encoded. Web Push: the subscription's `endpoint`, percent-encoded. |
| `pn-call-str` | Optional. pgw copies it into the `call_str` field of the call push. |

Also send a `+sip.instance` Contact parameter that stays the same for the life of the installation. pgw recognizes a device by an earlier push token, then by `+sip.instance`, then by the Contact URI. A stable `+sip.instance` keeps the device on one registration when the device's token and address change.

An iOS app that sends both tokens:

```text theme={null}
Contact: <sip:1001@192.0.2.50:51234;transport=tls;pn-provider=apns;pn-param=ABCDE12345.com.example.phone.remote&voip;pn-prid=<remote token>:remote&<voip token>:voip>;+sip.instance="<urn:uuid:00000000-0000-0000-0000-000000000001>";expires=3600
```

An Android app:

```text theme={null}
Contact: <sip:1001@192.0.2.51:40112;transport=tls;pn-provider=fcm;pn-param=example-phone;pn-prid=<fcm token>>;+sip.instance="<urn:uuid:00000000-0000-0000-0000-000000000002>"
```

### Name the iOS token kinds

An iOS app can send a VoIP token for PushKit, a remote token for other notifications, or both. pgw reads the kind from the suffix of `pn-param` and from labels in `pn-prid`.

| `pn-param` ends with | `pn-prid` | Tokens |
| - | - | - |
| `.voip` | `<voip token>` | VoIP |
| `.remote`, or no suffix | `<remote token>` | Remote |
| `.remote&voip` | `<remote token>:remote&<voip token>:voip` | Both |

Without a VoIP token, a call arrives as an alert push to the remote token. Without a remote token, pgw sends no missed-call, refresh, or test push.

### Responses to a REGISTER

| Response | Cause |
| - | - |
| `200 OK` with `Feature-Caps` | pgw registered the device. `+sip.pns` names the provider, and `+sip.pnsreg`, when present, is how many seconds before expiry pgw sends a refresh push. |
| `400 Bad Push Parameters` | A `pn-param` or `pn-prid` that pgw can't parse, such as an unlabeled `pn-prid` with a `.remote&voip` `pn-param`. |
| `400 Too Many Contacts` | More than one Contact. Each REGISTER registers one device. |
| `555 Push Notification Service Not Supported` | An unknown `pn-provider`, or no app in pgw matches the bundle ID or Firebase project. `Feature-Caps` lists the providers pgw serves. |

A REGISTER with `pn-provider` and no `pn-prid` asks only for capabilities and registers nothing. A browser app uses it to get the VAPID key. See [Web apps](https://docs.pgw.sipmicro.services/apps/web.md#create-the-web-app-and-subscribe).

## Handle a call push

When a call arrives for a device with no open connection, pgw holds the INVITE and sends a `call` push. The app has 30 seconds, by default, to come back for it:

1. On iOS, report the call to CallKit as soon as the VoIP push arrives. iOS stops an app that receives a VoIP push and reports no call. On Android, show a notification for the high-priority message. Android lowers the priority of apps that don't.
2. Open a new connection to pgw and register again, with the same push token or `+sip.instance` as before.
3. Answer the held INVITE, which pgw sends on that connection after the `200 OK`.

For the push fields, see [Push payload](https://docs.pgw.sipmicro.services/reference/push-payload.md).

## Handle calls that end before the app answers

* **Missed call.** When the caller hangs up or the hold time runs out after a call push, pgw sends a `missed` push. On iOS, it is an alert to the remote token.
* **Answered elsewhere.** When another device answers, pgw sends no missed-call push. A device that already has the INVITE gets a CANCEL with `Reason: SIP;cause=200;text="Call completed elsewhere"`. Use it to dismiss the ringing screen.
* **Call ended while waking.** When a held call ends before the app registers, the `200 OK` to that REGISTER carries `X-Pgw-Call-Status: <call-id>;ended`. End the call that the app reported to CallKit or showed in its notification.

## Handle refresh and test pushes

* **`refresh`.** Register again. pgw sends it before the registration expires. A browser app never gets one.
* **`test`.** Do nothing. An operator sent it with `pgw binding test-push` to check the token.

Each push to an iOS or Android app names its kind in the `pgw_event` field: `call`, `missed`, `refresh`, or `test`. Ignore a value that the app doesn't know.

## Unregister

Send a REGISTER whose Contact has `expires=0`, or an `Expires: 0` header. An `expires` parameter on the Contact wins over the header. pgw removes the device and its push token after the PBX accepts the request, or at once in managed mode. To remove every device of the account, send `Contact: *` alone with `Expires: 0`. pgw answers `Contact: *` without `Expires: 0` with `400 Invalid Wildcard`.

## Next steps

> [card] [Push payload](https://docs.pgw.sipmicro.services/reference/push-payload.md)
>
> Look up the fields and priority of each push that your app handles.

> [card] [How pgw works](https://docs.pgw.sipmicro.services/how-pgw-works.md)
>
> See what pgw does between your REGISTER and the INVITE.

> [card] [Try it on the Android emulator](https://docs.pgw.sipmicro.services/tutorial-android-emulator.md)
>
> Compare your app with an open-source build that rings while closed.


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