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, withpgw 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 forcom.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 forpbx.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 user1001 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.
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 inconfig.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.