Skip to main content
pgw can wake an app for a call only because it stays in the SIP path. Every registration passes through it on the way to the PBX, and every call passes through it on the way back. After this page, you know what to expect in a SIP trace and what your firewall must allow. The examples use user 1001 at Example Corp.

Where pgw sits

pgw sits between the apps and the PBX. Apps connect over TLS on port 5061 or secure WebSocket, the PBX sends calls on port 5060, and pgw sends pushes to APNs, FCM, and Web Push. The diagram shows managed mode.
Each of pgw’s connections needs a path through your network: If pgw reaches the internet through a proxy, set HTTPS_PROXY in its environment. Audio and video never pass through pgw. They flow between the app and the PBX, exactly as they do without pgw.

How an app registers

The app on 1001’s iPhone is configured with pgw as its outbound proxy, so its REGISTER arrives at pgw. The request looks like any other registration, except that its Contact carries the device’s push token. pgw finds the upstream that owns the domain pbx.example.com. It takes the push token out and stores it. Then it forwards the registration, with a Path header that tells the PBX to send this device’s calls through pgw. In passthrough mode, the default, the PBX challenges the request, and the app answers, as usual. pgw passes both along and never sees the password. In managed mode, pgw checks the password and registers at the PBX itself. When the PBX answers 200 OK, pgw saves a binding for the device, and from then on it can wake the device.

How the registration stays alive

A registration expires, and a sleeping app can’t renew it. So shortly before the expiry, pgw sends the app a silent refresh push. The app wakes in the background, registers again, and goes back to sleep. The user sees nothing. pgw sends the refresh push 2 minutes before the expiry on iOS and 10 minutes before on Android. It asks the PBX for a registration of one hour, which you can change with the upstream’s max_expires.

How a call reaches the app

Someone calls 1001. The PBX looks up the registration, finds the Path, and sends the INVITE to pgw. The app has been asleep for a while, so pgw has no connection to deliver the call over.
  1. pgw holds the INVITE and answers 100 Trying, so the PBX stops retransmitting.
  2. pgw sends a call push to the device’s push token. When the push service accepts it, pgw answers 180 Ringing, and the caller hears ringing while the app wakes.
  3. The app wakes and registers again. This opens a new connection to pgw.
  4. pgw sends the held INVITE over that connection. From here on, the call is a normal one, and pgw relays every request and response between the app and the PBX until it ends.
pgw holds a call for 30 seconds, which you can change with hold_seconds.

When the app is still connected

Sometimes the app still has an open connection, for example right after the user leaves it. For these calls, pgw first sends the INVITE over the open connection, and pushes only if the app stays silent for 3 seconds. You can make pgw push for every call instead. See Call delivery settings.

When a user has several devices

Each device registers on its own and has its own binding. In passthrough mode, the PBX holds one contact for each device and decides which ones to ring, as it does for any user with several phones. In managed mode, pgw rings all of the user’s devices at once, and the first one to answer takes the call.

What happens to a missed call

A held call ends without an answer when the caller hangs up, or when the hold time runs out before the app returns. Either way, a device that received the call push may be showing an incoming call that no longer exists. If the call push went out, pgw sends a missed-call push, so that the app can show a missed-call notification. When the app next registers, pgw’s answer also carries the header X-Pgw-Call-Status, which names the call that ended, so that the app can dismiss its call screen. pgw sends no missed-call push when the PBX’s CANCEL says that another phone answered the call.

Limits that protect pgw and the device

pgw limits how many calls it holds and how often it pushes to one device. pgw refuses calls over a limit, and the PBX handles the refusal as it would for any busy or unavailable phone.

Next steps

Quickstart

Watch this flow on your own computer with a test call.

SIP responses

Look up a status code that pgw sent, and why.

Integrate your app

See what your app must send and how it handles each push.