Notification Resource
We are no longer allowing customers to onboard to Notify. We intend to deprecate the Notify product on April 25, 2024. Learn more in our Notify API End of Life Notice. We prepared this Transition Guide to assist in supporting your push notification use cases.
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
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
Resource Properties in REST API format | |
---|---|
sid
|
The unique string that we created to identify the Notification resource. |
account_sid
|
The SID of the Account that created the Notification resource. |
service_sid
|
The SID of the Service the resource is associated with. |
date_created
|
The date and time in GMT when the resource was created specified in RFC 2822 format. |
identities
|
The list of |
tags
|
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. |
segments
|
The list of Segments to notify. The Segment resource is deprecated. Use the |
priority
|
The priority of the notification. Can be: |
ttl
|
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. |
title
|
The notification title. For FCM and GCM, this translates to the |
body
|
The notification text. For FCM and GCM, translates to |
sound
|
The name of the sound to be played for the notification. For FCM and GCM, this Translates to |
action
|
The actions to display for the notification. For APNS, translates to the |
data
|
The custom key-value pairs of the notification's payload. For FCM and GCM, this value translates to |
apn
|
The APNS-specific payload that overrides corresponding attributes in the generic payload for APNS Bindings. This property maps to the APNS |
gcm
|
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 |
fcm
|
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 for more details. Target parameters |
sms
|
The SMS-specific payload that overrides corresponding attributes in the generic payload for SMS Bindings. Each attribute in this value maps to the corresponding |
facebook_messenger
|
Deprecated. |
alexa
|
Deprecated. |
Create a Notification resource
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
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.
- Example 1 shows how to send a notification to a Binding identified by its
identity
. - Example 2 shows how to send a notification to a Binding identified by its
tags
. - Example 3 shows how to send a notification to a Binding identified by its
identity
and itstags
.
Send a Notification to Bindings in the request
Set ToBinding
to the JSON object that defines the Bindings to notify.
- Example 4 shows how to send a notification to Bindings defined in the request.
Send a Notification tailored to the specific channel
Define channel-specific features in the request to tailor the notification to the channel.
- Example 5 below shows how to apply channel-specific features to customize the notification content to the channel.
Parameters
Parameters in REST API format | |
---|---|
service_sid
Path
|
The SID of the Service to create the resource under. |
body
Optional
|
The notification text. For FCM and GCM, translates to |
priority
Optional
|
The priority of the notification. Can be: |
ttl
Optional
|
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. |
title
Optional
|
The notification title. For FCM and GCM, this translates to the |
sound
Optional
|
The name of the sound to be played for the notification. For FCM and GCM, this Translates to |
action
Optional
|
The actions to display for the notification. For APNS, translates to the |
data
Optional
|
The custom key-value pairs of the notification's payload. For FCM and GCM, this value translates to |
apn
Optional
|
The APNS-specific payload that overrides corresponding attributes in the generic payload for APNS Bindings. This property maps to the APNS |
gcm
Optional
|
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 for more details. Target parameters |
sms
Optional
|
The SMS-specific payload that overrides corresponding attributes in the generic payload for SMS Bindings. Each attribute in this value maps to the corresponding |
facebook_messenger
Optional
|
Deprecated. |
fcm
Optional
|
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 for more details. Target parameters |
segment
Optional
|
The Segment resource is deprecated. Use the |
alexa
Optional
|
Deprecated. |
to_binding
Optional
|
The destination address specified as a JSON string. Multiple |
delivery_callback_url
Optional
|
URL to send webhooks. |
identity
Required if
tag
is not passed
|
The |
tag
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 |
Example 1
Example 2
Example 3
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.
Example 4
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 or Google 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.
Example 5
ToBinding attributes
Name | Description |
---|---|
binding_type | The channel to use. Possible values: sms , apn , fcm . |
address |
The 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
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. Example 5 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.
Example 5 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
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.
Channel | Error |
---|---|
APNS | APNS response status code 410 with error string "Unregistered" |
APNS | Address in invalid format |
FCM | Firebase response status code 200 + error:NotRegistered |
FCM | Firebase response status code 200 + error:InvalidRegistration |
FCM | Firebase response status code 200 + error:MismatchSenderId |
SMS | 21604 - 'To' phone number is blank |
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.