Skip to main content
At the end of this page, you call extension 1001, the app on your test phone is closed, and the phone rings anyway. This is a test setup. pgw runs on your computer with a self-signed certificate, which only a debug build of your app accepts. When it works, install pgw on a server.

Before you begin

You need:
  • A computer on the same network as your test phone, with 64-bit Linux, macOS, or Windows.
  • Your PBX, reachable from that computer, with a SIP account to test with. This page uses 1001.
  • Push credentials for your app. For iOS, an APNs key (.p8 file) with its key ID and your team ID. For Android, a Firebase service account file. If you don’t have them yet, see iOS apps or Android apps.
  • A debug build of your app that accepts a self-signed certificate. A build from the App Store or Google Play won’t connect in this setup.
The examples use an iOS app, com.example.phone, and a PBX at 192.0.2.10. Use your own values.

Step 1: Start pgw

1

Download pgw

Download the file for your system from the download page into a new folder, and rename it to pgw (pgw.exe on Windows).On Linux and macOS, make it executable:
macOS blocks files that a browser downloaded. Remove the block:
2

Create the starter files

pgw init writes everything that pgw needs to start, with working defaults:
3

Check the address

Open config.yaml and look at hostname. Your phone and your PBX reach pgw at this address, and pgw init filled in your computer’s LAN address. If your computer has several addresses and this is the wrong one, correct it.
4

Start the server

pgw logs its startup and stays in the foreground:
The certificate warning is expected in this setup. pgw then logs pgw ready with the ports that it listens on: 5061 for apps, 5060 for the PBX, and 8080 for commands, which only this computer can reach.
5

Create your tenant

Leave the server running, and open a second terminal in the same folder. A tenant is your workspace in pgw, and it comes with an API key:
You don’t need to copy the key. The other pgw commands read it from .env.

Step 2: Add your app and your PBX

pgw needs two records: an app, so that it can send pushes with your credentials, and an upstream, which is pgw’s name for a PBX. In this setup, both come from tenant.yaml.
1

Add your app

Copy your credential file into the folder. In tenant.yaml, under apps, uncomment the block for your platform and fill in your values:
A debug build of an iOS app receives pushes only from Apple’s sandbox environment, so keep that value for this test.
2

Add your PBX

Under upstreams, replace <pbx-host> with your PBX’s IP address:
If your PBX doesn’t support the Path header, also uncomment contact_strategy and set it to masquerade. You can’t change it later. The page for your PBX, linked in step 3, says whether the PBX needs masquerade.
3

Apply the file

pgw prints what it changed. A + marks a record that it created:

Step 3: Point your PBX and your app at pgw

1

Configure the PBX

The PBX must accept registrations that arrive through pgw, and send the calls for those devices back to pgw. The settings differ for each PBX, so follow its page, then return here:
2

Configure the app

In your debug build, turn off certificate checks, because pgw’s certificate is self-signed. Then add the SIP account. The account stays the same as before, except that the app now connects to pgw instead of the PBX:

Step 4: Check that it works

1

Check the registration

A binding is one registered device. The list shows one binding for 1001, with flow_alive set to true while the app is connected.
2

Close the app

Swipe the app away. On Android, use Recents, not Force stop: Android delivers no pushes to an app that was force-stopped.
3

Call 1001

Call 1001 from another phone on your PBX. The test phone rings, and the call connects when you answer.

If the phone doesn’t ring

Work through these checks in order. To read the push log, ask the API for the latest push events:
The newest event comes first. A delivered call push has the type call and the status code 200. For other symptoms, see Troubleshooting.

Next steps

Install pgw on a server

Move from this test setup to a host that runs pgw under systemd.

Install a TLS certificate

Replace the self-signed certificate, so that store builds of your app connect.

Concepts

Understand the records that you created, and the choices behind them.