SMS Status and Delivery Receipt

For every SMS that you send you can check if it was delivered to the recipient’s phone or not.

HTTP Method & Headers

The HTTP method is GET using this URL:

https://api.engagespark.com/v1/organizations/[organizationId]/messages/[messageId]/

Replace [organizationId] (e.g., 123) with your orgId and [messageId] (e.g., SMS20190723T154425-123-123) with your message’s Id. Don’t forget to remove the brackets [ ].

Find the messageId in the JSON response body of your SMS API POST Request. See sample JSON response here: Send SMS to Phone Number API or Send SMS to Contact API. Or, see sample below:

Sample JSON Response (from Send SMS to Phone Number API POST request)

{
  "error": "",
  "messageId": "SMS20190723T154425-123-0123",
  "estimateParts": 1,
  "estimateMicro": 20000,
  "estimate": "0.02",
  "deliveryDeadline": "2019-07-24T15:39:41.071667761Z",
  "contactId": 0,
  "to": "639123456789",
  "message": "Sample message to you."
}

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {API_KEY}
Content-type application/json

Sample URL:

https://api.engagespark.com/v1/organizations/123/messages/SMS20190723T154425-123-0123/

Sample JSON Response:

{
    "id": "SMS20190723T154425-123-0123",
    "direction": "egress",
    "created": "2019-07-24T07:57:11.13269Z",
    "sender": "engageSPARK",
    "recipient": "639123456789",
    "contactId": 0,
    "engagementId": 0,
    "engagementFlowId": 0,
    "engagementRunId": 0,
    "engagementPartId": "",
    "pricePerPart": 20000,
    "successPartCount": 1,
    "successT": "2019-07-24T07:57:12.533444Z",
    "message": "Sample message to you.",
    "deliveredToTelco": true,
    "deliveredToPhone": "confirmed",
    "firstName": "",
    "lastName": "",
    "fullPhoneNumber": ""
}

“deliveredToTelco” – this can be either true or false. True if the message is successfully delivered to the telecom (mobile network operator). Can be false if there was an error or while the message is still being delivered.

“deliveredToPhone” – this can show either unknown/confirmed/failed.

  • unknown – means we haven’t received a delivery receipt from the telecom. This can happen either when (a) deliveredToTelco is false OR (b) deliveredToTelco is true but the vendor hasn’t sent us the delivery receipt, yet.
  • confirmed – means we received the delivery receipt from the telecom and it says the SMS WAS delivered.
  • failed – means we received the delivery receipt from the telecom and it says the SMS was not delivered.

Note: Not all telcos support delivery receipts and they are not always reliable, it varies per telco per country. Contact us to know if delivery receipts are available in your program country.

Have questions or need a little extra help?

Get in touch with us via:

facebook-logo    messenger-logo    twitter-logo

Or drop us a message here: