The Binding resource binds an identity
to the address
used by a notification channel. For example, iOS push notifications use an APNS device token for their address and SMS uses a phone number. Creating a Binding allows you to send notifications by referring to an identity
rather than a specific device. You can create up to 20 Bindings with the same identity
in a given Service.
You can add tags
to a Binding that describe related Bindings. For example, you can add a tag to the Bindings of a user's preferred devices and then refer to that tag to notify them on only their preferred devices. Read more about Sending Notifications.
The systems that process this parameter assume it does not contain PII.
You should use a GUID or other pseudonymized identifier for identity
instead of PII such as a person's name, home address, email or phone number. If you identify your users with PII, we recommend creating a pseudonymized identifier from their PII, for example by hashing or encrypting it, before you use it for identity
.
You can read more about how we process your data in our privacy policy.
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.
While the address
of an SMS message is the phone number, the address
to use for push notifications is obtained by your client-side mobile app. Learn how to:
The unique string that we created to identify the Binding resource.
^BS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Account that created the Binding resource.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Service the resource is associated with.
^IS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The SID of the Credential resource to be used to send notifications to this Binding. If present, this overrides the Credential specified in the Service resource. Applicable only to apn
, fcm
, and gcm
type Bindings.
^CR[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The date and time in GMT when the resource was created specified in RFC 2822 format.
The date and time in GMT when the resource was last updated specified in RFC 2822 format.
The protocol version to use to send the notification. This defaults to the value of default_xxxx_notification_protocol_version
in the Service for the protocol. 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.
The identity
value that uniquely identifies the resource's User within the Service. Up to 20 Bindings can be created for the same Identity in a given Service.
The transport technology to use for the Binding. Can be: apn
, fcm
, gcm
, sms
, or facebook-messenger
.
The channel-specific address. For APNS, the device token. For FCM and GCM, the registration token. For SMS, a phone number in E.164 format. For Facebook Messenger, the Messenger ID of the user or a phone number in E.164 format.
The list of tags associated with this Binding. Tags can be used to select the Bindings to use when sending a notification. Maximum 20 tags are allowed.
The URLs of related resources.
We deprecated endpoint
and trust the push-channel provider (such as APNS or Firebase) to let us know when an app has changed or invalidated the device token used as the address
.
The endpoint
property was used to uniquely identify push notification Bindings when the app installation's address
changed, such as when the device token changed in an iOS app. You can still include an Endpoint
parameter when you create a Binding; however, it will be ignored.
POST https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings
application/x-www-form-urlencoded
The identity
value that uniquely identifies the new resource's User within the Service. Up to 20 Bindings can be created for the same Identity in a given Service.
The transport technology to use for the Binding. Can be: apn
, fcm
, gcm
, sms
, or facebook-messenger
.
apn
gcm
sms
fcm
facebook-messenger
alexa
The channel-specific address. For APNS, the device token. For FCM and GCM, the registration token. For SMS, a phone number in E.164 format. For Facebook Messenger, the Messenger ID of the user or a phone number in E.164 format.
A tag that can be used to select the Bindings to notify. Repeat this parameter to specify more than one tag, up to a total of 20 tags.
The protocol version to use to send the notification. This defaults to the value of default_xxxx_notification_protocol_version
for the protocol 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.
The SID of the Credential resource to be used to send notifications to this Binding. If present, this overrides the Credential specified in the Service resource. Applies to only apn
, fcm
, and gcm
type Bindings.
^CR[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
Deprecated.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createBinding() {11const binding = await client.notify.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.bindings.create({14address: "Address",15bindingType: "apn",16identity: "Identity",17});1819console.log(binding.sid);20}2122createBinding();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"address": "Address",4"binding_type": "apn",5"credential_sid": null,6"date_created": "2015-07-30T20:00:00Z",7"date_updated": "2015-07-30T20:00:00Z",8"endpoint": "26607274",9"identity": "Identity",10"notification_protocol_version": "3",11"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",12"sid": "BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"tags": [14"26607274"15],16"links": {17"user": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users/24987039"18},19"url": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Bindings/BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"20}
If the Service already has a Binding with the same Address
as specified in the create request, the Binding being created replaces the existing Binding.
The new Binding replaces the existing one under these conditions to prevent leaking notifications between users when, for example, a new user logs into your app on a device that has already been registered to another user.
To register the same address twice, such as when someone is a buyer and a seller at the same time in a marketplace, we recommend creating separate Service instances, such as one for buyers and one for sellers.
We deprecated endpoint
and trust the push-channel provider (such as APNS or Firebase) to let us know when an app has changed or invalidated the device token used as the address
.
The endpoint
property was used to uniquely identify push notification Bindings when the app installation's address
changed, such as when the device token changed in an iOS app. You can still include an Endpoint
parameter when you create a Binding; however, it will be ignored.
GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}
The SID of the Service to fetch the resource from.
^IS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The Twilio-provided string that uniquely identifies the Binding resource to fetch.
^BS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchBinding() {11const binding = await client.notify.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.bindings("BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")14.fetch();1516console.log(binding.sid);17}1819fetchBinding();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"address": "a7c658f4111ec4ff5a1a647f9d0edd819025b9f20522d2fae897049f32873e73",4"binding_type": "apn",5"credential_sid": null,6"date_created": "2015-07-30T20:00:00Z",7"date_updated": "2015-07-30T20:00:00Z",8"endpoint": "26607274",9"identity": "24987039",10"notification_protocol_version": "3",11"service_sid": "ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",12"sid": "BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"tags": [14"26607274"15],16"links": {17"user": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users/24987039"18},19"url": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Bindings/BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"20}
GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings
Only include usage that has occurred on or after this date. Specify the date in GMT and format as YYYY-MM-DD
.
Only include usage that occurred on or before this date. Specify the date in GMT and format as YYYY-MM-DD
.
Only list Bindings that have all of the specified Tags. The following implicit tags are available: all
, apn
, fcm
, gcm
, sms
, facebook-messenger
. Up to 5 tags are allowed.
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listBinding() {11const bindings = await client.notify.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.bindings.list({ limit: 20 });1415bindings.forEach((b) => console.log(b.sid));16}1718listBinding();
1{2"bindings": [],3"meta": {4"first_page_url": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=0",5"key": "bindings",6"next_page_url": null,7"page": 0,8"page_size": 50,9"previous_page_url": null,10"url": "https://notify.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=0"11}12}
Note that no more than 50 Bindings are returned at a time.
DELETE https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}
The SID of the Service to delete the resource from.
^IS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The Twilio-provided string that uniquely identifies the Binding resource to delete.
^BS[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteBinding() {11await client.notify.v112.services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.bindings("BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")14.remove();15}1617deleteBinding();