Twilio Notify API is a powerful tool that allows developers to send notifications to multiple recipients across various communication channels. With this API, users can customize the content and delivery of their notifications, ensuring that each message reaches the right audience at the right time. Whether it's SMS, push notifications, or email, Twilio Notify API enables seamless communication and engagement with users.
components:
schemas:
notify.v1.service.binding:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^BS[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Binding resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Binding resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/notify/api/service-resource)
the resource is associated with.
credential_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Credential](https://www.twilio.com/docs/notify/api/credential-resource)
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.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
notification_protocol_version:
type: string
nullable: true
description: >-
The protocol version to use to send the notification. This defaults
to the value of `default_xxxx_notification_protocol_version` in the
[Service](https://www.twilio.com/docs/notify/api/service-resource)
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.
endpoint:
type: string
nullable: true
description: Deprecated.
identity:
type: string
nullable: true
description: >-
The `identity` value that uniquely identifies the resource's
[User](https://www.twilio.com/docs/chat/rest/user-resource) within
the
[Service](https://www.twilio.com/docs/notify/api/service-resource).
Up to 20 Bindings can be created for the same Identity in a given
Service.
x-twilio:
pii:
handling: standard
deleteSla: 120
binding_type:
type: string
nullable: true
description: >-
The transport technology to use for the Binding. Can be: `apn`,
`fcm`, `gcm`, `sms`, or `facebook-messenger`.
address:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: sensitive
deleteSla: 120
tags:
type: array
items:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: standard
deleteSla: 120
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Binding resource.
links:
type: object
format: uri-map
nullable: true
description: The URLs of related resources.
binding_enum_binding_type:
type: string
enum:
- apn
- gcm
- sms
- fcm
- facebook-messenger
- alexa
notify.v1.credential:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Credential
resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Credential resource.
friendly_name:
type: string
nullable: true
description: The string that you assigned to describe the resource.
type:
type: string
$ref: '#/components/schemas/credential_enum_push_service'
nullable: true
description: 'The Credential type. Can be: `gcm`, `fcm`, or `apn`.'
sandbox:
type: string
nullable: true
description: >-
[APN only] Whether to send the credential to sandbox APNs. Can be
`true` to send to sandbox APNs or `false` to send to production.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Credential resource.
credential_enum_push_service:
type: string
enum:
- gcm
- apn
- fcm
notify.v1.service.notification:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^NT[0-9a-fA-F]{32}$
nullable: true
description: >-
The unique string that we created to identify the Notification
resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Notification resource.
service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Service](https://www.twilio.com/docs/notify/api/service-resource)
the resource is associated with.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
identities:
type: array
items:
type: string
nullable: true
description: >-
The list of `identity` values of the Users to notify. We will
attempt to deliver notifications only to Bindings with an identity
in this list.
x-twilio:
pii:
handling: standard
deleteSla: 120
tags:
type: array
items:
type: string
nullable: true
description: >-
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.
x-twilio:
pii:
handling: standard
deleteSla: 120
segments:
type: array
items:
type: string
nullable: true
description: >-
The list of Segments to notify. The
[Segment](https://www.twilio.com/docs/notify/api/segment-resource)
resource is deprecated. Use the `tags` property, instead.
priority:
type: string
$ref: '#/components/schemas/notification_enum_priority'
nullable: true
description: >-
The priority of the notification. Can be: `low` or `high` and the
default is `high`. A value of `low` optimizes the client app's
battery consumption; however, notifications may be delivered with
unspecified delay. For FCM and GCM, `low` priority is the same as
`Normal` priority. For APNS `low` priority is the same as `5`. A
value of `high` sends the notification immediately, and can wake up
a sleeping device. For FCM and GCM, `high` is the same as `High`
priority. For APNS, `high` is a priority `10`. SMS does not support
this property.
ttl:
type: integer
nullable: true
description: >-
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:
type: string
nullable: true
description: >-
The notification title. For FCM and GCM, this translates to the
`data.twi_title` value. For APNS, this translates to the
`aps.alert.title` value. SMS does not support this property. This
field is not visible on iOS phones and tablets but appears on Apple
Watch and Android devices.
body:
type: string
nullable: true
description: >-
The notification text. For FCM and GCM, translates to
`data.twi_body`. For APNS, translates to `aps.alert.body`. For SMS,
translates to `body`. SMS requires either this `body` value, or
`media_urls` attribute defined in the `sms` parameter of the
notification.
x-twilio:
pii:
handling: standard
deleteSla: 0
sound:
type: string
nullable: true
description: >-
The name of the sound to be played for the notification. For FCM and
GCM, this Translates to `data.twi_sound`. For APNS, this translates
to `aps.sound`. SMS does not support this property.
action:
type: string
nullable: true
description: >-
The actions to display for the notification. For APNS, translates to
the `aps.category` value. For GCM, translates to the
`data.twi_action` value. For SMS, this parameter is not supported
and is omitted from deliveries to those channels.
data:
nullable: true
description: >-
The custom key-value pairs of the notification's payload. For FCM
and GCM, this value translates to `data` in the FCM and GCM
payloads. FCM and GCM [reserve certain
keys](https://firebase.google.com/docs/cloud-messaging/http-server-ref)
that cannot be used in those channels. For APNS, attributes of
`data` are inserted into the APNS payload as custom properties
outside of the `aps` dictionary. In all channels, we reserve keys
that start with `twi_` for future use. Custom keys that start with
`twi_` are not allowed and are rejected as 400 Bad request with no
delivery attempted. For SMS, this parameter is not supported and is
omitted from deliveries to those channels.
apn:
nullable: true
description: >-
The APNS-specific payload that overrides corresponding attributes in
the generic payload for APNS Bindings. This property maps to the
APNS `Payload` item, therefore the `aps` key must be used to change
standard attributes. Adds custom key-value pairs to the root of the
dictionary. See the [APNS
documentation](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html)
for more details. We reserve keys that start with `twi_` for future
use. Custom keys that start with `twi_` are not allowed.
gcm:
nullable: true
description: >-
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 `to`, `registration_ids`,
and `notification_key` are not allowed. We reserve keys that start
with `twi_` for future use. Custom keys that start with `twi_` are
not allowed.
fcm:
nullable: true
description: >-
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](https://firebase.google.com/docs/cloud-messaging/http-server-ref#downstream)
for more details. Target parameters `to`, `registration_ids`,
`condition`, and `notification_key` are not allowed in this
parameter. We reserve keys that start with `twi_` for future use.
Custom keys that start with `twi_` are not allowed. FCM also
[reserves certain
keys](https://firebase.google.com/docs/cloud-messaging/http-server-ref),
which cannot be used in that channel.
sms:
nullable: true
description: >-
The SMS-specific payload that overrides corresponding attributes in
the generic payload for SMS Bindings. Each attribute in this value
maps to the corresponding `form` parameter of the Twilio
[Message](https://www.twilio.com/docs/sms/api/message-resource)
resource. These 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` property expects a JSON array.
facebook_messenger:
nullable: true
description: Deprecated.
alexa:
nullable: true
description: Deprecated.
notification_enum_priority:
type: string
enum:
- high
- low
notify.v1.service:
type: object
properties:
sid:
type: string
minLength: 34
maxLength: 34
pattern: ^IS[0-9a-fA-F]{32}$
nullable: true
description: The unique string that we created to identify the Service resource.
account_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^AC[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Account](https://www.twilio.com/docs/iam/api/account) that created
the Service resource.
friendly_name:
type: string
nullable: true
description: The string that you assigned to describe the resource.
date_created:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was created specified in
[RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format.
date_updated:
type: string
format: date-time
nullable: true
description: >-
The date and time in GMT when the resource was last updated
specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt)
format.
apn_credential_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Credential](https://www.twilio.com/docs/notify/api/credential-resource)
to use for APN Bindings.
gcm_credential_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Credential](https://www.twilio.com/docs/notify/api/credential-resource)
to use for GCM Bindings.
fcm_credential_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the
[Credential](https://www.twilio.com/docs/notify/api/credential-resource)
to use for FCM Bindings.
messaging_service_sid:
type: string
minLength: 34
maxLength: 34
pattern: ^MG[0-9a-fA-F]{32}$
nullable: true
description: >-
The SID of the [Messaging
Service](https://www.twilio.com/docs/sms/quickstart#messaging-services)
to use for SMS Bindings. In order to send SMS notifications this
parameter has to be set.
facebook_messenger_page_id:
type: string
nullable: true
description: Deprecated.
default_apn_notification_protocol_version:
type: string
nullable: true
description: >-
The protocol version to use for sending APNS notifications. Can be
overridden on a Binding by Binding basis when creating a
[Binding](https://www.twilio.com/docs/notify/api/binding-resource)
resource.
default_gcm_notification_protocol_version:
type: string
nullable: true
description: >-
The protocol version to use for sending GCM notifications. Can be
overridden on a Binding by Binding basis when creating a
[Binding](https://www.twilio.com/docs/notify/api/binding-resource)
resource.
default_fcm_notification_protocol_version:
type: string
nullable: true
description: >-
The protocol version to use for sending FCM notifications. Can be
overridden on a Binding by Binding basis when creating a
[Binding](https://www.twilio.com/docs/notify/api/binding-resource)
resource.
log_enabled:
type: boolean
nullable: true
description: >-
Whether to log notifications. Can be: `true` or `false` and the
default is `true`.
url:
type: string
format: uri
nullable: true
description: The absolute URL of the Service resource.
links:
type: object
format: uri-map
nullable: true
description: >-
The URLs of the Binding, Notification, Segment, and User resources
related to the service.
alexa_skill_id:
type: string
nullable: true
description: Deprecated.
default_alexa_notification_protocol_version:
type: string
nullable: true
description: Deprecated.
delivery_callback_url:
type: string
nullable: true
description: URL to send delivery status callback.
delivery_callback_enabled:
type: boolean
nullable: true
description: >-
Callback configuration that enables delivery callbacks, default
false
CreateBindingRequest:
type: object
required:
- Identity
- BindingType
- Address
properties:
Identity:
type: string
description: >-
The `identity` value that uniquely identifies the new resource's
[User](https://www.twilio.com/docs/chat/rest/user-resource) within
the
[Service](https://www.twilio.com/docs/notify/api/service-resource).
Up to 20 Bindings can be created for the same Identity in a given
Service.
BindingType:
type: string
$ref: '#/components/schemas/binding_enum_binding_type'
description: >-
The transport technology to use for the Binding. Can be: `apn`,
`fcm`, `gcm`, `sms`, or `facebook-messenger`.
Address:
type: string
description: >-
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.
Tag:
type: array
items:
type: string
description: >-
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.
NotificationProtocolVersion:
type: string
description: >-
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](https://www.twilio.com/docs/notify/api/service-resource).
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.
CredentialSid:
type: string
minLength: 34
maxLength: 34
pattern: ^CR[0-9a-fA-F]{32}$
description: >-
The SID of the
[Credential](https://www.twilio.com/docs/notify/api/credential-resource)
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.
Endpoint:
type: string
description: Deprecated.
ListBindingResponse:
type: object
properties:
bindings:
type: array
items:
$ref: '#/components/schemas/notify.v1.service.binding'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
ListCredentialResponse:
type: object
properties:
credentials:
type: array
items:
$ref: '#/components/schemas/notify.v1.credential'
meta:
type: object
properties:
first_page_url:
type: string
format: uri
next_page_url:
type: string
format: uri
nullable: true
page:
type: integer
page_size:
type: integer
previous_page_url:
type: string
format: uri
nullable: true
url:
type: string
format: uri
key:
type: string
CreateCredentialRequest:
type: object
required:
- Type
properties:
Type:
type: string
$ref: '#/components/schemas/credential_enum_push_service'
description: 'The Credential type. Can be: `gcm`, `fcm`, or `apn`.'
FriendlyName:
type: string
description: >-
A descriptive string that you create to describe the resource. It
can be up to 64 characters long.
Certificate:
type: string
description: >-
[APN only] The URL-encoded representation of the certificate. Strip
everything outside of the headers, e.g. `--BEGIN
CERTIFICATE--MIIFnTCCBIWgAwIBAgIIAjy9H849+E8wDQYJKoZIhvcNAQEFBQAwgZYxCzAJBgNV.....A==--END
CERTIFICATE--`
PrivateKey:
type: string
description: >-
[APN only] The URL-encoded representation of the private key. Strip
everything outside of the headers, e.g. `--BEGIN RSA PRIVATE
KEY--MIIEpQIBAAKCAQEAuyf/lNrH9ck8DmNyo3fGgvCI1l9s+cmBY3WIz+cUDqmxiieR\n.--END
RSA PRIVATE KEY--`
Sandbox:
type: boolean
description: >-
[APN only] Whether to send the credential to sandbox APNs. Can be
`true` to send to sandbox APNs or `false` to send to production.
ApiKey:
type: string
description: >-
[GCM only] The `Server key` of your project from Firebase console
under Settings / Cloud messaging.
Secret:
type: string
description: >-
[FCM only] The `Server key` of your project from Firebase console
under Settings / Cloud messaging.
UpdateCredentialRequest:
type: object
properties:
FriendlyName:
type: string
description: >-
A descriptive string that you create to describe the resource. It
can be up to 64 characters long.
Certificate:
type: string
description: >-
[APN only] The URL-encoded representation of the certificate. Strip
everything outside of the headers, e.g. `--BEGIN
CERTIFICATE--MIIFnTCCBIWgAwIBAgIIAjy9H849+E8wDQYJKoZIhvcNAQEFBQAwgZYxCzAJBgNV.....A==--END
CERTIFICATE--`
PrivateKey:
type: string
description: >-
[APN only] The URL-encoded representation of the private key. Strip
everything outside of the headers, e.g. `--BEGIN RSA PRIVATE
KEY--MIIEpQIBAAKCAQEAuyf/lNrH9ck8DmNyo3fGgvCI1l9s+cmBY3WIz+cUDqmxiieR\n.--END
RSA PRIVATE KEY--`
Sandbox:
type: boolean
description: >-
[APN only] Whether to send the credential to sandbox APNs. Can be
`true` to send to sandbox APNs or `false` to send to production.
ApiKey:
type: string
description: >-
[GCM only] The `Server key` of your project from Firebase console
under Settings / Cloud messaging.
Secret:
type: string
description: >-
[FCM only] The `Server key` of your project from Firebase console
under Settings / Cloud messaging.
CreateNotificationRequest:
type: object
properties:
Body:
type: string
description: >-
The notification text. For FCM and GCM, translates to
`data.twi_body`. For APNS, translates to `aps.alert.body`. For SMS,
translates to `body`. SMS requires either this `body` value, or
`media_urls` attribute defined in the `sms` parameter of the
notification.
Priority:
type: string
$ref: '#/components/schemas/notification_enum_priority'
description: >-
The priority of the notification. Can be: `low` or `high` and the
default is `high`. A value of `low` optimizes the client app's
battery consumption; however, notifications may be delivered with
unspecified delay. For FCM and GCM, `low` priority is the same as
`Normal` priority. For APNS `low` priority is the same as `5`. A
value of `high` sends the notification immediately, and can wake up
a sleeping device. For FCM and GCM, `high` is the same as `High`
priority. For APNS, `high` is a priority `10`. SMS does not support
this property.
Ttl:
type: integer
description: >-
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:
type: string
description: >-
The notification title. For FCM and GCM, this translates to the
`data.twi_title` value. For APNS, this translates to the
`aps.alert.title` value. SMS does not support this property. This
field is not visible on iOS phones and tablets but appears on Apple
Watch and Android devices.
Sound:
type: string
description: >-
The name of the sound to be played for the notification. For FCM and
GCM, this Translates to `data.twi_sound`. For APNS, this translates
to `aps.sound`. SMS does not support this property.
Action:
type: string
description: >-
The actions to display for the notification. For APNS, translates to
the `aps.category` value. For GCM, translates to the
`data.twi_action` value. For SMS, this parameter is not supported
and is omitted from deliveries to those channels.
Data:
description: >-
The custom key-value pairs of the notification's payload. For FCM
and GCM, this value translates to `data` in the FCM and GCM
payloads. FCM and GCM [reserve certain
keys](https://firebase.google.com/docs/cloud-messaging/http-server-ref)
that cannot be used in those channels. For APNS, attributes of
`data` are inserted into the APNS payload as custom properties
outside of the `aps` dictionary. In all channels, we reserve keys
that start with `twi_` for future use. Custom keys that start with
`twi_` are not allowed and are rejected as 400 Bad request with no
delivery attempted. For SMS, this parameter is not supported and is
omitted from deliveries to those channels.
Apn:
description: >-
The APNS-specific payload that overrides corresponding attributes in
the generic payload for APNS Bindings. This property maps to the
APNS `Payload` item, therefore
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twilio/refs/heads/main/openapi/notify-openapi-original.yml