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 SMS.

Callback url configuration

To configure your callback URL, please contact us for assistance.

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 two types of webhook events:

• INCOMING_SMS: 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.

To subscribe to webhooks, use the Subscribe to webhooks endpoint, providing your hookUrl and the desired type (INCOMING_SMS or SIGNOFF).

Webhook Callback Formats:

INCOMING_SMS:

{
    "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.