# Send a push notification

> \[!IMPORTANT]
>
> The Push Notifications API is 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 Push Notifications 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.

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 all web browsers (including Safari): Google Firebase Cloud Messaging (FCM)
* iOS devices: 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 might have a development App and a production App, or offer more than one user-facing application to your customers. If you only have one App, Twilio sets it to `isDefault: true`. Unless you specify otherwise 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/v1/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 APNs credentials

To upload APNs 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 APNs credentials using cURL"}
curl -X POST 'https://comms.twilio.com/v1/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 APNs 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

The following request sends a notification to one FCM device using your default App and its associated Credentials. To send using a non-default App or a specific Credential, include the `from` object in the request body. See the [PushNotifications resource](/docs/push-notifications/api/notification-resource) reference for details.

```bash {title="Single recipient push notification using cURL"}
curl -X POST 'https://comms.twilio.com/v1/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 APNs 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/v1/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 [APNs credentials][APN].
* Review the [Push Notifications API reference](/docs/push-notifications/api/notification-resource).

[FCM]: /docs/push-notifications/fcm-credentials

[APN]: /docs/push-notifications/apn-credentials

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