Push Notifications API

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.

Before you send push notifications, complete the following steps:

• Obtain credentials from FCM, APN, or both.
• Upload your credentials to the Comms API.

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.

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.

1
curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
2
     -H 'Content-Type: application/json' \
3
     -d '{
4
          "credentialType": "FCM",
5
          "content": {
6
            "privateKey": "YOUR_PRIVATE_KEY"
7
          },
8
          "appName": "YOUR_APP_NAME"
9
        }' \
10
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

To learn how to generate and encode your credentials, see Obtain FCM 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.

1
curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
2
     -H 'Content-Type: application/json' \
3
     -d '{
4
          "credentialType": "APN",
5
          "content": {
6
            "certificate": "YOUR_CERTIFICATE",
7
            "privateKey": "YOUR_PRIVATE_KEY"
8
          },
9
          "appName": "YOUR_APP_NAME"
10
        }' \
11
     -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

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

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.

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

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.

• To send notifications to Android devices and web browsers, set up FCM credentials.
• To send notifications to Apple devices, set up APN credentials.
• Review the Push Notifications API reference.