Skip to content

Twilio Notify & Mobile push Service

Summary

Twilio Notify API allows sending notifications across multiple channels.
Available channels: SMS, iOS and Android mobile push notifications

This service is in Beta status from Twilio. Please review limitations at https://www.twilio.com/notify.
Before you can use this service, you need to add your twilio credentials in the service configuration. You can refer to the "configuration" section in following doc for instructions of setting your service configuration.

Operations

Name Tag Summary
twilionotify.createBinding() Create a binding between a device identity and a target service
twilionotify.deleteBinding() Delete the binding of a service
twilionotify.getBinding() Get the binding of a service
twilionotify.listBinding() List all created bindings to this service
twilionotify.send() Send a notification to binding channels

Configuration parameters

Name Type Description
AccountSid ^\(\[0-9a-zA-Z\]\{34\}|\)$ Account SID
AuthToken string(password) Authentication Token

Operations

createBinding

Description

Create a binding between a device identity and a target service

Arguments

Name Type Description
Tag string (optional) The list of tags associated with this Binding. Tags can be used to filter registrations when selecting recipients of a notification. A maximum of 20 tags are allowed.
Address string The address specific to the channel. For APNS, it is the device token. For FCM and GCM, it is the registration token. For SMS, it is a phone number in E.164 format. For Facebook Messenger, it is the Messenger ID of the user or a phone number in E.164 format.
Endpoint string The identifier of the endpoint to which this Binding belongs. An endpoint is a specific application on a specific device (e.g., a mobile app on your iPad or the SMS inbox on your phone) of a specific user. The value of this parameter is a string that integrates those three pieces of information: application, device, and user.
Identity string The Identity to which this Binding belongs. Identity is defined by your application and typically is a username or email address.
BindingType string The type of the Binding determining the transport technology to use. Allowed values: apn, fcm, gcm, sms, facebook-messenger.
CredentialSid string (optional) The unique identifier (SID) of the Credential resource to be used to send notifications to this Binding. If present, it overrides the Credential specified in the Service resource. Applicable only to apn, fcm, and gcm type Bindings.
NotificationProtocolVersion string (optional) The version of the protocol (data format) used to send the notification. Defaults to the value of DefaultXXXNotificationProtocolVersion in the Service. The current version is "3" for apn, fcm, and gcm type Bindings. The parameter is not applicable to sms and facebook-messenger type Bindings as the data format is fixed.

Responses

  • Returns {object} when Binding posted

    Details of posted binding {object}

    Name Type Description
    sid ^[0-9a-zA-Z]{34}$ A 34-character string that uniquely identifies this resource.
    url string The URL of created Binding.
    tags string The list of tags associated with this Binding.
    address string The address specific to the channel. For APNS it is the device token.
    endpoint string The identifier of the endpoint to which this Binding belongs to.
    identity string The Identity to which this Binding belongs to.
    account_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of Twilio account.
    service_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of the Service of Notify API.
    binding_type string The type of the Binding determining the transport technology to use.
    date_created string(date) The date this resource was created, given in RFC 2822 format.
    date_updated string(date) The date this resource was updated, given in RFC 2822 format.
    credential_sid string The unique identifier (SID) of the Credential resource to be used to send notifications to this Binding.
    notification_protocol_version string The version of the protocol (data format) used to send the notification.
  • Returns {object} when Error

    Request error {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code

Example

-- Create a binding by client-side information
local out = Twilionotify.createBinding({
  ServiceSid = "ISXXXXXXXXXXXXXXXXXXX",
  Identity = "dev00001",
  Endpoint = "dev_test_device",
  BindingType = "apn",
  Address = "apn_device_token"
})
response.message = out

deleteBinding

Description

Delete the binding of a service

Arguments

Name Type Description
BindingSid ^[0-9a-zA-Z]{34}$ SID of the binding

Responses

  • Returns nil for Binding deleted

  • Returns {object} when Error

    Request error {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code

Example

local binding = Twilionotify.deleteBinding({
  ServiceSid = "ISXXXXXXXXXXXXXXXXXXX",
  BindingSid = "BSYYYYYYYYYYYYYYYYYYY"
})
response.message = binding

getBinding

Description

Get the binding of a service

Arguments

Name Type Description
BindingSid ^[0-9a-zA-Z]{34}$ SID of the binding

Responses

  • Returns {object} when Binding information

    Details of posted binding {object}

    Name Type Description
    sid ^[0-9a-zA-Z]{34}$ A 34-character string that uniquely identifies this resource.
    url string The URL of created Binding.
    tags string The list of tags associated with this Binding.
    address string The address specific to the channel. For APNS it is the device token.
    endpoint string The identifier of the endpoint to which this Binding belongs to.
    identity string The Identity to which this Binding belongs to.
    account_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of Twilio account.
    service_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of the Service of Notify API.
    binding_type string The type of the Binding determining the transport technology to use.
    date_created string(date) The date this resource was created, given in RFC 2822 format.
    date_updated string(date) The date this resource was updated, given in RFC 2822 format.
    credential_sid string The unique identifier (SID) of the Credential resource to be used to send notifications to this Binding.
    notification_protocol_version string The version of the protocol (data format) used to send the notification.
  • Returns {object} when Error

    Request error {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code

Example

local binding = Twilionotify.getBinding({
  ServiceSid = "ISXXXXXXXXXXXXXXXXXXX",
  BindingSid = "BSYYYYYYYYYYYYYYYYYYY"
})
response.message = binding

listBinding

Description

List all created bindings to this service

Arguments

Name Type Description
Identity string Only list Bindings that have any of the specified Identities.
Tag string Only list Bindings that have all the specified Tags. The following implicit tags are available: all, apn, fcm, gcm, sms, facebook-messenger. A maximum of 20 tags are allowed.
StartDate string Only list Bindings created on or after the given date. Should be formatted as YYYY-MM-DD. All dates considered in UTC.
EndDate string Only list Bindings created on or before the given date. Should be formatted as YYYY-MM-DD. All dates considered in UTC.

Responses

  • Returns {object} when Binding list retrieved

    Binding list result {object}

    Name Type Description
    meta object Meta information
    meta.key string Key name of meta information
    meta.url string Current page URL
    meta.page integer The current page number. Zero-indexed, so the first page is 0.
    meta.page_size integer Number of items in this page
    meta.next_page_url string Next page URL
    meta.first_page_url string First page URL
    meta.previous_page_url string Previous page URL
    bindings [ object ] Binding list
    bindings[].sid ^[0-9a-zA-Z]{34}$ A 34-character string that uniquely identifies this resource.
    bindings[].url string The URL of created Binding.
    bindings[].tags string The list of tags associated with this Binding.
    bindings[].address string The address specific to the channel. For APNS it is the device token.
    bindings[].endpoint string The identifier of the endpoint to which this Binding belongs to.
    bindings[].identity string The Identity to which this Binding belongs to.
    bindings[].account_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of Twilio account.
    bindings[].service_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of the Service of Notify API.
    bindings[].binding_type string The type of the Binding determining the transport technology to use.
    bindings[].date_created string(date) The date this resource was created, given in RFC 2822 format.
    bindings[].date_updated string(date) The date this resource was updated, given in RFC 2822 format.
    bindings[].credential_sid string The unique identifier (SID) of the Credential resource to be used to send notifications to this Binding.
    bindings[].notification_protocol_version string The version of the protocol (data format) used to send the notification.
  • Returns {object} when Error

    Request error {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code

Example

local list = Twilionotify.listBinding({
  ServiceSid = "ISXXXXXXXXXXXXXXXXXXX"
})
response.message = list

send

Description

Send a notification to binding channels

Arguments

Name Type Description
Apn string APNS specific payload that overrides corresponding attributes in generic payload for Bindings with APN BindingType.



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



This parameter only adds or overrides attributes, but it does not delete ones specified in the generic payload. 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 string FCM specific payload that overrides corresponding attributes in generic payload for Bindings with FCM BindingType.



Value mapped to the root json dictionary. Refer to FCM documentation for more details.



This parameter only adds or overrides attributes, but it does not delete ones specified in the generic payload. Target parameters (to, registration_ids, condition, 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.
Gcm string GCM specific payload that overrides corresponding attributes in generic payload for Bindings with gcm BindingType.



Value mapped to the root json dictionary. Refer to GCM documentation for more details.



This parameter only adds or overrides attributes, but it does not delete ones specified in the generic payload. Target parameters (to, registration_ids, 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.
Sms string 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.



This parameter only adds or overrides attributes, but it does not delete ones specified in the generic payload. The following parameters of the Message resource are supported in snake case format: from, body, media_url, status_callback, max_price.



from and status_callback parameters override the corresponding parameters in the messaging service if one is configured. Either the from parameter needs to be set here or the Service used to send the notification needs to have a MessagingServiceSid configured.
Tag string Delivery will be attempted only to Bindings that have all the Tags in this list.



Maximum 20 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.
Ttl string (optional) This parameter specifies how long (in seconds) the notification is valid and should be attempted to be delivered if the device is offline.



The maximum time to live supported is 4 weeks. The value zero means that the notification is attempted to be delivered immediately once but not stored for future delivery. The default value is 4 weeks.



This feature is not supported by SMS and Facebook Messenger; therefore, it will be ignored for deliveries via those channels.
Body string (optional) Indicates notification body text. Translates to data.twi_body for FCM and GCM, aps.alert.body for APNS, and Body for SMS and Facebook Messenger.



For SMS, either this or the 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.
Data string (optional) This parameter specifies the custom key-value pairs of the notification’s payload.



Translates to data dictionary in FCM and GCM payload. For APNS, attributes of Data will be inserted into the APNS payload as custom properties outside of the APS dictionary.



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; therefore, it is omitted from deliveries via those channels.
Sound string (optional) Indicates 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; therefore, it is omitted from deliveries via those channels.
Title string (optional) Indicates 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 and aps.alert.title for APNS. It is not supported for SMS and Facebook Messenger; therefore, it will be omitted from deliveries via those channels.
Action string (optional) 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; therefore, it is omitted from deliveries via those channels.
Identity string List of Identities for which this notification is intended.



Maximum 20 items allowed in this list. For larger multicast, use Tags.
Priority string (optional) Two priorities defined: low and high (default).



low optimizes the client app's battery consumption. Notifications may be delivered with unspecified delay. Same as Normal priority for FCM and GCM or priority 5 for APNS.



high sends the notification immediately, and it can wake up a sleeping device. Same as High priority for FCM and GCM or priority 10 for APNS.



This feature is not supported by SMS and Facebook Messenger; therefore, it will be ignored for deliveries via those channels.

Responses

  • Returns {object} when Notification posted

    Details of posted notification {object}

    Name Type Description
    apn string APNS specific payload.
    fcm string FCM specific payload.
    gcm string GCM specific payload.
    sid ^[0-9a-zA-Z]{34}$ A 34-character string that uniquely identifies this resource.
    sms string SMS specific payload.
    ttl string How long (in seconds) the notification is valid and should be attempted to be delivered if the device is offline.
    body string Notification body text.
    data string Custom key-value pairs of the notification’s payload.
    tags string Tags used.
    sound string Sound to be played.
    title string Notification title.
    action string Actions to be displayed.
    priority string Priority of notification delivery.
    identities string List of Identities for which this notification is intended.
    account_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of Twilio account.
    service_sid ^[0-9a-zA-Z]{34}$ The 34-character unique ID of the Service of Notify API.
    date_created string(date) The date that this resource was created, given in RFC 2822 format.
    facebook_messenger string Messenger specific payload (not available yet).
  • Returns {object} when Error

    Request error {object}

    Name Type Description
    type string Error type
    error string Error message
    status integer Response code

Example

-- Send a notification to a device with SMS configuration.
local out = Twilionotify.send({
  ServiceSid = "ISXXXXXXXXXXXXXXXXXXX",
  Identity = "dev00001",
  Body = "Device alarm trigger for dev00001!",
  Sms = "{\"from\": \"+123456789\"}"
})
response.message = out