SMS Delivery Receipts in XML
Delivery receipts let you know whether a message has been delivered. We forward them to you by making an HTTP request to a URL of your choice. Your server must respond with a 200, OK, status code to indicate successful processing of the delivery receipt.
The easy way
Setting up default delivery receipt parameters on your account removes the need to specify the parameters on each request.
- Login to Clockwork and choose “Delivery Receipts” under the “Sending” menu option
- Enter your server URL
- Choose a delivery receipt type
- Save your settings
It takes around 30 minutes for the new defaults to be applied to your account. We make HTTP calls on port 80 and HTTPS on port 443, so you shouldn’t need to open any more ports.
The manual way
DlrType 1: HTTP GET
Sent to your server using a standard HTTP GET. When sending an SMS set DlrContent to the query string you would like to receive, use the merge parameters to signal where the API should fill in values. All the merged values will be UrlEncoded.
DlrType 2: HTTP POST
The content type will be set to x-www-form-urlencoded so the request appears to your server as a form submission. Set DlrContent to the form fields you would like to receive, using the merge parameters to signal where the API should fill in values. All the merged values will be UrlEncoded.
DlrType 3: XML POST
An HTTP POST with the content type set to text/xml containing the XML specified in DlrContent when sending the message. The XML should use the merge parameters to signify where the API shold replace values. All merged parameters will be XML Encoded.
DlrType 4: Bulk XML
The bulk delivery receipt option will send you up to 100 delivery receipts in a single HTTP request with the content type set to text/xml. For customers sending large volumes of messages, this speeds up receipts as it removes the overhead of creating many separate connections and may reduce the load on your server. As a result of this improved efficiency there a couple of restrictions, the content cannot be customised and you must reply to each delivery receipt.
It’s important to note that using the bulk XML option will never slow down your delivery receipts, if they’re slowly trickling in one at a time from the mobile network we’ll forward them as soon as they arrive rather than wait for a batch to build up.
These parameters can be used in your DlrContent string and will be replaced before making the request. To use them simply surround them with # symbols, e.g. #TO#. These parameters must always be specified in upper case.
The Clockwork Message ID returned when you sent the message.
Phone number the message was sent to
From address of the text message
Delivery status of the message.
The detail code provides more information on why a message has failed. Sometimes the mobile network doesn’t provide a reason, in these cases it will be set to unknown (1).
Your unique ID, if provided, specified when sending the SMS.
HTTP GET or POST
XML POST (Type 3)
1 2 3 4 5 6 7 <!--?xml version="1.0" encoding="utf-8"?--> <Dlr> <MsgId>#MSG_ID#</MsgId> <Status>#STATUS#</Status> <Detail>#DETAIL#</Detail> <To>#TO#</To> </Dlr>
1 2 3 4 5 6 7 <!--?xml version="1.0" encoding="utf-8"?--> <Dlr> <MsgId>AB_123456</MsgId> <Status>DELIVRD</Status> <Detail>0</Detail> <To>441234567980</To> </Dlr>
With the bulk XML delivery receipts the receiving script must acknowledge each delivery receipt within the request. The response must contain the delivery receipt ID (DlrID) and a status (Response) indicating whether it has been processed correctly. Valid values for Response are “ok” and “error”. The DlrContent parameter is not used with this type.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 <?xml version="1.0" encoding="utf-8"?> <DlrList> <Dlr type="SMS"> <DlrID>CD_123456</DlrID> <ClientID>client1</ClientID> <MsgID>AB_123456</MsgID> <Status>ENROUTE</Status> <DestAddr>441234567890</DestAddr> <ErrCode>1</ErrCode> <SrcAddr>From</SrcAddr> <SubmitDate>20111021095428</SubmitDate> <StatusDate>20111021095433</StatusDate> </Dlr> <Dlr> <DlrID>CD_123457</DlrID> <ClientID>client2</ClientID> <MsgID>AB_123457</MsgID> <Status>DELIVRD</Status> <DestAddr>441234567891</DestAddr> <ErrCode>0</ErrCode> <SrcAddr>From</SrcAddr> <SubmitDate>20111021095428</SubmitDate> <StatusDate>20111021095433</StatusDate> </Dlr> </DlrList>
1 2 3 4 5 6 7 8 9 10 <!--?xml version="1.0" encoding="utf-8"?--> <DlrList_Resp> <Dlr_Resp> <DlrID>CD_123456</DlrID> <Response>ok</Response> </Dlr_Resp> <Dlr_Resp> <DlrID>CD_123457</DlrID> <Response>ok</Response> </DlrList_Resp>