Delivery receipts for outbound SMS

  • Delivery Receipts (DR) are webhooks for delivery statuses: POST requests sent by the Wavecell platform either in JSON (latest version of the webhook) or XML (older version) format to the delivery reports callback URL configured for your account.
  • Whenever a message has a new delivery status associated with the delivery stage it is in, Wavecell sends out a POST request with the new status to the callback URL.
  • You can configure your default delivery reports callback URL for your account by contacting Wavecell support team.
  • You can also overwrite the default callback URL on a per-message / per-batch-of-message basis by specifying a different dlrCallbackUrl value in your API requests when sending a message or a batch of messages.
  • Delivery reports are sent using the following format to your configured callback URL:

Sample of delivery report - JSON (latest version):

{
   "umid":"371e8f64-195b-e711-8144-020897df54591",
   "timestamp":"2019-01-18T07:08:16.1537626Z",
   "status":"REJECTED BY DEVICE",
   "statusCode":41,
   "error":"Absent subscriber",
   "errorCode":1,
   "source":"INFO",
   "subAccountId":"wavecell_demo",
   "version":6,
   "destination":"+6512345678",
   "batchId":"9d5f44fc-d2cf-40e2-a9e3-7319550ca092",
   "clientMessageId":"clid_111",
   "clientBatchId":"bid_77789",
   "smsCount":3,
   "price":{
      "total":0.33,
      "perSms":0.11,
      "currency":"EUR"
   }
}

Parameters:

  • umid: unique identifier generated by Wavecell for the message
  • timestamp : the notification date and timestamp in ISO 8601 ISO format yyyy-mm-ddThh:mm:ss.fffffZ.
  • status : the status of the message
  • statusCode : the numeric code associated with the delivery status
  • error : if the message cannot be delivered or if an error occurs, the reason for the error.
  • errorCode : if the message cannot be delivered or if an error occurs, the code for the error
  • source : the source (i.e: senderID) used to deliver the message
  • subAccountId : the subaccountid used to deliver the message
  • version : the version of the delivery report webhook
  • destination : destination phone number where the SMS was sent (E.164 format)
  • batchId : the unique identifier generated by Wavecell for the message if sent using by batch (using the many endpoints)
  • clientMessageId : custom message ID used when submitting the SMS to Wavecell
  • clientBatchId : custom batch ID used when submitting the batch of SMS to Wavecell (using the many endpoints)
  • smsCount : number of parts in the SMS (based on characters count)
  • price :
    • total: price charged by Wavecell for sending the SMS
    • perSms: price per part of message
    • currency: billing currency

If the format of the DLR that you receive is different from the example above, it means that your account is set to use a previous version of the delivery reports - please send a request to Wavecell Support to be upgraded to the last delivery reports version.

Sample of delivery report - XML (deprecated)

<DeliveryReport version="3">
  <UMID>371e8f64-195b-e711-8144-020897df54591</UMID>
  <DateTimeStamp>2019-01-18T07:08:16.1537626</DateTimeStamp>
  <Status>DELIVERED TO DEVICE</Status>
  <Reason />
  <Source>INFO</Source>
  <SubAccountId>wavecell_demo</SubAccountId>
  <Attempt>0</Attempt>
  <ErrorCode>1</ErrorCode>
  <Destination>6512345678</Destination>
  <Price>0.012</Price>
  <Currency>EUR</Currency>
  <ClientMessageId>clid_111</ClientMessageId>
  <ClientBatchId>bid_77789</ClientBatchId>
</DeliveryReport>

Parameters:

  • UMID: unique identifier generated by Wavecell for the message
  • DateTimeStamp : the notification date and timestamp
  • Status : the status of the message
  • Source : the source (i.e: senderID) used to deliver the message
  • Subaccountid : the subaccountid used to deliver the message
  • Attempt : attempt to deliver the message
  • Errorcode : if the message cannot be delivered or if an error occurs, the code of the error.
  • Destination : destination phone number where the message was sent
  • Price : price billed by Wavecell for the message
  • Currency : billing currency for price
  • ClientMessageId : custom message ID submitted when requesting for the message to be sent
  • ClientBatchId: custom batch ID submitted when using the many (batch) method to submit message

Message Status

The status of a message can have the following values:

Status Code Description
RECEIVED 10 the message has been received on Wavecell platform and is being processed before being sent to the carrier
PROCESSED 20 the message has been sent to the carrier and did not receive an acknowledgement from the carrier yet
REJECTED BY WAVECELL 21 the message has been rejected by Wavecell (invalid number, insufficient credit, etc…)
DELIVERED TO CARRIER 30 the message has been delivered to the carrier and the carrier has acknowledged its reception for processing
REJECTED BY CARRIER 31 the messages has been rejected by the carrier
DELIVERED TO DEVICE 40 the message has been successfully delivered to the destination handset
REJECTED BY DEVICE 41 the message has been rejected by the destination handset
READ 50 the message has been read by the recipient (available on chat apps channels only)