Skip to main content

Delivery callbacks

API callbacks provide delivery status updates for messages sent through the Send SMS, Send multiple SMS messages and Send RCS endpoints. To enable API callbacks, set the sendApiCallback parameter to true when sending your message.

Callback URL

Set the URL to call for a message with the callbackUrl parameter of the Send SMS or Send RCS request. Passing callbackUrl also turns on API callbacks for that message, so you don't need to set sendApiCallback as well. The URL must use https, be at most 2048 characters long, and point to a host that resolves to a public address (private, loopback, link-local and cloud metadata addresses are rejected). With Send multiple SMS messages you can set callbackUrl on each message, or once for the whole batch.

To use one callback URL for all your messages without passing callbackUrl each time, please contact us and we will configure a default URL for your account.

Every callback is signed. To check that a callback comes from HelloSMS, see Verifying webhooks and callbacks.

Callback format​

HelloSMS will send a POST request to your callback URL with a JSON payload whenever a sent message's status updates.

Callback example:

{
"apiMessageId": "12345",
"status": "delivered",
"timestamp": 1672531199,
"callbackRef": "someReference"
}
  • apiMessageId: The unique ID of the message sent via the API.
  • status: The current delivery status of the message. Possible values are:
    • delivered: The message was successfully delivered to the recipient's phone.
    • failed: Permanent failure, usually indicating an invalid or inactive phone number.
    • not delivered: Temporary failure, often due to the recipient's phone being off or offline.
  • timestamp: The time of the status update as a UNIX timestamp.
  • callbackRef: A custom identifier included in the original API request for internal reference.

Callbacks for RCS messages

For a message sent with Send RCS you get one callback, when the message reaches its final result. A read receipt is not reported as a status of its own, and there is no read status. To hear when a recipient reads a message, subscribe to the READ event of the events webhook. A message that fails before it reaches our delivery provider doesn't produce a callback.

  • channel: Only included for messages sent with Send RCS. Callbacks for messages sent with Send SMS and Send multiple SMS messages don't have it. Possible values are:

    • rcs: The message was delivered as an RCS message.
    • sms: The message was delivered as the SMS fallback, or was sent as an ordinary SMS because the number is outside your account's country.

    For a message that failed, channel is the last channel HelloSMS tried.

Callback example for a message sent with Send RCS:

{
"apiMessageId": "a1b2c3d4e5",
"status": "delivered",
"timestamp": 1791878400,
"callbackRef": "order-4471",
"channel": "rcs"
}