CallFire API v2 Text Delivery Report Webhook

Overview

Text Delivery Report Webhook allows user to receive notification events from CallFire platform about sent SMS and MMS messages and to know were they delivered or not and the reason in case they weren't delivered to end-user device.

More information about CallFire Webhooks and how to use them you can find at Webhooks Guide page.

Limitations

Delivery reports are only available to short-code users.

Please note that delivery reports are not reliable way to verify was message delivered or not, some providers may not send any information about received messages or may send it within 72 hours timeframe.

Sample webhook payload

[[code-container]] [+text-delivery-report]

{
   "timestamp": 1502221022807,
   "webhookId": 1,
   "webhookName": "ASA DLR Test",
   "resourceType": "OutboundTextDeliveryReport",
   "events": [
      {
         "timestamp": 1502221022807,
         "webhookId": 1,
         "resourceType": "OutboundTextDeliveryReport",
         "eventType": "Received",
         "resource": {
            "id": 7420017300281076000,
            "actionId": 123123123123,
            "campaignId": 123456789,
            "toNumber": "12135551234",
            "fromNumber": "12138888888",
            "timestamp": 1502221022571,
            "deliveryState": "DELIVERED",
            "deliveryCategory": "DELIVERED"
         }
      }
   ]
}

[-text-delivery-report] [[/code-container]]

Delivery categories and states

Data in Delivery Report Payload

Data	Description	Example
accountId	CallFire Account ID	1348751344
actionId	Sent text ID	1348751344
campaignId	CallFire Campaign ID	1826124237
fromNumber	Shortcode or DID used to send the text	67076
toNumber	Text recipient number	12134445555
deliveryState	Current text delivery state	See table below for possible values
deliveryCategory	Current text delivery category	See table below for possible values

Delivery Category

Value	Description
DELIVERED	Delivered to device
BOUNCED	Bounced for various reasons
OPTED_OUT	Recipient opted out
NO_DATA	Not sent or no definitive data

Delivery States

Value	Delivery Category	Description
DELIVERED	DELIVERED	Delivered to device
UNSENT_OPTED_OUT_GLOBAL	OPTED_OUT	Recipient opted out globally
UNSENT_OPTED_OUT_LOCAL	OPTED_OUT	Recipient opted out locally
GATEWAY_REJECTED	BOUNCED	Gateway rejected the message
CARRIER_REJECTED	BOUNCED	Carrier rejected the message
NOT_DELIVERED	BOUNCED	Gateway reports message not delivered (device unreachable, service denied, etc)
UNSENT_BAD_DATA	BOUNCED	Failed data validation (missing required data or failed phone number format check)
UNSENT_NO_WIRELESS_CARRIER	BOUNCED	Recipient phone number is not a wireless number
UNSENT_MESSAGE_TOO_LONG	BOUNCED	Message is too long to send (not applicable for MMS)
ORIGINATED	NO_DATA	Message has been received by text message server and is in queue
SUBMITTED	NO_DATA	Message has been submitted to gateway, but no delivery response yet
NOT_GIVEN	NO_DATA	Should not happen. We received a gateway delivery response without a delivery state.
UNKNOWN	NO_DATA	Should not happen. We received a gateway delivery response with a delivery state we don't recognize
RETRY_MMS_AS_SMS	NO_DATA	Sending as MMS failed and we will retry as SMS
QUEUED	NO_DATA	Message has been queued for delivery
ORIGINAL	NO_DATA	Message has been validated but not sent to gateway yet
DUPE	NO_DATA	Message is a duplicate, already sent
TRUNCATED	NO_DATA	Message was too long and was truncated for sending
BUFFERED	NO_DATA	Message was buffered (queued) by carrier gateway
RATE_LIMIT_EXCEEDED	NO_DATA	Carrier gateway rate limit exceeded, will be re-queued and re-attempted for up to 60 minutes
SERVICE_UNAVAILABLE	NO_DATA	Should not happen. Got a server error when sending to carrier gateway. Will be re-queued and re-attempted for up to 60 minutes
SEND_MMS_AS_SMS	NO_DATA	Sending an MMS message as SMS instead because we do have have an MMS gateway for the to_number carrier
REQUEUED_RECOVERABLE_ERROR	NO_DATA	Catch all for any other recoverable error. Will be re-queued and re-attempted for up to 60 minutes

Common State Transitions

Scenario	States
Confirmed Delivery	ORIGINAL -> QUEUED -> ORIGINATED -> SUBMITTED -> BUFFERED -> DELIVERED
Confirmed Not Delivered	ORIGINAL -> QUEUED -> ORIGINATED -> SUBMITTED -> BUFFERED -> NOT_DELIVERED
Sent, No Delivery Confirmation	ORIGINAL -> QUEUED -> ORIGINATED -> SUBMITTED -> BUFFERED
Invalid Number	ORIGINAL -> UNSENT_BAD_DATA
Non-Wireless Number	ORIGINAL -> QUEUED -> UNSENT_NO_WIRELESS_CARRIER

DeliveryCategory to TextResult mapping

DeliveryCategory	TextResult
ORIGINATED, DELIVERED	SENT
UNSENT_MESSAGE_TOO_LONG	TOO_BIG
OPTED_OUT	DNT
UNSENT_BAD_DATA	INTERNAL_ERROR
BOUNCED, UNSENT_MESSAGE_TOO_LONG, UNSENT_BAD_DATA	CARRIER_ERROR