Notify delivery callbacks
A Notify delivery callback is a URL that sends webhooks that provide you with information about how many messages were sent and if those messages were sent correctly by the Notify API. Let's keep in mind that Notify is a bulk-first messaging API, where one API call can trigger from zero to multiple thousands of messages.
Info
Note: Each Callback will contain the status for up to 1000 SMS and/or pushes.
Every callback contains a list of the deliveries-messages that were sent as part of the notification.
The status of one notification can be delivered in one or multiple delivery callbacks, depending on the size of the notification. The final callback from the Notify API will always have a flag IsFinal set to True to indicate that notification is handled completely.
Every delivery in the list has one of the following status:
- SENT: Notify successfully passed the message to the channel (i.e. Twilio SMS, FCM, APN)
- FAILED: The channel (Twilio SMS, FCM, APM) returned an error.
Warning
Notify callbacks do not update the state of the message once it has been passed to the channel. It means there will be no further updates when a recipient has received a message.
Notify delivery callback provides the following payload information.
| Parameter | Type | Description |
|---|---|---|
| NotificationSid | string | A 34 character string that uniquely identifies the Notification that triggered the Delivery attempt |
| AccountSid | string | The unique ID of the Account that sent this notification |
| ServiceSid | string | The unique ID of the Service that sent this notification |
| Count | integer | Number of Deliveries in this report |
| SequenceId | integer | Sequence number of the batch starting from 0 |
| IsFinal | Boolean | Flag to indicate it is the final batch for the bulk notification |
| DeliveryState | JSON | The status of this Delivery attempt |
The DeliveryState indicates the status of a delivery attempt. The number of performed delivery attempts should be equal to the number of DeliveryState parameters shown in the payload.
| Parameter | Type | Description |
|---|---|---|
| sid | string | Provider unique message id (for APN/FCM) or message sid (SMxxx for SMS, MMxxx for MMS, RUxxx for rest of adapters) |
| type | string | Channel type (e.g., APN, FCM, SMS, etc...) |
| status | string | SENT or FAILED |
| identity | string | Identity |
| error_code | Integer (optional) | Twilio error code, if an error happened. For more information, go to Twilio error codes |
Content-Type: application/x-www-form-urlencoded
1&SequenceId=02&NotificationSid={NotificationSid}3&IsFinal=False4&Count=25&DeliveryState[0]="{ \"sid\": \"message sid\", \"channel\": \"APN\", \"status\": \"SENT\" }"6&DeliveryState[1]="{ \"sid\": \"message sid\",7\"channel\": \"APN\",8\"status\": \"FAILED\",9\"error_code\": 52131,10\"error_message\": \"The provided APNs device token has been unregistered\" }"
The Notification's resource accepts an optional "DeliveryCallbackUrl" field that should contain a URL that will be called to provide the Notification status, as shown in the following example:
1curl -X POST 'https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications' \2--data-urlencode 'Identity=00000001' \3--data-urlencode 'Body=Hello Bob' \4--data-urlencode 'DeliveryCallbackUrl=https://myhost/notifyCallbacks'5-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN6