Callback URL For Delivery Receipts API
After you send SMS using PaaSoo Global SMS / Telecom Services, you can receive the SMS Delivery Receipt (DLR) through this Callback mechanism. Please note: These Delivery Receipts (DLR) are usually returned by the Operator side. Therefore, in different countries/regions, the Operator's reporting mechanism and timeliness may vary. In some areas, the reports may not be complete or reliable enough to fully reflect the final delivery status.
By integrating this Callback feature, you can synchronously update the SMS delivery results in your business database or front-end system, thereby better managing and tracking whether each SMS has been successfully Delivered to the user's terminal. This document will introduce you to the Callback method, parameter meanings, and common reception processing examples.
1. Callback Description
- HTTP Method:
GET - Callback URL: The
USER_CALLBACK_URLpre-configured in the PaaSoo platform (provided by you). - Callback Timing: When the target Operator generates or updates a Delivery Receipt, PaaSoo will push the status via a GET request to your specified Callback URL.
- Retry Policy: If your server fails to correctly return HTTP 200, PaaSoo will attempt to resend at intervals of 5 / 10 / 30 minutes.
2. Callback Example
After a Delivery Receipt is generated, the PaaSoo platform will invoke your Callback URL in the form of a GET request as follows:
https://USER_CALLBACK_URL?type=dlr&messageid=MESSAGE_ID&to=12025550199&status=0&statuscode=delivered&errcode=0&network=52099&price=0.03&counts=1×tamp=1686045579378
Note: The plus sign (+) in the timestamp parameter will be encoded as %3A or other escape characters in the URL, depending on the actual URL encoding method.
3. Parameter Description
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | string | Callback message type, fixed as dlr for DLR callbacks. | dlr |
| messageid | string | The Message ID returned when the send request was made, used to uniquely identify an SMS request. | 015bd4-d6dfa7-58w |
| to | string | SMS Destination Number, in the format of Country Code + phone number (without leading 00 or +). | 12025550199 |
| status | integer | Status value:
| 0 |
| statuscode | string | Detailed status code:
| delivered |
| errcode | string | The error code returned by the Operator (if any), corresponding to statuscode:
| 0 - Normal |
| network | string | The Operator network of the Destination Number, such as an MCC+MNC combination. | 52099 |
| price | number | Single SMS billing price (unit: USD or determined by the account Billing currency). | 0.03 |
| counts | integer | Billing Count (may be affected by SMS length, GSM7/Unicode conversion, split billing, etc.). | 1 |
| ref | string | Customer-defined parameter used to correlate the initial request with the PaaSoo response (returned via asynchronous notification or query result). | |
| timestamp | long | The timestamp when the Delivery Receipt was generated, in milliseconds. | 1686045579378 |
4. Callback Response and Retry
- Successful Response: After you receive the Callback and complete processing, you need to return HTTP 200 or a similar success response to inform PaaSoo that the Callback has been correctly received.
- Retry Mechanism: If PaaSoo does not receive a valid success response, the system will retry once at intervals of 5 minutes, 10 minutes, and 30 minutes respectively. If a 200 response is still not received, subsequent retries will be abandoned.
- Recommendation: In an actual production environment, be sure to add logging or database insertion logic for Callbacks to prevent duplicate data caused by multiple retries. Deduplication can be performed using
messageid.
5. Best Practices and Precautions
- Security:
- It is recommended to use HTTPS encryption in the Callback URL to ensure data transmission security.
- Security control can be strengthened by verifying the source IP, checking Signature parameters, etc., to avoid malicious invocations.
- Parameter Storage:
- Be sure to record core fields such as
messageid,to, andstatuscodeto support subsequent reconciliation and log analysis. - If you need to compute Billing and deduction status, you can record the
priceandcountsfields.
- Be sure to record core fields such as
- Idempotent Processing:
- If the same DLR Callback arrives multiple times (which may happen under retry status), please use
messageidfor idempotency checks to avoid duplicate database entries and processing.
- If the same DLR Callback arrives multiple times (which may happen under retry status), please use
- Compatibility:
- Some Operators may not return the final status on time, or delay Callbacks when the network is unstable.
- Some Operators may not provide complete
errcodedetails. - Since Delivery Receipts depend on the Operator side, their accuracy may be limited in some countries or regions and require extra attention.
6. Summary
The above is the relevant description and implementation example of the PaaSoo platform pushing SMS Delivery Receipts (DLR) to the user's specified Callback URL. Since the reliability of such reports in different countries or regions depends on the synchronization mechanisms of local Operators, you may need to evaluate the final delivery status based on your business scenarios. By setting up a DLR Callback receiver, you can obtain more comprehensive and real-time monitoring capabilities throughout the entire SMS delivery process.
If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.