Skip to main content

Incoming message webhook

INCOMING_MESSAGE is the webhook for replies from your customers. HelloSMS calls your hookUrl once for each reply, and the channel field says how the reply arrived. It replaces INCOMING_SMS for new integrations.

Today a reply arrives as an SMS, so channel is sms.

Subscribe​

Subscribe with Subscribe to webhooks, using the type INCOMING_MESSAGE:

{
    "hookUrl": "https://mywebhook.com",
    "type": "INCOMING_MESSAGE",
    "channels": ["sms"]
}

channels is optional. It lists the channels you want replies from, sms and rcs. Leave it out to get every channel. Subscribe again with a different list to change the channels. To stop, unsubscribe. That removes the whole subscription.

The payload​

HelloSMS sends a POST request with a JSON body to your hookUrl.

SMS reply:

{
    "action": "INCOMING_MESSAGE",
    "channel": "sms",
    "message_id": "1234567890",
    "from": "46701740605",
    "to": "46701740610",
    "text": "Example incoming SMS text.\nCan be multiple lines",
    "replyType": "text",
    "timestamp": 1739710713
}
  • action: Always INCOMING_MESSAGE.
  • channel: How the reply arrived: sms or rcs.
  • message_id: A unique ID for the reply. Treat it as an opaque string.
  • from: The phone number of the customer who replied.
  • to: Your number.
  • text: The text of the reply.
  • replyType: Always text.
  • timestamp: When the reply was received, as a UNIX timestamp.
  • textHidden: Only on trial accounts. true when the text is hidden, and text is then null.

Moving from INCOMING_SMS​

INCOMING_SMS still works, but it is deprecated and carries SMS replies only. To move over, subscribe to INCOMING_MESSAGE first, and then unsubscribe from INCOMING_SMS. While you are subscribed to both, every SMS reply is sent twice, once on each webhook.

The payload of INCOMING_MESSAGE has the same fields as INCOMING_SMS, plus channel and replyType. See Webhooks and Callbacks for the INCOMING_SMS payload.

What does not arrive here​

  • STOP messages: A recipient who opts out is reported with the SIGNOFF webhook.
  • MMS: A reply to an SMS with a picture or other media attached is not sent to this webhook.