Our webhooks API allows you to subscribe to events. Using them requires you to have URLs (https) configured on your account that can receive POST requests over the internet.
The event_type field is an enum that specifies which event to subscribe to:
- LINK_HIT
- OPT_OUT
- MMS_INBOUND
- MMS_STATUS
- SMS_INBOUND
- SMS_STATUS
For status events, the nested status field is an enum with these values:
- FAILED: Failed because of an error from the carrier or handset.
- SENT: Submitted to the carrier.
- ACCEPTED: Accepted by the carrier and delivery may have been attempted (but is not confirmed).
- DELIVERED: Delivered to handset.
- SOFT_BOUNCE: Undeliverable due to handset being switched off, out of range or other temporary deliverability issue.
- HARD_BOUNCE: Handset was disconnected.
- OTHER: Any other status from the carrier.
Link Hit
The LINK_HIT event is triggered any time a recipient visits a link that is tracked. Track Links is an optional flag on the send message API calls. Along with the URL that was being tracked is a hits field indicating how many visits this tracked link has in total and a source_message which contains the track link sent to the recipient.
Example Payloads
{
"event_type": "LINK_HIT",
"timestamp": "2021-05-06T05:19:42Z",
"link_hit": {
"hits": 1,
"url": "<https://www.example.com/abc">,
"source_message": {
"type": "MMS",
"id": "b50e4dc1-e57f-459c-a15c-526bee00a4c4",
"message": "Hey, Check this out! <http://clckme.info/KYhSsuIH> Opt-out reply STOP",
"message_ref": "D701",
"recipient": "61435790000",
"sender": "61481074191",
"subject": "Hello",
"content_urls": [
"https://res.cloudinary.com/burstsms/image/upload/v1618798563/284KB_qgqtbe.jpg"
]
}
}
}
{
"event_type": "LINK_HIT",
"timestamp": "2021-07-20T23:14:04Z",
"link_hit": {
"hits": 1,
"url": "<https://www.example.com/abc">,
"source_message": {
"type": "SMS",
"id": "faf68308-16cd-4cf9-aef7-47342bd405be",
"message": "Hey, Check this out! <http://clckme.info/KYhSsuIH> for Opt-out reply STOP or hit opt out link - <http://nsub.me/vqHTcCsh> ",
"message_ref": "D301",
"recipient": "61435795809",
"sender": "61481074185"
}
}
}
Opt Out
The OPT_OUT event is triggered when a recipient has visited an opt-out link in a message they have received or by sending a message with the text "STOP".
Using parameter [opt-out-link] in message body, inserts the opt-out link.
The source field will be set according to the method a recipient has used to opt-out and contain a value of either link or SMS.
Important: Please make sure You exclude the opted out contacts from your future campaigns. To achieve high throughput, this API does NOT check against an Opt Out list before sending messages.
Example Payloads
{
"event_type": "OPT_OUT",
"timestamp": "2021-05-06T05:16:20Z",
"opt_out": {
"source": "LINK_HIT",
"source_message": {
"type": "SMS",
"id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
"message": "Hey, Check this out! <http://clckme.info/KYhSsuIH> for Opt-out reply STOP or hit opt out link - <http://nsub.me/vqHTcCsh">,
"message_ref": "ncc5009d",
"recipient": "61435790000",
"sender": "61481074190"
}
}
}
{
"event_type": "OPT_OUT",
"timestamp": "2021-05-06T05:16:20Z",
"opt_out": {
"source": "SMS_INBOUND",
"source_message": {
"type": "SMS",
"id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
"message": "Hey, Check this out! <http://clckme.info/KYhSsuIH> for Opt-out reply STOP or hit opt out link - <http://nsub.me/vqHTcCsh">,
"message_ref": "ncc5009d",
"recipient": "61435790000",
"sender": "61481074190"
}
}
}
MMS Inbound
The MMS_INBOUND event is posted to you on receipt of an MMS sent from a recipient to one of the senders listed on your account. For convenience we will try and find a message that you have sent to this recipient from that sender in the past 72 hours and supply it as the last_message field. This is useful for determining if an inbound message is potentially a reply.
{
"event_type": "MMS_INBOUND",
"timestamp": "2021-05-06T05:16:33Z",
"mo": {
"type":"MMS",
"id": "alss-2way-605b31c7-d2c49104",
"sender": "61435790000",
"recipient": "61481074190",
"message": "Here's a cute picture",
"media": [
{
"name": "image-0.png",
"content": "BASE64-encoded-string------",
],
"last_message": {
"type":"SMS",
"id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
"message": "Hey, check this out!",
"message_ref": "ncc5009d",
"recipient": "61435790000",
"sender": "61481074190"
}
}
}
MMS Status
The MMS_STATUS event data is posted to you for changes to an MMS message status. These are currently only comprised of internal statuses (SENT, FAILED).
{
"event_type": "MMS_STATUS",
"timestamp": "2021-05-06T05:19:33Z",
"status": {
"type": "MMS",
"id": "b50e4dc1-e57f-459c-a15c-526bee00a4c4",
"message_ref": "D7001",
"recipient": "61435790000",
"sender": "61481074191",
"status": "SENT"
}
}
SMS Inbound
The SMS_INBOUND event is posted to you on receipt of an SMS sent from a recipient to one of the senders listed on your account. For convenience we will try and find a message that you have sent to this recipient from that sender and supply it as the last_message field. This is useful for determining if an inbound message is potentially a reply. The routed_via field will display when a shared local number has been used to deliver your message.
{
"event_type": "SMS_INBOUND",
"timestamp": "2021-05-06T05:16:33Z",
"mo": {
"type":"SMS",
"id": "alss-2way-605b31c7-d2c49104",
"message": "Stop",
"recipient": "61481074190",
"routed_via": "447507333300",
"sender": "447507222200",
"last_message": {
"type":"SMS",
"id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
"message": "Hey, check this out!",
"message_ref": "ncc5009d",
"recipient": "447507222200",
"routed_via": "447507333300",
"sender": "61481074190"
}
}
}
SMS Status
The SMS_STATUS event data is posted to you for changes to a SMS message status. Multiple status events can be triggered for a single message. The routed_via field will display when a shared local number has been used to deliver your message.
SMS_Status: SENT
{
"event": "sms_status",
"data": {
"@type": "type.googleapis.com/transmit.webhook.v1.Status",
"mms_id": "",
"sms_id": "b5ca21d8-4f2e-4bf7-9e19-4c0a969192f0",
"message_ref": "",
"sender": "61481075000",
"recipient": "61411274000",
"status": "sent",
"status_updated_at": "2024-11-07T23:48:45Z",
"description": ""
}
}
SMS_Status: DELIVERED
{
"event": "sms_status",
"data": {
"@type": "type.googleapis.com/transmit.webhook.v1.Status",
"mms_id": "",
"sms_id": "b5ca21d8-4f2e-4bf7-9e19-4c0a969192f0",
"message_ref": "",
"sender": "61481070000",
"recipient": "61411270000",
"status": "delivered",
"status_updated_at": "2024-11-07T23:48:46Z",
"description": ""
}
}