Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

PushNotifications resource

(new)

Beta

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(link takes you to an external page). 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.

A PushNotification resource represents a push notification sent through the Twilio Communications API. You can send notifications to Android devices, Apple devices, and web browsers through a single API.

You can send personalized notifications to up to 10,000 recipients in a single request, with a mix of APNs and FCM recipients.

When you send a notification, the API returns an operationId that you can use to track delivery status. See Operation resource for details.

(information)

Info

Records are available for 7 days after creation. Requests for data older than 7 days may return incomplete results.

PushNotification Properties

pushnotification-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
idstring
required
Not PII

A reference to a PushNotification.

Example: comms_pushnotification_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotification_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
fromPushNotificationCredentialSender
required
Not PII

For each supported provider, a Credential.Id can be provided.

Ensure that the Credential.credentialTypes of each Credential matches the name of the respective fields.

to
oneOf:
required
Not PII

The recipient of the Push Notification

priorityenum<string>

Optional

Not PII

The priority of the Push Notification. A value of "low" reduces the client app battery consumption. A value of "high" sends the notification immediately and can wake up a sleeping device.

Default: HIGHPossible values:
HIGHLOW
soundstring or null

Optional

Not PII

The name of the sound to be played for the push notification.

statusenum<string>
required
Not PII

The status of a Push Notification resource. The status can be one of the following:

  • scheduled The Push Notification is scheduled to be sent by Twilio in the future.

  • queued The Push Notification is queued in Twilio for sending.

  • sent The Push Notification resource has been sent by Twilio.

  • failed The Push Notification resource processing failed inside Twilio. Use GET /PushNotifications/Operations/{operationId}/Errors for more details.

  • canceled The communication resource was canceled via API request.

Possible values:
SCHEDULEDQUEUEDSENTFAILEDCANCELED
createdAtstring<date-time>
required
Not PII

The date and time when the Push Notification was created, in ISO 8601 format.

updatedAtstring<date-time>
required
Not PII

The date and time when the Push Notification was last updated, in ISO 8601 format.

PushNotification status values

pushnotification-status-values page anchor
StatusDescription
SCHEDULEDThe notification is scheduled for future delivery.
QUEUEDThe notification is queued for sending.
SENTThe notification was sent to the provider.
FAILEDThe notification failed during processing.
CANCELEDThe notification was canceled via the API.

Send a PushNotification

send-a-pushnotification page anchor

POST https://comms.twilio.com/v1/PushNotifications

Send a push notification to one or more recipients by making an HTTP POST request to the Notifications resource URI.

The to array accepts up to 10,000 recipients. Each recipient can be either a direct recipient (with a device token and provider) or a User recipient (with a userId). You can include both APN and FCM recipients in the same request.

You can personalize notification content for each recipient using LiquidJS templates. Pass recipient-specific variables in the variables object for each recipient.

Recipient types

recipient-types page anchor

You can address recipients in two ways:

  • Direct recipient: Provide a device token and provider (APN or FCM).
  • User recipient: Provide a userId referencing a User. The API delivers to all devices registered to that User.

From object

from-object page anchor

Use the optional from object to specify which credentials or app to use for sending. You can either:

  • Provide specific credential IDs with fcm and apn fields.
  • Provide an appName to use that app's default credentials.

If omitted, the API uses the default App and its associated credentials.

Schedule object

schedule-object page anchor

Use the optional schedule object to schedule notifications for future delivery. Provide an array of RFC 3339 datetime strings in the sendAt field. Notifications can be scheduled up to 7 days in the future.

Tags object

tags-object page anchor

Attach custom key-value metadata to notifications using the optional tags object. Tags support up to 10 pairs, with keys up to 128 characters and values up to 256 characters. Tags support Liquid templating.

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
from
oneOf:

Optional

Not PII

The sender of the Push Notification(s). Leave unspecified to automatically use the default App.

to
array(oneOf):
required
Not PII

A list of recipients to send the Push Notifications(s) to.

content
oneOf:
required
Not PII

The content of the Push Notification.

  • Use the Liquid(link takes you to an external page) templating language for personalization in any text-based field.

  • When using a templated content, use the variables field on each recipient to specify the values to substitute.

  • For each variable you specify in your template, you should have a matching key in each recipient's variables object.

priorityenum<string>

Optional

Not PII

The priority of the Push Notification. A value of "low" reduces the client app battery consumption. A value of "high" sends the notification immediately and can wake up a sleeping device.

Default: HIGHPossible values:
HIGHLOW
soundstring or null

Optional

Not PII

The name of the sound to be played for the Push Notification.

scheduleSchedule

Optional

Not PII

A schedule defines when a communication will be sent to a recipient.

Min properties: 1
tagsTags

Optional

Not PII

Custom metadata in the form of key-value pairs. Maximum size of a tag key is 128 characters. Maximum size of a tag value is 256 characters. There can be a maximum of 10 key-value pairs.

This field can be templated with Liquid(link takes you to an external page). Specify variables with each recipient for personalization.

Max properties: 10

Responses

responses page anchor
202400429500503

The request was accepted and an Operation was created to track its progress. The response body contains the ID and link to the Operation resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
operationIdstring

Optional

The Operation ID is an identifier that can be used to correlate all of the resources created in a request.

Issue a GET request to the resource list location, using the Operation ID as a query parameter to retrieve the resources that correlate with the Operation.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
operationLocationstring<uri>

Optional

The location (uri) of the Operation resource identified by operationId.

Send a PushNotificationLink to code sample: Send a PushNotification
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.send({

9
        from: {

10
            fcm: "comms_credential_01h9krwprkeee8fzqspvwy6nq8",

11
            apn: "comms_credential_8qn6ywvpsqzf8eeekrpwrk9h10",

12
        },

13
        to: [

14
            {

15
                token: "dqWD7WEC83K41WHyufTS7:APA91bFcrVaOLqKeJfSiEutJXX2Tr9wN_tYOwYd8rFA6mYUMBFqdz9n6k3v5EpFA_ukXD89hGqG3OarzbVfdjGnLOIAQfwbQcqJkjQWMrhwElrtU1y3JLDPfnjc0eTJLxzhyYvDFopEh",

16
                provider: "FCM",

17
            },

18
            {

19
                token: "utJXX2Tr9wN_tYOwYd8rFA6mYUMBFqdz9n6k3v5EpFAukXD89hGq",

20
                provider: "APN",

21
            },

22
        ],

23
        content: {

24
            title: "Boarding time @ TLL",

25
            body: "Dear customer, you have 1 hour until boarding time at the Tallinn airport",

26
        },

27
        priority: "HIGH",

28
        sound: "ring",

29
    });

30
}

31
main();

Fetch a PushNotification

fetch-a-pushnotification page anchor

GET https://comms.twilio.com/v1/PushNotifications/{pushNotificationId}

Retrieve a single PushNotification resource by making an HTTP GET request to the PushNotification resource URI with the PushNotification ID.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
pushNotificationIdstring
required
Not PII
Example: comms_pushnotification_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotification_[0-7][a-hjkmnpqrstv-z0-9]{25,34}

Responses

responses-1 page anchor
200400404429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
idstring

Optional

A reference to a PushNotification.

Example: comms_pushnotification_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotification_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
fromPushNotificationCredentialSender

Optional

For each supported provider, a Credential.Id can be provided.

Ensure that the Credential.credentialTypes of each Credential matches the name of the respective fields.

to
oneOf:

Optional

The recipient of the Push Notification

priorityenum<string>

Optional

The priority of the Push Notification. A value of "low" reduces the client app battery consumption. A value of "high" sends the notification immediately and can wake up a sleeping device.

Default: HIGHPossible values:
HIGHLOW
soundstring or null

Optional

The name of the sound to be played for the push notification.

statusenum<string>

Optional

The status of a Push Notification resource. The status can be one of the following:

  • scheduled The Push Notification is scheduled to be sent by Twilio in the future.

  • queued The Push Notification is queued in Twilio for sending.

  • sent The Push Notification resource has been sent by Twilio.

  • failed The Push Notification resource processing failed inside Twilio. Use GET /PushNotifications/Operations/{operationId}/Errors for more details.

  • canceled The communication resource was canceled via API request.

Possible values:
SCHEDULEDQUEUEDSENTFAILEDCANCELED
createdAtstring<date-time>

Optional

The date and time when the Push Notification was created, in ISO 8601 format.

updatedAtstring<date-time>

Optional

The date and time when the Push Notification was last updated, in ISO 8601 format.

content
oneOf:

Optional

The content of the Push Notification.

Fetch a PushNotificationLink to code sample: Fetch a PushNotification
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.fetch("comms_pushnotification_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();

List PushNotifications

list-pushnotifications page anchor

GET https://comms.twilio.com/v1/PushNotifications

Returns a list of Notifications. You can filter by operation ID, status, tags, date range, User, or provider.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
operationIdstring

Optional

Not PII

Filter Push Notifications by Operation ID.

Example: comms_operation_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
statusenum<string>

Optional

Not PII

Filter Push Notifications by Delivery Status.

Possible values:
SCHEDULEDQUEUEDSENTFAILEDCANCELED
tagsstring

Optional

Not PII

Match Push Notifications by one or many tags. If more than one tag is specified in the query, the search will return only results that have ALL the matching tags.

For Example:

GET /PushNotifications?tags=ageGroup:20s;industry:engineering;
Example: key_1:value;key_2:value;Pattern: ^(?:[a-zA-Z0-9._~-]+:[a-zA-Z0-9._~-]+;){1,10}$
startDatestring<date-time>

Optional

Not PII

Filter to Push Notifications created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter to Push Notifications created before the specified date and time.

userstring

Optional

Not PII

Filter Push Notifications sent to a specific User.

Example: comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_pushnotificationuser_[0-7][a-hjkmnpqrstv-z0-9]{25,34}
providerenum<string>

Optional

Not PII

Filter Push Notifications by provider.

Possible values:
APNFCM
pageTokenstring

Optional

Not PII

The token to retrieve the next page of results.

pageSizeinteger

Optional

Not PII

The number of resources to return in a page.

Default: 50Example: 50Minimum: 1Maximum: 1000

Responses

responses-2 page anchor
200400429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
pushNotificationsarray[PushNotificationMetadata]

Optional

paginationPaginationMetadata

Optional

Metadata for paginated results. This object contains two tokens to navigate through paginated results.

  • Use next to retrieve the 'next' page in the result list.
  • Use self to retrieve the same page of the result list again.
  • Supply the token in the pageToken query param.
List PushNotificationsLink to code sample: List PushNotifications
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.list({

9
        operationId: "comms_operation_01h9krwprkeee8fzqspvwy6nq8",

10
        status: "SCHEDULED",

11
        tags: "key_1:value;key_2:value;",

12
        startDate: new Date("2024-01-15T09:30:00Z"),

13
        endDate: new Date("2024-01-15T09:30:00Z"),

14
        user: "comms_pushnotificationuser_01h9krwprkeee8fzqspvwy6nq8",

15
        provider: "APN",

16
        pageToken: "pageToken",

17
        pageSize: 50,

18
    });

19
}

20
main();