- It connects to pgw instead of the PBX.
- It tells pgw its push token in every REGISTER.
- When a call push wakes it, it shows the call and registers again, so that pgw can deliver the call.
- It dismisses calls that ended before it answered.
Connect to pgw
- Connect over TLS to pgw’s port for apps,
5061by 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 asips:request with480 Temporarily Unavailable. - Stay under 5 requests a second for each device, with bursts of 20. A request over the limit gets
503 Service UnavailablewithRetry-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:
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 ofpn-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 acall push. The app has 30 seconds, by default, to come back for it:
- 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.
- Open a new connection to pgw and register again, with the same push token or
+sip.instanceas before. - Answer the held INVITE, which pgw sends on that connection after the
200 OK.
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
missedpush. 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 OKto that REGISTER carriesX-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 withpgw binding test-pushto check the token.
pgw_event field: call, missed, refresh, or test. Ignore a value that the app doesn’t know.
Unregister
Send a REGISTER whose Contact hasexpires=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.