Skip to main content
A softphone can take a call only while it holds a connection to your PBX. iOS and Android close that connection soon after the app leaves the screen, so the PBX finds nobody to ring and the user misses the call. pgw solves this without changes to your PBX. It sits between the PBX and your apps. When a call arrives for a sleeping app, pgw holds the call, wakes the app with a push notification, and hands the call over as soon as the app reconnects. To the caller, it is an ordinary call.
pgw in managed mode. The app registers with pgw over TLS or secure WebSocket, pgw registers at the PBX with its own contact, the PBX sends calls to pgw, pgw wakes the app through APNs, FCM, or Web Push, and the app registers again to receive the call. Media flows directly between the app and the PBX.

How a call reaches a sleeping app

The numbers match the diagram, which shows pgw in managed mode.
  1. The app registers with pgw. Instead of connecting to the PBX, the app connects to pgw, over TLS or, from a browser, over secure WebSocket. Its REGISTER carries a push token, which is the address that the push service uses to reach that one device.
  2. pgw registers at your PBX. pgw keeps the push token for itself. In managed mode, it registers the user with its own contact and renews that registration itself. In passthrough mode, the default, it passes the app’s own registration on. Either way, the PBX sees an ordinary phone.
  3. A call arrives. Because the app registered through pgw, the PBX sends the INVITE to pgw.
  4. pgw holds the call and sends a push. The app is asleep, so pgw keeps the INVITE and asks APNs, FCM, or the browser’s Web Push service to wake the device, using your own push credentials. As soon as the push service accepts the push, the caller hears ringing.
  5. The push wakes the app. The app starts in the background and shows the incoming call. A browser shows a notification, and the user opens it.
  6. The app registers again, and pgw delivers the call. The new registration gives pgw an open connection, and pgw sends the held INVITE over it.
  7. Audio flows directly. Once the user answers, media travels between the app and the PBX. pgw never relays it.
If the app doesn’t return within 30 seconds, pgw tells the PBX that the user is unavailable and sends the app a missed-call push. For the SIP messages behind each step, see How pgw works.

When to use pgw

Use pgw when your users have a softphone on their phone or in their browser and miss calls while the app is closed. You don’t need pgw for desk phones, or for softphones that stay open on a desktop computer. They keep their connection, so the PBX reaches them directly. pgw does one job, and leaves the rest to the systems that you already run:
  • It doesn’t replace your PBX. Every device is still registered at your PBX, which keeps handling users, dial plans, and voicemail.
  • It doesn’t carry audio or video. The PBX must be able to exchange media with the app, as it does today.
  • It doesn’t supply push credentials. You register your app with Apple or Google, and pgw sends pushes with your key.

What you can build

What you need

Next steps

Quickstart

Run pgw on your computer and make a closed app ring.

Concepts

Learn the three records that you create and the two choices that you make.