Skip to main content

Webhooks and Callbacks

HelloSMS offers two types of callbacks to keep you informed about events related to your SMS messages: API callbacks and webhooks. These callbacks provide real-time updates on message delivery status, incoming messages, and user sign-offs, enabling you to build more responsive and integrated applications.

By utilizing API callbacks and webhooks, you can create more dynamic and interactive SMS applications. These real-time updates empower you to:

  • Track message delivery status: Know exactly when your messages are delivered, failed, or queued, allowing for better troubleshooting and customer communication.
  • Respond to incoming messages promptly: Automate replies, route messages to the right department, or trigger actions based on incoming SMS content, enhancing customer engagement and satisfaction.
  • Efficiently manage user preferences: Respect opt-out requests ("STOP" messages) in real-time and update your contact lists accordingly, ensuring compliance and a positive user experience

API Callbacks​

API callbacks provide delivery status updates for messages sent through the Send SMS and Send multiple SMS messages 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 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.

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.

Webhooks​

Webhooks provide real-time notifications for specific events happening in your HelloSMS account. Currently, HelloSMS supports four types of webhook events:

  • INCOMING_MESSAGE: Triggered when a customer replies to you. See the incoming message webhook for the payload.
  • INCOMING_SMS (deprecated): Triggered when your HelloSMS account receives a new SMS message.
  • SIGNOFF: Triggered when a recipient opts out of receiving further SMS messages by sending a "STOP" keyword.
  • EVENTS: Triggered when something happens to a message you sent, such as a recipient clicking a link in it. See Events.

To subscribe to webhooks, use the Subscribe to webhooks endpoint, providing your hookUrl and the desired type (INCOMING_MESSAGE, INCOMING_SMS, SIGNOFF or EVENTS). For EVENTS you also choose which events and which messages you want.

Your hookUrl must answer with HTTP 200 within 20 seconds. Any other answer, including a redirect, counts as a failure and HelloSMS tries again after 1, 5, 15, 60 and 360 minutes, then gives up (about 7 hours after the first attempt).

Webhook Callback Formats:​

INCOMING_SMS:

Deprecated

INCOMING_SMS is deprecated. It still works and carries SMS replies only. New integrations should use the incoming message webhook.

{
    "message_id": "1234567890",
    "from": "46701740609",
    "to": "46701740610",
    "text": "Example incoming SMS text.",
    "timestamp": 1739710713,
    "action": "INCOMING_SMS"
}
  • message_id: A unique ID for the incoming SMS message.
  • from: The sender's phone number.
  • to: The recipient's phone number.
  • text: The content of the incoming SMS message.
  • timestamp: The time the message was received as a UNIX timestamp.
  • action: The action that triggered the webhook.

SIGNOFF:

{
    "message_id": "12345",
    "from": "46701740609",
    "to": "46701740610",
    "keyword": "STOPP",
    "timestamp": 1739710713,
    "action": "SIGNOFF"
}
  • message_id: A unique ID for the sign-off event.
  • from: The phone number of the user who opted out.
  • to: The recipient's phone number.
  • keyword: The keyword field typically contains STOPP or STOP to indicate a recipient opting out of messages. However, it may vary if a custom shortcode is used for opt-out.
  • timestamp: The time of the sign-off event as a UNIX timestamp.
  • action: The action that triggered the webhook.

Events​

An EVENTS webhook tells you when something happens to a message you sent. Subscribe once, then choose what you want to hear about:

{
    "hookUrl": "https://mywebhook.com/events",
    "type": "EVENTS",
    "events": ["LINK_CLICK"],
    "messages": "api"
}
  • events: Required. The string "all", or a list of event types. "all" also covers event types added later, so your endpoint should ignore types it doesn't know.
  • messages: Optional. "all" (the default) sends events for every message your account sends, including messages sent from the web app. "api" sends events only for messages sent through the API.

Subscribing again to the same hookUrl with different choices replaces the earlier ones. To stop, unsubscribe with the hookUrl and type EVENTS. Events still waiting to be sent when you unsubscribe are dropped.

LINK_CLICK: When you send a message containing a link, HelloSMS shortens the link. A LINK_CLICK event is sent the first time a person opens the shortened link, once per link. A person clicking the same link again gives no further event. A message with two links can give two events.

{
    "event_id": "EVT9C41D07A2B3E5F18",
    "message_id": "MSG4A7C19E2",
    "apiMessageId": "api-638ca85eb5c808.02026978",
    "channel": "sms",
    "to": "46701234567",
    "url": "https://example.com/offer?id=42",
    "timestamp": 1791878400,
    "action": "LINK_CLICK"
}
  • event_id: A unique ID for the click. If you have several event subscriptions, each receives the same event_id. A retry sends the same event_id again.
  • message_id: The ID of the message the link was in. Every event about the same message has the same message_id. It is not the message_id of an INCOMING_SMS webhook, which identifies a received message.
  • apiMessageId: Only present when the message was sent through the API. It is the apiMessageId that Send SMS and Send multiple SMS messages return for the message.
  • channel: How the recipient received the message: sms.
  • to: The recipient's phone number, without a leading +.
  • url: The address the person was sent to.
  • timestamp: The time of the click as a UNIX timestamp.
  • action: The event type, LINK_CLICK.

Matching an event to a message​

Use apiMessageId to find the message an event is about: it is the same ID the API returned when you sent the message. Messages not sent through the API, such as messages from the web app, have no apiMessageId. Subscribe with "messages": "api" if you only want events for API messages.

Delivery​

Events can arrive late, out of order or more than once. A failed delivery is retried as described above, and a retry sends the same event_id, so keep the event_ids you have handled and ignore repeats. Use timestamp rather than the time an event arrives to tell when something happened.