GuidesPush

Push Notifications API

Overview

You can use Google’s Firebase Cloud Messaging (FCM) to send push notifications to Android devices and web browsers. To send to Apple devices, you’ll need to use Apple’s Push Notification service (APN). You can also use APN to push to Safari browsers.

Concepts

To understand the Push Notifications endpoints, you should be aware of these resources:

  • Credentials: Stores your credentials from Google or Apple. These credentials are used to send the push notification to the device token you register.
  • App: Allows you to separate Credentials and DeviceRegistrations by app ID. You may have multiple applications (for example, a test app, or separate apps like OwlEats and OwlRides). If you only have one app, it will be set to isDefault: true and Credentials and DeviceRegistrations will automatically fall under the default App unless otherwise specified in your request.

Send your first notification

Before sending any push notifications, you need to obtain credentials from FCM or APN and store them as a Credential in the Comms API.

Create credentials

First, a word about Apps. Apps are namespaces that allow you to separate registrations and credentials for their intended destination. 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.

You must specify an appName in your credential creation. If the App does not exist, it will be created. If you don’t already have an App, it will be set to be the default App.

Create FCM credentials

To upload FCM credentials to Twilio, make the request shown below. See Obtaining FCM Credentials for detailed instructions on generating and encoding your credentials.

The privateKey value must be base64 encoded.

$curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
>--header 'Content-Type: application/json' \
>--data '{
>    "credentialType": "FCM",
>    "content": {
>        "privateKey": "your_key"
>    },
>    "appName": "test_app"
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Create APN credentials

To upload APN credentials to Twilio, make the request shown below. See Obtaining APN Credentials for detailed instructions on generating and encoding your credentials.

The certificate and privateKey values must be base64 encoded.

$curl -X POST 'https://comms.twilio.com/preview/PushNotifications/Credentials' \
>--header 'Content-Type: application/json' \
>--data '{
>    "credentialType": "APN",
>    "content": {
>        "certificate": "your_cert",
>        "privateKey": "your_key"
>    },
>    "appName": "test_app"
>}' \
>-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Send a notification

You can send a notification directly without storing it as a registration. In production use cases, you’ll either use DeviceRegistrations to store the token on a User, or you’ll manage registration on your own and use this method to send pushes.

In this request, the assumed from is the default App and its associated Credentials. If your default App does not have a Credential for FCM, the request shown below would not deliver a push notification.

Send to a single recipient

$curl -X POST 'https://comms.twilio.com/preview/PushNotifications' \
>--header 'Content-Type: application/json' \
>--data '{
>    "to": [
>        {
>            "token": "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. Use Liquid templating to personalize notifications for each recipient:

$curl -X POST 'https://comms.twilio.com/preview/PushNotifications' \
>--header 'Content-Type: application/json' \
>--data '{
>    "to": [
>        {
>            "token": "device_token",
>            "provider": "FCM",
>            "variables": {
>                "name": "Jessie"
>            }
>        },
>        {
>            "token": "utJXX2Tr9wN_tYOwYd8rFA6mYUMBFqdz9n6k3v5EpFAukXD89hGq",
>            "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