Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Notification Resource


The Notification resource sends a notification to existing Bindings or a list of addresses.

You can notify users over these channels:

  • APNS for iOS devices
  • FCM for Android devices
  • SMS and MMS
(warning)

Warning

Make sure you have consent from users before storing their device's address.

It's a good practice to obtain your end users' consent before you send them messages and some jurisdictions might require it by law.

We recommend that you consult with your legal counsel to make sure that your communications comply with all applicable laws.

To make sure your messages reach the right people, you should make sure that they have given you their consent to send them messages and that their contact information is current.

Check out the Twilio Marketplace for Add-ons from our partners that can help you keep your database up to date.


Notification Properties

notification-properties page anchor
Resource properties
sidtype: SID<NT>Not PII

The unique string that we created to identify the Notification resource.


service_sidtype: SID<IS>Not PII

The SID of the Service(link takes you to an external page) the resource is associated with.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in RFC 2822(link takes you to an external page) format.


identitiestype: string[]PII MTL: 120 days

The list of identity values of the Users to notify. We will attempt to deliver notifications only to Bindings with an identity in this list.


tagstype: string[]PII MTL: 120 days

The tags that select the Bindings to notify. Notifications will be attempted only to Bindings that have all of the tags listed in this property.


segmentstype: string[]Not PII

The list of Segments to notify. The Segment(link takes you to an external page) resource is deprecated. Use the tags property, instead.


prioritytype: enum<STRING>Not PII

The priority of the notification. Can be: low or high and the default is high. A value of low optimizes the client app's battery consumption; however, notifications may be delivered with unspecified delay. For FCM and GCM, low priority is the same as Normal priority. For APNS low priority is the same as 5. A value of high sends the notification immediately, and can wake up a sleeping device. For FCM and GCM, high is the same as High priority. For APNS, high is a priority 10. SMS does not support this property.

Possible values:
highlow

ttltype: integerNot PII

How long, in seconds, the notification is valid. Can be an integer between 0 and 2,419,200, which is 4 weeks, the default and the maximum supported time to live (TTL). Delivery should be attempted if the device is offline until the TTL elapses. Zero means that the notification delivery is attempted immediately, only once, and is not stored for future delivery. SMS does not support this property.


titletype: stringNot PII

The notification title. For FCM and GCM, this translates to the data.twi_title value. For APNS, this translates to the aps.alert.title value. SMS does not support this property. This field is not visible on iOS phones and tablets but appears on Apple Watch and Android devices.


bodytype: stringPII MTL: 0 days

The notification text. For FCM and GCM, translates to data.twi_body. For APNS, translates to aps.alert.body. For SMS, translates to body. SMS requires either this body value, or media_urls attribute defined in the sms parameter of the notification.


soundtype: stringNot PII

The name of the sound to be played for the notification. For FCM and GCM, this Translates to data.twi_sound. For APNS, this translates to aps.sound. SMS does not support this property.


actiontype: stringNot PII

The actions to display for the notification. For APNS, translates to the aps.category value. For GCM, translates to the data.twi_action value. For SMS, this parameter is not supported and is omitted from deliveries to those channels.


datatype: objectNot PII

The custom key-value pairs of the notification's payload. For FCM and GCM, this value translates to data in the FCM and GCM payloads. FCM and GCM reserve certain keys(link takes you to an external page) that cannot be used in those channels. For APNS, attributes of data are inserted into the APNS payload as custom properties outside of the aps dictionary. In all channels, we reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed and are rejected as 400 Bad request with no delivery attempted. For SMS, this parameter is not supported and is omitted from deliveries to those channels.


apntype: objectNot PII

The APNS-specific payload that overrides corresponding attributes in the generic payload for APNS Bindings. This property maps to the APNS Payload item, therefore the aps key must be used to change standard attributes. Adds custom key-value pairs to the root of the dictionary. See the APNS documentation(link takes you to an external page) for more details. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed.


gcmtype: objectNot PII

The GCM-specific payload that overrides corresponding attributes in the generic payload for GCM Bindings. This property maps to the root JSON dictionary. Target parameters to, registration_ids, and notification_key are not allowed. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed.


fcmtype: objectNot PII

The FCM-specific payload that overrides corresponding attributes in the generic payload for FCM Bindings. This property maps to the root JSON dictionary. See the FCM documentation(link takes you to an external page) for more details. Target parameters to, registration_ids, condition, and notification_key are not allowed in this parameter. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed. FCM also reserves certain keys(link takes you to an external page), which cannot be used in that channel.


smstype: objectNot PII

The SMS-specific payload that overrides corresponding attributes in the generic payload for SMS Bindings. Each attribute in this value maps to the corresponding form parameter of the Twilio Message(link takes you to an external page) resource. These parameters of the Message resource are supported in snake case format: body, media_urls, status_callback, and max_price. The status_callback parameter overrides the corresponding parameter in the messaging service, if configured. The media_urls property expects a JSON array.


facebook_messengertype: objectNot PII

Deprecated.


alexatype: objectNot PII

Deprecated.


Create a Notification resource

create-a-notification-resource page anchor
POST https://notify.twilio.com/v1/Services/{ServiceSid}/Notifications

Creating a Notification resource sends a notification to existing Bindings or to addresses provided in the request.

Send a Notification to existing Bindings

send-a-notification-to-existing-bindings page anchor

Set Identity or Tag to specify the stored Bindings to notify. To notify all available stored Bindings, set Tag to all. If both Identity and Tag have values, only the Bindings that match both will be notified.

Check out the below examples which show you how to

Send a Notification to Bindings in the request

send-a-notification-to-bindings-in-the-request page anchor

Set ToBinding to the JSON object that defines the Bindings to notify. Check out the below example which shows you how to

Send a Notification tailored to the specific channel

send-a-notification-tailored-to-the-specific-channel page anchor

Define channel-specific features in the request to tailor the notification to the channel. Check out the below example

Parameters

create-parameters page anchor
URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to create the resource under.


Request body parameters
Bodytype: stringPII MTL: 0 days

The notification text. For FCM and GCM, translates to data.twi_body. For APNS, translates to aps.alert.body. For SMS, translates to body. SMS requires either this body value, or media_urls attribute defined in the sms parameter of the notification.


Prioritytype: enum<STRING>Not PII

The priority of the notification. Can be: low or high and the default is high. A value of low optimizes the client app's battery consumption; however, notifications may be delivered with unspecified delay. For FCM and GCM, low priority is the same as Normal priority. For APNS low priority is the same as 5. A value of high sends the notification immediately, and can wake up a sleeping device. For FCM and GCM, high is the same as High priority. For APNS, high is a priority 10. SMS does not support this property.

Possible values:
highlow

Ttltype: integerNot PII

How long, in seconds, the notification is valid. Can be an integer between 0 and 2,419,200, which is 4 weeks, the default and the maximum supported time to live (TTL). Delivery should be attempted if the device is offline until the TTL elapses. Zero means that the notification delivery is attempted immediately, only once, and is not stored for future delivery. SMS does not support this property.


Titletype: stringNot PII

The notification title. For FCM and GCM, this translates to the data.twi_title value. For APNS, this translates to the aps.alert.title value. SMS does not support this property. This field is not visible on iOS phones and tablets but appears on Apple Watch and Android devices.


Soundtype: stringNot PII

The name of the sound to be played for the notification. For FCM and GCM, this Translates to data.twi_sound. For APNS, this translates to aps.sound. SMS does not support this property.


Actiontype: stringNot PII

The actions to display for the notification. For APNS, translates to the aps.category value. For GCM, translates to the data.twi_action value. For SMS, this parameter is not supported and is omitted from deliveries to those channels.


Datatype: objectNot PII

The custom key-value pairs of the notification's payload. For FCM and GCM, this value translates to data in the FCM and GCM payloads. FCM and GCM reserve certain keys(link takes you to an external page) that cannot be used in those channels. For APNS, attributes of data are inserted into the APNS payload as custom properties outside of the aps dictionary. In all channels, we reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed and are rejected as 400 Bad request with no delivery attempted. For SMS, this parameter is not supported and is omitted from deliveries to those channels.


Apntype: objectNot PII

The APNS-specific payload that overrides corresponding attributes in the generic payload for APNS Bindings. This property maps to the APNS Payload item, therefore the aps key must be used to change standard attributes. Adds custom key-value pairs to the root of the dictionary. See the APNS documentation(link takes you to an external page) for more details. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed.


Gcmtype: objectNot PII

The GCM-specific payload that overrides corresponding attributes in the generic payload for GCM Bindings. This property maps to the root JSON dictionary. See the GCM documentation(link takes you to an external page) for more details. Target parameters to, registration_ids, and notification_key are not allowed. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed. GCM also reserves certain keys(link takes you to an external page).


Smstype: objectNot PII

The SMS-specific payload that overrides corresponding attributes in the generic payload for SMS Bindings. Each attribute in this value maps to the corresponding form parameter of the Twilio Message(link takes you to an external page) resource. These parameters of the Message resource are supported in snake case format: body, media_urls, status_callback, and max_price. The status_callback parameter overrides the corresponding parameter in the messaging service, if configured. The media_urls property expects a JSON array.


FacebookMessengertype: objectNot PII

Deprecated.


Fcmtype: objectNot PII

The FCM-specific payload that overrides corresponding attributes in the generic payload for FCM Bindings. This property maps to the root JSON dictionary. See the FCM documentation(link takes you to an external page) for more details. Target parameters to, registration_ids, condition, and notification_key are not allowed in this parameter. We reserve keys that start with twi_ for future use. Custom keys that start with twi_ are not allowed. FCM also reserves certain keys(link takes you to an external page), which cannot be used in that channel.


Segmenttype: string[]Not PII

The Segment resource is deprecated. Use the tag parameter, instead.


Alexatype: objectNot PII

Deprecated.


ToBindingtype: string[]Not PII

The destination address specified as a JSON string. Multiple to_binding parameters can be included but the total size of the request entity should not exceed 1MB. This is typically sufficient for 10,000 phone numbers.


DeliveryCallbackUrltype: stringNot PII

URL to send webhooks.


Identitytype: string[]Not PII
Required if Tag is not passed

The identity value that uniquely identifies the new resource's User(link takes you to an external page) within the Service(link takes you to an external page). Delivery will be attempted only to Bindings with an Identity in this list. No more than 20 items are allowed in this list.


Tagtype: string[]Not PII
Required if Identity is not passed

A tag that selects the Bindings to notify. Repeat this parameter to specify more than one tag, up to a total of 5 tags. The implicit tag all is available to notify all Bindings in a Service instance. Similarly, the implicit tags apn, fcm, gcm, sms and facebook-messenger are available to notify all Bindings in a specific channel.

Send a Notification to existing Bindings (Identity)

send-a-notification-to-existing-bindings-identity page anchor

Send to an existing Binding identified by its Identity

Node.js
Python
C#
Java
PHP
Ruby
curl

_24
// NOTE: This example uses the next generation Twilio helper library - for more
_24
// information on how to download and install this version, visit
_24
// https://www.twilio.com/docs/libraries/node
_24
// To set up environmental variables, see http://twil.io/secure
_24
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_24
const authToken = process.env.TWILIO_AUTH_TOKEN;
_24
const Twilio = require('twilio');
_24
_24
const client = new Twilio(accountSid, authToken);
_24
_24
const service = client.notify.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
_24
_24
service.notifications
_24
.create({
_24
identity: '00000001',
_24
body: 'Hello Bob',
_24
})
_24
.then(notification => {
_24
console.log(notification);
_24
})
_24
.catch(error => {
_24
console.log(error);
_24
})
_24
.done();

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"sid": "NTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"date_created": "2015-08-26T00:07:12Z",
_19
"identities": ["00000001"],
_19
"tags": [],
_19
"priority": "high",
_19
"ttl": 2419200,
_19
"title": null,
_19
"body": "Hello Bob",
_19
"sound": null,
_19
"action": null,
_19
"data": null,
_19
"apn": null,
_19
"gcm": null,
_19
"sms": null,
_19
"fcm": null
_19
}

Send a Notification to existing Bindings (Tag)

send-a-notification-to-existing-bindings-tag page anchor

Send to an existing Binding identified by its Tag

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.notifications
_11
.create({tag: ['new_user'], body: `"Hello new user!"`})
_11
.then(notification => console.log(notification.sid));

Output

_24
{
_24
"sid": "NTb8021351170b4e1286adaac3fdd6d082",
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"date_created": "2016-03-24T23:42:28Z",
_24
"identities": [
_24
"jing"
_24
],
_24
"tags": [],
_24
"segments": [],
_24
"priority": "high",
_24
"ttl": 2419200,
_24
"title": "test",
_24
"body": "\"Hello new user!\"",
_24
"sound": null,
_24
"action": null,
_24
"data": null,
_24
"apn": null,
_24
"fcm": null,
_24
"gcm": null,
_24
"sms": null,
_24
"facebook_messenger": null,
_24
"alexa": null
_24
}

Send a Notification to existing Bindings (Identity and Tag)

send-a-notification-to-existing-bindings-identity-and-tag page anchor

Send to existing Bindings identified by their Identity and Tags

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.notifications
_15
.create({
_15
identity: ['00000001'],
_15
tag: ['preferred_device'],
_15
body: `"Hello, Charlie!"`
_15
})
_15
.then(notification => console.log(notification.sid));

Output

_24
{
_24
"sid": "NTb8021351170b4e1286adaac3fdd6d082",
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"date_created": "2016-03-24T23:42:28Z",
_24
"identities": [
_24
"jing"
_24
],
_24
"tags": [],
_24
"segments": [],
_24
"priority": "high",
_24
"ttl": 2419200,
_24
"title": "test",
_24
"body": "\"Hello, Charlie!\"",
_24
"sound": null,
_24
"action": null,
_24
"data": null,
_24
"apn": null,
_24
"fcm": null,
_24
"gcm": null,
_24
"sms": null,
_24
"facebook_messenger": null,
_24
"alexa": null
_24
}

(information)

Info

You can send notifications to addresses without storing them by using the toBinding parameter. However, the total size of the request entity shouldn't exceed 1MB. This is typically sufficient for 10,000 phone numbers.

Send a Notification to Bindings in the request

send-a-notification-to-bindings-in-the-request-1 page anchor

Create temporary Bindings in the request using the ToBinding attributes described below.

Node.js
Python
C#
Java
PHP
Ruby
curl

_33
// NOTE: This example uses the next generation Twilio helper library - for more
_33
// information on how to download and install this version, visit
_33
// https://www.twilio.com/docs/libraries/node
_33
// To set up environmental variables, see http://twil.io/secure
_33
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_33
const authToken = process.env.TWILIO_AUTH_TOKEN;
_33
const Twilio = require('twilio');
_33
_33
const client = new Twilio(accountSid, authToken);
_33
_33
const service = client.notify.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
_33
_33
service.notifications
_33
.create({
_33
toBinding: [
_33
JSON.stringify({
_33
binding_type: 'sms',
_33
address: '+15555555555',
_33
}),
_33
JSON.stringify({
_33
binding_type: 'facebook-messenger',
_33
address: '123456789123',
_33
}),
_33
],
_33
body: 'Hello Bob',
_33
})
_33
.then(notification => {
_33
console.log(notification);
_33
})
_33
.catch(error => {
_33
console.log(error);
_33
})
_33
.done();

Output

_26
{
_26
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"sid": "NTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26
"date_created": "2015-08-26T00:07:12Z",
_26
"toBindings": [{
_26
"binding_type":"sms",
_26
"address":"+15555555555"
_26
},{
_26
"binding_type":"facebook-messenger",
_26
"address":"123456789123"
_26
}],
_26
"identities": [],
_26
"tags": [],
_26
"priority": "high",
_26
"ttl": 2419200,
_26
"title": null,
_26
"body": "Hello Bob",
_26
"sound": null,
_26
"action": null,
_26
"data": null,
_26
"apn": null,
_26
"gcm": null,
_26
"sms": null,
_26
"fcm": null
_26
}

(information)

Info

There is a list of available keys for building notification messages for iOS and Android. You can pass any of the available keys forApple(link takes you to an external page) orGoogle(link takes you to an external page) on the APNs or FCM parameters. You can also combine these (as well as the sms key) all in the same Notification API request, as shown in the Send custom notifications by channel code sample.

Send custom notifications by channel

send-custom-notifications-by-channel page anchor

Configure the notification by channel in the request

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_32
// Download the helper library from https://www.twilio.com/docs/node/install
_32
// Find your Account SID and Auth Token at twilio.com/console
_32
// and set the environment variables. See http://twil.io/secure
_32
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_32
const authToken = process.env.TWILIO_AUTH_TOKEN;
_32
const client = require('twilio')(accountSid, authToken);
_32
_32
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_32
.notifications
_32
.create({
_32
apn: {
_32
aps: {
_32
alert: {
_32
title: 'Short title for Watch.'
_32
}
_32
}
_32
},
_32
body: 'This is the body for all Bindings',
_32
data: {
_32
custom_key1: 'custom value 1',
_32
custom_key2: 'custom value 2'
_32
},
_32
fcm: {
_32
notification: {
_32
title: 'New alert',
_32
body: 'Hello Bob!'
_32
}
_32
},
_32
identity: ['00000001'],
_32
title: 'Generic loooooooong title for all Bindings'
_32
})
_32
.then(notification => console.log(notification.sid));

Output

_38
{
_38
"sid": "NTb8021351170b4e1286adaac3fdd6d082",
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"date_created": "2016-03-24T23:42:28Z",
_38
"identities": [
_38
"jing"
_38
],
_38
"tags": [],
_38
"segments": [],
_38
"priority": "high",
_38
"ttl": 2419200,
_38
"title": "Generic loooooooong title for all Bindings",
_38
"body": "This is the body for all Bindings",
_38
"sound": null,
_38
"action": null,
_38
"data": {
_38
"custom_key1": "custom value 1",
_38
"custom_key2": "custom value 2"
_38
},
_38
"apn": {
_38
"aps": {
_38
"alert": {
_38
"title": "Short title for Watch."
_38
}
_38
}
_38
},
_38
"fcm": {
_38
"notification": {
_38
"title": "New alert",
_38
"body": "Hello Bob!"
_38
}
_38
},
_38
"gcm": null,
_38
"sms": null,
_38
"facebook_messenger": null,
_38
"alexa": null
_38
}

NameDescription
binding_typeThe channel to use. Possible values: sms, apn, fcm.
addressThe destination address. For SMS, it is the phone number in E.164 format. For APNS and FCM, it is the device or registration token.

Customize notification by channel

customize-notification-by-channel page anchor

Notifications can be tailored to each notification channel to take advantage of channel-specific features or to customize the content to each channel.

The channel-specific payload of a notification can be provided by adding a parameter whose name is the BindingType and the value is the channel specific payload in a JSON object. The example Send custom notifications by channel includes several such objects.

These channels support channel-specific payloads:

  • APNS
  • FCM
  • SMS

The channel-specific content specified in this parameter can add a new property for the channel or replace the value in an existing property, but it cannot remove a property.

The example Send custom notifications by channel sends a notification to all Bindings with Identity 00000001. A generic Title is specified and will be used for sms binding and specifically for fcm and apn binding types a payload with title and body are also added, which will override the generic Title.

Unrecoverable channel errors

unrecoverable-channel-errors page anchor

When the underlying notification channel indicates an unrecoverable error, it is usually because there's a problem with the Binding. To ensure your database contains only valid Bindings, we delete the Bindings that return unrecoverable errors.

The following errors are unrecoverable.

ChannelError
APNSAPNS response status code 410 with error string "Unregistered"
APNSAddress in invalid format
FCMFirebase response status code 200 + error
FCMFirebase response status code 200 + error
FCMFirebase response status code 200 + error
SMS21604 - 'To' phone number is blank

Rate this page: