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

Notify Notification resource

(error)

Twilio Notify deprecated

Twilio stopped supporting Notify in October 2022.

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

You can notify users over these channels:

  • Apple Push Notification service (APNS) for iOS devices
  • Firebase Cloud Messaging (FCM) for Android devices
  • SMS and MMS
(warning)

Get user consent before messaging

Many jurisdictions require the affirmative consent of their recipients before sending them messages. To follow these regulations, let recipients choose to receive or not receive your messages.

Notification Properties

notification-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
sidSID<NT>

Optional

Not PII

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

Pattern: ^NT[0-9a-fA-F]{32}$Min length: 34Max length: 34
accountSidSID<AC>

Optional

Not PII

The SID of the Account that created the Notification resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
serviceSidSID<IS>

Optional

Not PII

The SID of the Service the resource is associated with.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34
dateCreatedstring<date-time>

Optional

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.

identitiesarray[string]

Optional

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.

tagsarray[string]

Optional

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.

segmentsarray[string]

Optional

Not PII

The list of Segments to notify. The Segment resource is deprecated. Use the tags property, instead.

priorityenum<string>

Optional

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
ttlinteger

Optional

Not 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.

Default: 0
titlestring

Optional

Not 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.

bodystring

Optional

PII 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.

soundstring

Optional

Not 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.

actionstring

Optional

Not 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.

data

Optional

Not 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.

apn

Optional

Not 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.

gcm

Optional

Not 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.

fcm

Optional

Not 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.

sms

Optional

Not 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 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.

facebookMessenger

Optional

Not PII

Deprecated.

alexa

Optional

Not 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
  • To specify the stored Bindings to Notify, set an Identity or a Tag.
  • To notify all available stored Bindings, set Tag to all.
  • If both Identity and Tag have values, Twilio notifies the Bindings that match both values.

To send notifications to an existing Binding, consider the following examples:

Send a Notification to Bindings in the request

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

Set the ToBinding property value to the JSON object that defines the Bindings for Notify. To learn more, see the send a notification to Bindings defined in the request example.

Send a Notification tailored to the specific channel

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

To tailor the notification to the channel, define channel-specific features in the request. To customize the notification content to the channel, see Send custom notifications by channel.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<IS>
required
Not PII

The SID of the Service to create the resource under.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
bodystring

Optional

PII 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.

priorityenum<string>

Optional

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
ttlinteger

Optional

Not 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.

titlestring

Optional

Not 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.

soundstring

Optional

Not 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.

actionstring

Optional

Not 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.

data

Optional

Not 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.

apn

Optional

Not 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.

gcm

Optional

Not 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).

sms

Optional

Not 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 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.

facebookMessenger

Optional

Not PII

Deprecated.

fcm

Optional

Not 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.

segmentarray[string]

Optional

Not PII

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

alexa

Optional

Not PII

Deprecated.

toBindingarray[string]

Optional

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.

deliveryCallbackUrlstring

Optional

Not PII

URL to send webhooks.

identityarray[string]
required if Tag is not passed
Not PII

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

tagarray[string]
required if Identity is not passed
Not PII

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)Link to code sample: Send a Notification to existing Bindings (Identity)
1
// NOTE: This example uses the next generation Twilio helper library - for more

2
// information on how to download and install this version, visit

3
// https://www.twilio.com/docs/libraries/node

4
// To set up environmental variables, see http://twil.io/secure

5
const accountSid = process.env.TWILIO_ACCOUNT_SID;

6
const authToken = process.env.TWILIO_AUTH_TOKEN;

7
const Twilio = require('twilio');

8


9
const client = new Twilio(accountSid, authToken);

10


11
const service = client.notify.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');

12


13
service.notifications

14
  .create({

15
    identity: '00000001',

16
    body: 'Hello Bob',

17
  })

18
  .then((notification) => {

19
    console.log(notification);

20
  })

21
  .catch((error) => {

22
    console.log(error);

23
  })

24
  .done();

Output

1
{

2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "sid": "NTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

4
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "date_created": "2015-08-26T00:07:12Z",

6
  "identities": ["00000001"],

7
  "tags": [],

8
  "priority": "high",

9
  "ttl": 2419200,

10
  "title": null,

11
  "body": "Hello Bob",

12
  "sound": null,

13
  "action": null,

14
  "data": null,

15
  "apn": null,

16
  "gcm": null,

17
  "sms": null,

18
  "fcm": null

19
}
Send a Notification to existing Bindings (Tag)Link to code sample: Send a Notification to existing Bindings (Tag)
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createNotification() {

11
  const notification = await client.notify.v1

12
    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .notifications.create({

14
      body: '"Hello new user!"',

15
      tag: ["new_user"],

16
    });

17


18
  console.log(notification.sid);

19
}

20


21
createNotification();

Response

Note about this response
1
{

2
  "sid": "NTb8021351170b4e1286adaac3fdd6d082",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "date_created": "2016-03-24T23:42:28Z",

6
  "identities": [

7
    "jing"

8
  ],

9
  "tags": [],

10
  "segments": [],

11
  "priority": "high",

12
  "ttl": 2419200,

13
  "title": "test",

14
  "body": "\"Hello new user!\"",

15
  "sound": null,

16
  "action": null,

17
  "data": null,

18
  "apn": null,

19
  "fcm": null,

20
  "gcm": null,

21
  "sms": null,

22
  "facebook_messenger": null,

23
  "alexa": null

24
}
Send a Notification to existing Bindings (Identity and Tag)Link to code sample: Send a Notification to existing Bindings (Identity and Tag)
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createNotification() {

11
  const notification = await client.notify.v1

12
    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .notifications.create({

14
      body: '"Hello, Charlie!"',

15
      identity: ["00000001"],

16
      tag: ["preferred_device"],

17
    });

18


19
  console.log(notification.sid);

20
}

21


22
createNotification();

Response

Note about this response
1
{

2
  "sid": "NTb8021351170b4e1286adaac3fdd6d082",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "date_created": "2016-03-24T23:42:28Z",

6
  "identities": [

7
    "jing"

8
  ],

9
  "tags": [],

10
  "segments": [],

11
  "priority": "high",

12
  "ttl": 2419200,

13
  "title": "test",

14
  "body": "\"Hello, Charlie!\"",

15
  "sound": null,

16
  "action": null,

17
  "data": null,

18
  "apn": null,

19
  "fcm": null,

20
  "gcm": null,

21
  "sms": null,

22
  "facebook_messenger": null,

23
  "alexa": null

24
}

To send notifications to addresses without storing them, include the toBinding parameter. The total size of the request entity shouldn't exceed 1 MB. This should cover about 10,000 phone numbers.

Send a Notification to Bindings in the requestLink to code sample: Send a Notification to Bindings in the request
1
// NOTE: This example uses the next generation Twilio helper library - for more

2
// information on how to download and install this version, visit

3
// https://www.twilio.com/docs/libraries/node

4
// To set up environmental variables, see http://twil.io/secure

5
const accountSid = process.env.TWILIO_ACCOUNT_SID;

6
const authToken = process.env.TWILIO_AUTH_TOKEN;

7
const Twilio = require('twilio');

8


9
const client = new Twilio(accountSid, authToken);

10


11
const service = client.notify.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');

12


13
service.notifications

14
  .create({

15
    toBinding: [

16
      JSON.stringify({

17
        binding_type: 'sms',

18
        address: '+15555555555',

19
      }),

20
      JSON.stringify({

21
        binding_type: 'facebook-messenger',

22
        address: '123456789123',

23
      }),

24
    ],

25
    body: 'Hello Bob',

26
  })

27
  .then((notification) => {

28
    console.log(notification);

29
  })

30
  .catch((error) => {

31
    console.log(error);

32
  })

33
  .done();

Output

1
{

2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "sid": "NTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

4
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "date_created": "2015-08-26T00:07:12Z",

6
  "toBindings": [{

7
      "binding_type":"sms",

8
      "address":"+15555555555"

9
    },{

10
      "binding_type":"facebook-messenger",

11
      "address":"123456789123"

12
    }],

13
  "identities": [],

14
  "tags": [],

15
  "priority": "high",

16
  "ttl": 2419200,

17
  "title": null,

18
  "body": "Hello Bob",

19
  "sound": null,

20
  "action": null,

21
  "data": null,

22
  "apn": null,

23
  "gcm": null,

24
  "sms": null,

25
  "fcm": null

26
}

There is a list of available keys for building notification messages for iOS and Android. You can pass any of the available keys for Apple(link takes you to an external page) or Google(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 channelLink to code sample: Send custom notifications by channel
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createNotification() {

11
  const notification = await client.notify.v1

12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .notifications.create({

14
      apn: {

15
        aps: {

16
          alert: {

17
            title: "Short title for Watch.",

18
          },

19
        },

20
      },

21
      body: "This is the body for all Bindings",

22
      data: {

23
        custom_key1: "custom value 1",

24
        custom_key2: "custom value 2",

25
      },

26
      fcm: {

27
        notification: {

28
          title: "New alert",

29
          body: "Hello Bob!",

30
        },

31
      },

32
      identity: ["00000001"],

33
      title: "Generic loooooooong title for all Bindings",

34
    });

35


36
  console.log(notification.sid);

37
}

38


39
createNotification();

Response

Note about this response
1
{

2
  "sid": "NTb8021351170b4e1286adaac3fdd6d082",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "date_created": "2016-03-24T23:42:28Z",

6
  "identities": [

7
    "jing"

8
  ],

9
  "tags": [],

10
  "segments": [],

11
  "priority": "high",

12
  "ttl": 2419200,

13
  "title": "Generic loooooooong title for all Bindings",

14
  "body": "This is the body for all Bindings",

15
  "sound": null,

16
  "action": null,

17
  "data": {

18
    "custom_key1": "custom value 1",

19
    "custom_key2": "custom value 2"

20
  },

21
  "apn": {

22
    "aps": {

23
      "alert": {

24
        "title": "Short title for Watch."

25
      }

26
    }

27
  },

28
  "fcm": {

29
    "notification": {

30
      "title": "New alert",

31
      "body": "Hello Bob!"

32
    }

33
  },

34
  "gcm": null,

35
  "sms": null,

36
  "facebook_messenger": null,

37
  "alexa": null

38
}

ToBinding attributes

tobinding-attributes page anchor
NameDescriptionAccepted values
binding_typeThe channel to use.sms, apn, fcm
addressThe destination address.SMS uses a phone number in E.164 format. APNS uses a device token. FCM uses a registration token.

Customize notification by channel

customize-notification-by-channel page anchor

To use channel-specific features or customize the channel content, tailor the notification to the channel.

To provide the channel-specific payload of a notification, add the BindingType parameter with a value containing the channel specific payload in a JSON object. To see example objects, see Send custom notifications by channel.

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 Send custom notifications by channel example sends a notification to all Bindings with Identity 00000001. Binding to sms add a generic title. The fcm and apn Bindings add a payload with title and body.

Unrecoverable channel errors

unrecoverable-channel-errors page anchor

When the underlying notification channel indicates an unrecoverable error, the usual culprit involves the Binding. To ensure your database contains only valid Bindings, Twilio deletes the Bindings that return unrecoverable errors.

Your app can't recover from the following errors:

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