Skip to main content
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.
  • 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. 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:
An Android app:

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

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.

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.

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

Push payload

Look up the fields and priority of each push that your app handles.

How pgw works

See what pgw does between your REGISTER and the INVITE.

Try it on the Android emulator

Compare your app with an open-source build that rings while closed.