Skip to content Skip to navigation Skip to topbar

Page tools

On this page

Looking for more inspiration?Visit the

Notify Binding resource

(error)

Twilio Notify deprecated

Twilio stopped supporting Notify in October 2022.

If you used Notify for push notifications, sign up for the Private Beta.
If you used Notify for bulk SMS, migrate to the Bulk Messaging API.

The Binding resource binds an identity to the address the notification channel uses.

For example: iOS push notifications use an APNS device token for their address. SMS uses a phone number.

With Bindings, you can send notifications 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.

(error)

Never use PII in identity parameter

The systems that process the identity parameter assume it doesn't contain Personally Identifiable Information (PII). PII can include a person's name, home address, email or phone number. Instead, use a Universally Unique Identifier (UUID), a pseudonymized identifier, or hashed or encrypted PII data. To learn how Twilio processes your data, see the Twilio privacy policy.

Address for push notifications

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

Your client-side app obtains the address for push notifications. This differs from SMS, where the messages get sent to a phone number.

To obtain an Apple Push Notification service (APNS) address, called a device token, register for notifications on iOS .
To obtain a Firebase Cloud Messaging (FCM) address, called a registration token, register for Notifications on Android.

Binding Properties

Property nameTypeRequiredPIIDescriptionChild properties

sidSID<BS>

Optional

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

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

accountSidSID<AC>

Optional

The SID of the Account that created the Binding resource.

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

serviceSidSID<IS>

Optional

The SID of the Service the resource is associated with.

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

credentialSidSID<CR>

Optional

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.

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

dateCreatedstring<date-time>

Optional

The date and time in GMT when the resource was created specified in RFC 2822 format.

dateUpdatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

notificationProtocolVersionstring

Optional

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.

endpointstring

Optional

Deprecated.

identitystring

Optional

PII MTL: 120 days

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.

bindingTypestring

Optional

The transport technology to use for the Binding. Can be: apn, fcm, gcm, sms, or facebook-messenger.

addressstring

Optional

PII MTL: 120 days

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.

tagsarray[string]

Optional

PII MTL: 120 days

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.

urlstring<uri>

Optional

The absolute URL of the Binding resource.

linksobject<uri-map>

Optional

The URLs of related resources.

Endpoint (DEPRECATED)

Twilio deprecated endpoint property. When an app changes or invalidates the device token used as the address, the push-channel provider updates Twilio. If you add this property, Twilio ignores it.

Create a Binding resource

POST https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

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

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

identitystring

required

PII MTL: 120 days

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.

bindingTypeenum<string>

required

The transport technology to use for the Binding. Can be: apn, fcm, gcm, sms, or facebook-messenger.

Possible values:

apngcmsmsfcmfacebook-messengeralexa

addressstring

required

PII MTL: 120 days

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.

tagarray[string]

Optional

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.

notificationProtocolVersionstring

Optional

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.

credentialSidSID<CR>

Optional

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.

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

endpointstring

Optional

Deprecated.

Create a Binding resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createBinding() {
11  const binding = await client.notify.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .bindings.create({
14      address: "Unit 3856 Box 3973\nDPO AA 31194",
15      bindingType: "apn",
16      identity: "Identity",
17    });
18
19  console.log(binding.sid);
20}
21
22createBinding();

Response

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "address": "Unit 3856 Box 3973\nDPO AA 31194",
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}

Existing Bindings with the same Address are replaced

If your Service has a Binding with the same Address as specified in the Create request, the created Binding replaces the existing Binding. This prevents leaking notifications between users like when two end users log into your app from the same device. To register the same address twice, create separate Service instances.

For example: If you have an end user that serves a buyer and a seller at the same time in a marketplace, create a Service for buyers and another for sellers.

Fetch a Binding resource

GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

The SID of the Service to fetch the resource from.

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

sidSID<BS>

required

The Twilio-provided string that uniquely identifies the Binding resource to fetch.

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

Fetch a Binding resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchBinding() {
11  const binding = await client.notify.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .bindings("BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .fetch();
15
16  console.log(binding.sid);
17}
18
19fetchBinding();

Response

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}

Read multiple Binding resources

GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

The SID of the Service to read the resource from.

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

Query parameters

Property nameTypeRequiredPIIDescription

startDatestring<date>

Optional

Only include usage that has occurred on or after this date. Specify the date in GMT and format as YYYY-MM-DD.

endDatestring<date>

Optional

Only include usage that occurred on or before this date. Specify the date in GMT and format as YYYY-MM-DD.

identityarray[string]

Optional

PII MTL: 120 days

The User's identity value of the resources to read.

tagarray[string]

Optional

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.

pageSizeinteger<int64>

Optional

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

pageinteger

Optional

The page index. This value is simply for client state.

Minimum: 0

pageTokenstring

Optional

The page token. This is provided by the API.

Read multiple Binding resources

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listBinding() {
11  const bindings = await client.notify.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .bindings.list({ limit: 20 });
14
15  bindings.forEach((b) => console.log(b.sid));
16}
17
18listBinding();

Response

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}

This request returns no more than 50 Bindings at a time.

Delete a Binding resource

DELETE https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

serviceSidSID<IS>

required

The SID of the Service to delete the resource from.

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

sidSID<BS>

required

The Twilio-provided string that uniquely identifies the Binding resource to delete.

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

Delete a Binding resource

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteBinding() {
11  await client.notify.v1
12    .services("ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .bindings("BSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .remove();
15}
16
17deleteBinding();