メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Notification Resource

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

You can notify users over these channels:

  • APNS (iOS デバイス)
  • Androidデバイス用のFCMおよびGCM
  • SMSとMMS
  • Facebook Messenger

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

Names in PHP format
sid
sid<NO> Not PII

accountSid
sid<AC> Not PII

serviceSid
sid<IS> Not PII

dateCreated
date_time<iso8601> Not PII

identities

Delivery will be attempted only to Bindings with an Identity in this list.

tags

Delivery will be attempted only to Bindings that have all of the Tags in this list.

segments
string[] Not PII

priority
enum:priority Not PII

Two priorities defined: low and high (default). low optimizes the client app's battery consumption, and notifications may be delivered with unspecified delay. This is the same as Normal priority for FCM and GCM or priority 5 for APNS. high sends the notification immediately, and can wake up a sleeping device. This is the same as High priority for FCM and GCM or priority 10 for APNS. This feature is not supported by SMS and Facebook Messenger and will be ignored for deliveries via those channels.

ttl
integer Not PII

This parameter specifies how long (in seconds) the notification is valid. Delivery should be attempted if the device is offline. The maximum time to live supported is 4 weeks. The value zero means that the notification delivery is attempted immediately once but not stored for future delivery. The default value is 4 weeks. This feature is not supported by SMS and Facebook Messenger and will be ignored for deliveries via those channels.

title
文字列 Not PII

Indicates the notification title. This field is not visible on iOS phones and tablets but it is on Apple Watch and Android devices. Translates to data.twi_title for FCM and GCM, aps.alert.title for APNS and displayInfo.content[0].title, displayInfo.content[].toast.primaryText of request.message for Alexa. It is not supported for SMS and Facebook Messenger and will be omitted from deliveries via those channels.

body
文字列 PII MTL: 0 DAYS

Indicates the notification body text. Translates to data.twi_body for FCM and GCM, aps.alert.body for APNS, Body for SMS and Facebook Messenger and request.message.data for Alexa. For SMS either this, body, or the media_url attribute of the Sms parameter is required. For Facebook Messenger either this parameter or the body attribute in the FacebookMessenger parameter is required.

sound
文字列 Not PII

Indicates a sound to be played. Translates to data.twi_sound for FCM and GCM and aps.sound for APNS. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

action
文字列 Not PII

Specifies the actions to be displayed for the notification. Translates to data.twi_action for GCM and aps.category for APNS. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

data
オブジェクト Not PII

This parameter specifies the custom key-value pairs of the notification's payload. Translates to data dictionary in FCM and GCM payload. FCM and GCM reserves certain keys that cannot be used for those channels. For APNS, attributes of Data will be inserted into the APNS payload as custom properties outside of the aps dictionary. For Alexa they are added to request.message.data. For all channels, the twi_ prefix is reserved for Twilio for future use. Requests including custom data with keys starting with twi_ will be rejected as 400 Bad request and no delivery will be attempted. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

apn
オブジェクト Not PII

APNS specific payload that overrides corresponding attributes in a generic payload for Bindings with the apn BindingType. This value is mapped to the Payload item, therefore the aps key has to be used to change standard attributes. Adds custom key-value pairs to the root of the dictionary. Refer to APNS documentation for more details. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed.

gcm
オブジェクト Not PII

GCM specific payload that overrides corresponding attributes in generic payload for Bindings with gcm BindingType. This value is mapped to the root json dictionary. Refer to GCM documentation for more details. Target parameters to, registration_ids, and notification_key are not allowed. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed. FCM and GCM reserves certain keys that cannot be used for those channels.

fcm
オブジェクト Not PII

FCM specific payload that overrides corresponding attributes in generic payload for Bindings with fcm BindingType. This value is mapped to the root json dictionary. Refer to FCM documentation for more details. Target parameters to, registration_ids, condition, and notification_key are not allowed. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed. Custom data with keys starting with twi_ is not allowed. FCM and GCM reserves certain keys that cannot be used for those channels.

sms
オブジェクト Not PII

SMS specific payload that overrides corresponding attributes in generic payload for Bindings with sms BindingType. Each attribute in this JSON object is mapped to the corresponding form parameter of the Twilio Message resource. The following 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 expects a JSON array.

facebookMessenger
オブジェクト Not PII

Messenger specific payload that overrides corresponding attributes in generic payload for Bindings with facebook-messenger BindingType. This value is mapped to the root json dictionary of Facebook's Send API request. Overriding the recipient parameter is not allowed.

alexa
オブジェクト Not PII

Create a Notification resource

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

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 its tags.

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

See Customize notification content by channel below for how to apply channel-specific features or customize the notification content.

パラメーター
Names in None format
identity
Required if tag is not passed
post string[] Not PII

Delivery will be attempted only to Bindings with an Identity in this list. Maximum 20 items allowed in this list.

tag
Required if identity is not passed
post string[] Not PII

Delivery will be attempted only to Bindings that have all of the Tags in this list. Maximum 5 items allowed in this list. 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 of the given type.

body
オプション
post 文字列 PII MTL: 0 DAYS

(optional for all except Alexa) Indicates the notification body text. Translates to data.twi_body for FCM and GCM, aps.alert.body for APNS, Body for SMS and Facebook Messenger and request.message.data for Alexa. For SMS either this, body, or the media_url attribute of the Sms parameter is required. For Facebook Messenger either this parameter or the body attribute in the FacebookMessenger parameter is required.

priority
オプション
post enum:priority Not PII

Two priorities defined: low and high (default). low optimizes the client app's battery consumption, and notifications may be delivered with unspecified delay. This is the same as Normal priority for FCM and GCM or priority 5 for APNS. high sends the notification immediately, and can wake up a sleeping device. This is the same as High priority for FCM and GCM or priority 10 for APNS. This feature is not supported by SMS and Facebook Messenger and will be ignored for deliveries via those channels.

ttl
オプション
post integer Not PII

This parameter specifies how long (in seconds) the notification is valid. Delivery should be attempted if the device is offline. The maximum time to live supported is 4 weeks. The value zero means that the notification delivery is attempted immediately once but not stored for future delivery. The default value is 4 weeks. This feature is not supported by SMS and Facebook Messenger and will be ignored for deliveries via those channels.

title
オプション
post 文字列 Not PII

(optional for all except Alexa) Indicates the notification title. This field is not visible on iOS phones and tablets but it is on Apple Watch and Android devices. Translates to data.twi_title for FCM and GCM, aps.alert.title for APNS and displayInfo.content[0].title, displayInfo.content[].toast.primaryText of request.message for Alexa. It is not supported for SMS and Facebook Messenger and will be omitted from deliveries via those channels.

sound
オプション
post 文字列 Not PII

Indicates a sound to be played. Translates to data.twi_sound for FCM and GCM and aps.sound for APNS. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

action
オプション
post 文字列 Not PII

Specifies the actions to be displayed for the notification. Translates to data.twi_action for GCM and aps.category for APNS. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

data
オプション
post オブジェクト Not PII

This parameter specifies the custom key-value pairs of the notification's payload. Translates to data dictionary in FCM and GCM payload. FCM and GCM reserves certain keys that cannot be used for those channels. For APNS, attributes of Data will be inserted into the APNS payload as custom properties outside of the aps dictionary. For Alexa they are added to request.message.data. For all channels, the twi_ prefix is reserved for Twilio for future use. Requests including custom data with keys starting with twi_ will be rejected as 400 Bad request and no delivery will be attempted. This parameter is not supported by SMS and Facebook Messenger and is omitted from deliveries via those channels.

apn
オプション
post オブジェクト Not PII

APNS specific payload that overrides corresponding attributes in a generic payload for Bindings with the apn BindingType. This value is mapped to the Payload item, therefore the aps key has to be used to change standard attributes. Adds custom key-value pairs to the root of the dictionary. Refer to APNS documentation for more details. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed.

gcm
オプション
post オブジェクト Not PII

GCM specific payload that overrides corresponding attributes in generic payload for Bindings with gcm BindingType. This value is mapped to the root json dictionary. Refer to GCM documentation for more details. Target parameters to, registration_ids, and notification_key are not allowed. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed. FCM and GCM reserves certain keys that cannot be used for those channels.

sms
オプション
post オブジェクト Not PII

SMS specific payload that overrides corresponding attributes in generic payload for Bindings with sms BindingType. Each attribute in this JSON object is mapped to the corresponding form parameter of the Twilio Message resource. The following 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 expects a JSON array.

facebook_messenger
オプション
post オブジェクト Not PII

Messenger specific payload that overrides corresponding attributes in generic payload for Bindings with facebook-messenger BindingType. This value is mapped to the root json dictionary of Facebook's Send API request. Overriding the recipient parameter is not allowed.

fcm
オプション
post オブジェクト Not PII

FCM specific payload that overrides corresponding attributes in generic payload for Bindings with fcm BindingType. This value is mapped to the root json dictionary. Refer to FCM documentation for more details. Target parameters to, registration_ids, condition, and notification_key are not allowed. The twi_ key prefix for custom key-value pairs is reserved for Twilio for future use. Custom data with keys starting with twi_ is not allowed. Custom data with keys starting with twi_ is not allowed. FCM and GCM reserves certain keys that cannot be used for those channels.

to_binding
オプション
post string[] Not PII

The destination address in a JSON object (see attributes below). Multiple ToBinding 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.

例 1
        
        
        
        
        例 2
              
              
              
              
              例 3
                    
                    
                    
                    
                    例 4
                          
                          
                          
                          
                          Create temporary Bindings in the request using the ToBinding attributes described below.

                          Send a Notification to Bindings in the request

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

                                ToBinding attributes

                                名前 概要
                                binding_type The channel to use. Possible values: sms, apn, gcm, fcm, facebook-messenger.
                                address

                                The destination address.

                                For SMS, it is the phone number in E.164 format.

                                For APNS, GCM and FCM, it is the device or registration token.

                                For Facebook Messenger, it is the Messenger ID.

                                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
                                • GCM
                                • SMS
                                • Facebook Messenger

                                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
                                GCM / FCM Firebase response status code 200 + error:NotRegistered
                                GCM / FCM Firebase response status code 200 + error:InvalidRegistration
                                GCM / FCM Firebase response status code 200 + error:MismatchSenderId
                                SMS 21604 - 'To' phone number is blank
                                Facebook Messenger (has no unrecoverable errors)
                                Rate this page:

                                ヘルプが必要ですか?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.