Events webhook
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.The event types are
LINK_CLICK,VIEW_IN_BROWSER,READandTAP.READandTAPare for RCS only. -
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
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": "46701740610",
"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 sameevent_id. A retry sends the sameevent_idagain.message_id: The ID of the message the link was in. Every event about the same message has the samemessage_id. It is not themessage_idof anINCOMING_SMSwebhook, which identifies a received message.apiMessageId: Only present when the message was sent through the API. It is theapiMessageIdthat Send SMS and Send multiple SMS messages return for the message.channel: How the recipient received the message:smsorrcs. An RCS message that fell back to SMS sayssms.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.
VIEW_IN_BROWSER: Not a link click. RCS messages have a view-in-browser page, and a VIEW_IN_BROWSER event is sent the first time a person opens it. The payload is the same as for LINK_CLICK, but it has no url field and action is VIEW_IN_BROWSER.
{
"event_id": "EVT3B7E52A90C1D4F66",
"message_id": "MSG4A7C19E2",
"apiMessageId": "api-638ca85eb5c808.02026978",
"channel": "rcs",
"to": "46701740610",
"timestamp": 1791878460,
"action": "VIEW_IN_BROWSER"
}
READ: RCS only. A READ event is sent when the recipient reads an RCS message, once per message. If the message is read again, no further event is sent. Read receipts come only through this event, never on the delivery callback.
{
"event_id": "EVT5D2A8E71B09C3F44",
"message_id": "MSG4A7C19E2",
"apiMessageId": "api-638ca85eb5c808.02026978",
"channel": "rcs",
"to": "46701740610",
"timestamp": 1791878520,
"action": "READ"
}
The fields are the same as for LINK_CLICK, except that channel is always rcs, there is no url field, timestamp is the time the message was read, and action is READ.
TAP: RCS only. A TAP event is sent when the recipient taps a button or suggestion of an RCS message that opens something or shares something: an openUrl, dial, viewLocation, shareLocation or createCalendarEvent button. It is also sent for a tap on a link or button on the view-in-browser page of the message. Replies and opt-out chips are not taps. They arrive as incoming messages.
A TAP event is sent for the first tap on each button, so a recipient who taps the same button again gives no further event. Different buttons of the same message give one event each.
{
"event_id": "EVT7F10C4B6A2D85E93",
"message_id": "MSG4A7C19E2",
"apiMessageId": "api-638ca85eb5c808.02026978",
"channel": "rcs",
"to": "46701740610",
"source": "message",
"target": {
"type": "openUrl",
"caption": "See the offer",
"url": "https://example.com/offer?id=42",
"card": null,
"index": 0
},
"timestamp": 1791878580,
"action": "TAP"
}
The fields are the same as for LINK_CLICK, except that there is no url field at the top level and timestamp is the time of the tap. action is TAP. A TAP event also has:
source: Where the tap happened.messageis a button in the RCS message itself.pageis a link or button on the view-in-browser page.target: What was tapped.type: The kind of button, as you sent it:openUrl,dial,viewLocation,shareLocationorcreateCalendarEvent. A link on the view-in-browser page has the typelink.caption: The text on the button. It isnullwhen the button has none, and alwaysnullfor alink.- The values you gave the button, depending on its
type:urlforopenUrlandlink,phoneNumberfordial,latitude,longitudeandlabelforviewLocation, andstartTime,endTime,titleanddescriptionforcreateCalendarEvent. A value the button doesn't have is left out.shareLocationhas none. card: The number of the card in a carousel, ornullfor a button that isn't on a card.index: The position of the button, or of the link on the view-in-browser page. It isnullwhen HelloSMS could not match the tap to a button of the message. Thentypeandcaptionare what the phone reported, and no other values are included.
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 in Webhooks and callbacks, 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.