> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# How pgw works

> Follow a registration, an incoming call, and a missed call through pgw, message by message.

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.](https://mintcdn.com/pgw/AxRzHBtQGOZ6Qv0v/images/deployment.svg?fit=max\&auto=format\&n=AxRzHBtQGOZ6Qv0v\&q=85\&s=63ab27bde28a78e7498a43a54d416be4)

Each of pgw's connections needs a path through your network:

| Connection | Direction | Default port | Why |
| - | - | - | - |
| App to pgw | Inbound to pgw | TCP `5061`, TLS | Apps always open the connection, so a phone needs no open inbound port. pgw sends calls to an app over the connection that the app opened. |
| pgw and the PBX | Both ways | UDP and TCP `5060` | pgw sends registrations to the PBX, and the PBX sends calls to pgw. |
| pgw to the push services | Outbound from pgw | HTTPS `443` | pgw calls `api.push.apple.com` (and `api.sandbox.push.apple.com` for sandbox apps), `fcm.googleapis.com`, and `oauth2.googleapis.com`. For browser apps, it also calls the push services in `webpush_hosts`. |

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.

```mermaid theme={null}
sequenceDiagram
    participant App
    participant pgw
    participant PBX
    App->>pgw: REGISTER with push token
    pgw->>PBX: REGISTER with Path, without push token
    PBX-->>pgw: 401 Unauthorized
    pgw-->>App: 401 Unauthorized
    App->>pgw: REGISTER with credentials
    pgw->>PBX: REGISTER with Path, without push token
    PBX-->>pgw: 200 OK
    pgw-->>App: 200 OK
```

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](https://docs.pgw.sipmicro.services/upstreams/managed-mode.md), 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.

```mermaid theme={null}
sequenceDiagram
    participant App
    participant Push as APNs or FCM
    participant pgw
    participant PBX
    PBX->>pgw: INVITE
    pgw-->>PBX: 100 Trying
    pgw->>Push: call push
    pgw-->>PBX: 180 Ringing
    Push-)App: push
    App->>pgw: REGISTER
    pgw->>PBX: REGISTER
    PBX-->>pgw: 200 OK
    pgw-->>App: 200 OK
    pgw->>App: INVITE
    App-->>pgw: 200 OK
    pgw-->>PBX: 200 OK
```

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](https://docs.pgw.sipmicro.services/concepts.md#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.

```mermaid theme={null}
sequenceDiagram
    participant App
    participant Push as APNs or FCM
    participant pgw
    participant PBX
    Note over pgw: The INVITE is held.
    alt The caller hangs up
        PBX->>pgw: CANCEL
        pgw-->>PBX: 487 Request Terminated
    else The app doesn't return within the hold time
        pgw-->>PBX: 480 Temporarily Unavailable
    end
    pgw->>Push: missed-call push
    Push-)App: missed call
```

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.

| Limit | Default | Over the limit | Setting |
| - | - | - | - |
| Held calls for one device | 8 | `486 Busy Here` | `max_held_per_binding` |
| Held calls in total | 10,000 | `503 Service Unavailable` | `max_held_invites` |
| Call and missed-call pushes to one device | 10 a minute, after a burst of 5 | `486 Busy Here`, and no push | `call_push_rate_per_binding`, `call_push_burst_per_binding` |

## Next steps

> [card] [Quickstart](https://docs.pgw.sipmicro.services/quickstart.md)
>
> Watch this flow on your own computer with a test call.

> [card] [SIP responses](https://docs.pgw.sipmicro.services/reference/sip-responses.md)
>
> Look up a status code that pgw sent, and why.

> [card] [Integrate your app](https://docs.pgw.sipmicro.services/apps/integrate.md)
>
> See what your app must send and how it handles each push.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.