# Push Notifications API

> \[!IMPORTANT]
>
> The Push Notifications API is part of the Twilio Communications API, currently available as a
> Private Beta product. The information contained in this document is subject to change. You acknowledge
> and agree that your use of the Twilio Communications API is subject to the terms of the [Services in
> Private Beta](https://www.twilio.com/en-us/legal/service-country-specific-terms/private-beta). This
> means that some features are not yet implemented and others may be changed before the product is
> declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or
> Twilio Service Level Agreement.
>
> Request access to the private beta through the [private beta access request form](https://airtable.com/appqQFoQmQ9WDS1YW/pagDQFkMvNi7O28dN/form).

Mobile devices and browsers rely on platform-specific messaging services to receive push notifications. Twilio supports the following services for delivering push notifications:

* Android and Chrome: Google Firebase Cloud Messaging (FCM)
* Apple devices and Safari: Apple Push Notification service (APNs)

## Resources

The Push Notifications API uses the following resources:

* **Credentials**: Authentication permissions from Google or Apple. After you upload a Credential to Twilio, you can associate it with an App. If you omit the App, Twilio uses your default App.
* **App**: Associates different Credentials with specific DeviceRegistrations. Each version, variant, or environment for your app might require different permissions. This might be because a staging server requires different permissions than a production server.

## Prerequisites

Before you send push notifications, complete the following steps:

* Obtain credentials from [FCM][], [APN][], or both.
* Upload your credentials to the Comms API.

## Create credentials

To separate registrations and credentials for their intended destination, use a namespace called an *App*.

**For example**: you may have a development App and a production App, or you may offer more than one user-facing application to your customers. If you only have one app, Apps get set to `isDefault: true`. Unless otherwise specified in your request, Credentials and DeviceRegistrations fall under the default App.

When creating your Credential, specify an `appName`. If the App doesn't exist, the API creates it. If no other Apps exist, the API sets your created App as the default App.

### Upload FCM credentials

To upload FCM credentials to Twilio, make a `POST` request to the `Credentials` resource including a credential type of `FCM`, your private key, and your App name.

> \[!NOTE]
>
> The `privateKey` value must be base64 encoded.

```bash {title="Upload FCM credentials using cURL"}
curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
     -H 'Content-Type: application/json' \
     -d '{
          "credentialType": "FCM",
          "content": {
            "privateKey": "YOUR_PRIVATE_KEY"
          },
          "appName": "YOUR_APP_NAME"
        }' \
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

To learn how to generate and encode your credentials, see [Obtain FCM credentials][FCM].

### Upload APN credentials

To upload APN credentials to Twilio, call the `Credentials` resource including a credential type of `APN`, your certificate, your private key, and your App name.

> \[!NOTE]
>
> The `certificate` and `privateKey` values must be base64 encoded.

```bash {title="Upload APN credentials using cURL"}
curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
     -H 'Content-Type: application/json' \
     -d '{
          "credentialType": "APN",
          "content": {
            "certificate": "YOUR_CERTIFICATE",
            "privateKey": "YOUR_PRIVATE_KEY"
          },
          "appName": "YOUR_APP_NAME"
        }' \
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

To learn how to generate and encode your credentials, see [Obtain APN credentials][APN].

## Send a notification

You can send a notification without storing it as a registration. In production use cases, you have two options:

* Store the token on a User with `DeviceRegistrations`.
* Manage device tokens yourself and send notifications using a direct `POST` request.

### Send to a single recipient

This request uses your default App and its associated Credentials. If the default App lacks an FCM Credential, the request fails.

```bash {title="Single recipient push notification using cURL"}
curl -X POST 'https://comms.twilio.com/preview/PushNotifications' \
     -H 'Content-Type: application/json' \
     -d '{
          "to": [
            {
              "token": "FCM_DEVICE_TOKEN",
              "provider": "FCM"
            }
          ],
          "content": {
            "title": "Your flight details",
            "body": "Hello, your flight is leaving soon! Tap for details"
          }
        }' \
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

### Send to multiple recipients with personalization

You can send personalized push notifications to up to 10,000 recipients in a single request, with a mix of APN and FCM recipients. To personalize notifications for each recipient, use the [LiquidJS][] templating language.

```bash {title="Multiple recipient push notification using cURL"}
curl -X POST 'https://comms.twilio.com/preview/PushNotifications' \
     -H 'Content-Type: application/json' \
     -d '{
          "to": [
            {
              "token": "FCM_DEVICE_TOKEN",
              "provider": "FCM",
              "variables": {
                "name": "Jessie"
              }
            },
            {
              "token": "APN_DEVICE_TOKEN",
              "provider": "APN",
              "variables": {
                "name": "James"
              }
            }
          ],
          "content": {
            "title": "New styles in stock!",
            "body": "Hey {{name}}, new colorways just dropped on your favorite silhouettes."
          }
        }' \
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

## Next steps

* To send notifications to Android devices and web browsers, set up [FCM credentials][FCM].
* To send notifications to Apple devices, set up [APN credentials][APN].
* Review the [Push Notifications API reference][push-api].

[FCM]: /docs/comms/fcm-credentials

[APN]: /docs/comms/apn-credentials

[push-api]: /docs/api/comms/preview/PushNotifications

[LiquidJS]: /docs/studio/user-guide/liquid-template-language