Skip to main content
This page follows one user through pgw. Example Corp runs a PBX at pbx.example.com and gives its staff an iOS app, com.example.phone. User 1001 misses calls whenever the phone is locked, so Example Corp installs pgw at pgw.example.com. To make the phone ring, Example Corp creates three records. pgw adds a fourth when the app registers.

Records that you create

Tenant

A tenant is your workspace in pgw. It owns your apps and upstreams, and it has the API key that your commands and API requests use. You create the tenant once, with pgw bootstrap, right after pgw starts for the first time.

App

An app record gives pgw what it needs to push to one of your apps: the app’s identifier and your push credentials for it. Example Corp creates one app record for com.example.phone, with the APNs key from its Apple developer account. pgw encrypts the key before it stores it. You create one app record for each platform that you ship:

Upstream

An upstream tells pgw about one of your PBXs. When an app registers, pgw reads the SIP domain in the request and sends the registration to the upstream that owns that domain. Most setups need one upstream. Example Corp creates one for pbx.example.com, so every registration for 1001@pbx.example.com goes to that PBX. An upstream also lists the addresses that the PBX sends calls from. pgw accepts calls from those addresses and refuses them from anywhere else. An upstream also has a mode and a contact strategy, which you choose when you create it. The defaults suit most PBXs.

The record that pgw creates

Binding

A binding is one registered device. When user 1001 signs in on an iPhone, the app registers through pgw, and pgw creates a binding that ties together three things:
  • The SIP account, sip:1001@pbx.example.com.
  • The device’s push token, which the app sent in its REGISTER.
  • The device’s registration at the PBX.
When a call for 1001 arrives, the binding tells pgw which device to wake and where to deliver the call. If 1001 also signs in on a tablet, that is a second binding, and both devices ring. You never create a binding. pgw removes a binding when the app unregisters, when its registration expires, when you delete it, or when Apple or Google reports that the push token is no longer valid.

Choices for each upstream

You make both choices when you create the upstream, and you can’t change them afterward. To change one, delete the upstream and create it again.

Mode

The mode decides who checks the SIP password, and who keeps the device registered at the PBX. Start with passthrough. It needs no user records, and your PBX stays the only system that holds passwords. Choose managed mode when your PBX grants only short registrations, because waking every app every few minutes drains batteries. Managed mode needs each SIP account’s password, either as a user record in pgw or from a Kamailio database. See Managed mode.

Contact strategy

The contact strategy decides how the PBX learns to send a device’s calls to pgw. The page for your PBX says which one to use.

Call delivery settings

These settings control what happens between the PBX’s INVITE and the phone ringing. Set them in config.yaml. The defaults work for most setups. For every setting, see the settings reference.

Next steps

Quickstart

Create these records on your own computer and make a test call.

How pgw works

Follow the SIP messages of a registration and a call.