> ## 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.

# Configure an iOS app

> Create an APNs key for your iOS app and register the app in pgw.

When you finish this page, pgw can wake your iOS app for a call. iOS wakes a closed app for a call only through a VoIP push. Apple delivers a VoIP push at once, and the app must answer it by showing the system's call screen. pgw sends it through Apple's push service, APNs, signed with a key from your Apple developer account.

## Before you begin

* An Apple developer account with access to **Certificates, Identifiers & Profiles**.
* The app's bundle ID, such as `com.example.phone`.

## Create an APNs key

One key works for all the apps of your team, and it doesn't expire.

**1. Open your developer account**

Sign in to your Apple developer account, and open **Certificates, Identifiers & Profiles**.

**2. Create a key**

Under **Keys**, create a key with **Apple Push Notifications service (APNs)** turned on.

**3. Download the key**

Download the `.p8` file, and note the key ID. You can download the file only once.

**4. Note your team ID**

Note your team ID, shown under **Membership details**.

> [!WARNING]
>
> The `.p8` file is a credential. Don't commit it or share it.

## Register the iOS app in pgw

Apple runs two separate push services, and a build receives pushes from only one of them. Set `--apns-environment` to `sandbox` for a build that you run from Xcode, and to `production` for TestFlight and App Store builds:

```bash theme={null}
pgw app create --platform ios --bundle-id com.example.phone --apns-team-id ABCDE12345 --apns-key-id ABC123DEFG --apns-key-file AuthKey_ABC123DEFG.p8 --apns-environment sandbox
```

| Flag | Value |
| - | - |
| `--bundle-id` | The app's bundle ID, without a `.voip` suffix. |
| `--apns-team-id` | Your Apple team ID. |
| `--apns-key-id` | The APNs key ID. |
| `--apns-key-file` | The `.p8` file. pgw accepts only a PKCS #8 P-256 private key in PEM. |
| `--apns-environment` | `production`, the default, or `sandbox`. |
| `--name` | Optional. A name that log lines show instead of the bundle ID. |

## Check that it works

Register the app through pgw, close it, and call the account. The phone shows the system's incoming-call screen. If it doesn't, the most common cause is the environment: a debug build with `production`, or a store build with `sandbox`. The [push log](https://docs.pgw.sipmicro.services/push-log.md) shows Apple's answer to each push.

## Which push pgw sends for each event

An iOS app can give pgw two tokens: a VoIP token, for pushes that ring, and a remote token, for ordinary notifications. The table shows which token pgw uses for each event. To send both from your app, see [Name the iOS token kinds](https://docs.pgw.sipmicro.services/apps/integrate.md#name-the-ios-token-kinds).

| Event | Push type | Token | Topic |
| - | - | - | - |
| Incoming call | `voip`, priority 10 | VoIP token | The bundle ID with `.voip` |
| Incoming call, when the app sent no VoIP token | `alert`, priority 10, titled "Incoming call" | Remote token | The bundle ID |
| Missed call | `alert`, priority 10, titled "Missed call" | Remote token | The bundle ID |
| Registration refresh, and `pgw binding test-push` | `background`, priority 5, with `content-available` | Remote token | The bundle ID |

An app that sent no remote token gets only call pushes. A test push never goes to the VoIP token, because iOS requires the app to report a call to CallKit for every VoIP push.

## Next steps

> [card] [Integrate your app](https://docs.pgw.sipmicro.services/apps/integrate.md)
>
> Send the push tokens in the REGISTER and report each call to CallKit.

> [card] [Push payload](https://docs.pgw.sipmicro.services/reference/push-payload.md)
>
> Look up the fields that each push in the table carries.


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