Webhook Types and Variables
Webhook Types and Variables
This page details the properties available to each webhook type as well as the use-case for the various webhook types. The Variable column indicates what should be put within the @@
encapsulation when setting up a webhook template. The UI will assist with the variable encapsulation process.
NOTE 1: Deprecated variables are listed with a "Rather Use" column that indicates which property should rather be used. If this column is empty, it means that the variable is no longer relevant for that type of webhook.
NOTE 2: Variables are case sensitive. As an example,
ID
andId
are not the same.
1. SMS Delivery Receipts (DLRs)
Delivery Receipts (DLRs) are webhooks that provide feedback on the delivery of a single SMS.
NOTE 3:
XDateTime
variables consider the configurable offset in the API key responsible for the send. The offset is added to these webhooks types at send time.
Variable | Type | GET | POST | Description |
---|---|---|---|---|
CustomerId | string | ✅ | ✅ | An optionally supplied customer ID field. |
EventId | long | ✅ | ✅ | The ID provided by the API for the original outgoing SMS batch. |
GroupData | json | ❌ | ✅ | All the data pertaining to group sends. |
Id | integer | ✅ | ✅ | A unique value for this specific line item. |
Mcc | integer | ✅ | ✅ | The Mobile Country Code (MCC) is the country where the mobile number is registered. |
Mnc | string | ✅ | ✅ | The Mobile Network Code (MNC) is used to identify a mobile network within a country. |
PhoneNumber | string | ✅ | ✅ | The mobile number the message was sent to. |
ReceivedDateTime | string | ✅ | ✅ | DLR received date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in dd/MMM/yyyy HH:mm:ss format. |
ReceivedUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the DLR was received. |
SentData | string | ❌ | ✅ | The message content sent. Note that this field is truncated to 157 characters in the webhook data. |
SentDataPartsCount | integer | ✅ | ✅ | The number of message parts for the message content sent. |
SentDataType | string | ✅ | ✅ | The data type ("SMS" only). |
SentDateTime | string | ✅ | ✅ | Mobile network operator submission date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in dd/MMM/yyyy HH:mm:ss format. |
SentUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the message was submitted to the mobile network operator. |
Status | string | ✅ | ✅ | The status that the handset responded with (see Delivery Statuses). |
Deprecated Variables
Variable | Type | GET | POST | Rather Use |
---|---|---|---|---|
CustomerID | string | ✅ | ✅ | CustomerId |
Data | string | ✅ | ✅ | SentData |
DataType | string | ✅ | ✅ | SentDataType |
Destination | string | ✅ | ✅ | PhoneNumber |
EventID | long | ✅ | ✅ | EventId |
GRPDesc | string | ✅ | ✅ | GroupData |
GRPName | string | ✅ | ✅ | GroupData |
ID | integer | ✅ | ✅ | Id |
MsgCount | integer | ✅ | ✅ | SentDataPartsCount |
Msisdn | string | ✅ | ✅ | PhoneNumber |
NumberValue1 | string | ✅ | ✅ | GroupData |
NumberValue2 | string | ✅ | ✅ | GroupData |
NumberValue3 | string | ✅ | ✅ | GroupData |
NumberValue4 | string | ✅ | ✅ | GroupData |
NumberValue5 | string | ✅ | ✅ | GroupData |
NumberValue6 | string | ✅ | ✅ | GroupData |
Phonenumber | string | ✅ | ✅ | PhoneNumber |
Received | long | ✅ | ✅ | ReceivedUtc |
SentDataTime | string | ✅ | ✅ | SentDateTime |
UserReference | string | ✅ | ✅ | CustomerId |
2. SMS Replies (MOs)
SMS Replies are webhooks that provide feedback on the reply that someone replied with after receiving a single SMS that was sent to them.
NOTE 4:
XDateTime
variables consider the configurable offset in the API key responsible for the send. The offset is added to these webhooks types at send time.NOTE 5:
SentX
variables refer to information on the message sent.IncomingX
variables refer to information on the reply received.
Variable | Type | GET | POST | Description |
---|---|---|---|---|
Campaign | string | ✅ | ✅ | The campaign that the original message was sent for. |
CustomerId | string | ✅ | ✅ | An optionally supplied customer ID field. |
DestinationPhoneNumber | string | ✅ | ✅ | The mobile number that received the reply message. |
EventId | long | ✅ | ✅ | The ID provided by the API for the original outgoing SMS batch. |
GroupData | json | ❌ | ✅ | All the data pertaining to group sends. |
IncomingData | string | ❌ | ✅ | The message content received in the reply. Note that this field is truncated to 477 characters in the webhook data. |
IncomingDateTime | string | ✅ | ✅ | Customer reply received date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in dd/MMM/yyyy HH:mm:ss format. |
IncomingId | integer | ✅ | ✅ | A unique value for this specific line item. |
IncomingUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the message was received. |
OptOut | boolean | ✅ | ✅ | A boolean flag indicating whether an opt out was detected (true) or not (false). |
OptOutPhrase | string | ✅ | ✅ | Any opt-out phrase detected in the reply (eg. "stop", "opt-out", etc). |
SentData | string | ❌ | ✅ | The message content sent. Note that this field is truncated to 157 characters in the webhook data. |
SentDateTime | string | ✅ | ✅ | Mobile network operator submission date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in dd/MMM/yyyy HH:mm:ss format. |
SentId | long | ✅ | ✅ | A unique value for this specific outgoing line item. |
SentUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the message was submitted to the mobile network operator. |
SourcePhoneNumber | string | ✅ | ✅ | The mobile number that sent the reply message. |
Deprecated Variables
Variable | Type | GET | POST | Rather Use |
---|---|---|---|---|
CustomerID | string | ✅ | ✅ | CustomerId |
EventID | long | ✅ | ✅ | EventId |
Id | integer | ✅ | ✅ | IncomingId |
IncomingDataTime | string | ✅ | ✅ | IncomingDateTime |
IncomingID | integer | ✅ | ✅ | IncomingId |
Message | string | ✅ | ✅ | IncomingData |
Msisdn | string | ✅ | ✅ | SourcePhoneNumber |
NumberValue1 | string | ✅ | ✅ | GroupData |
NumberValue2 | string | ✅ | ✅ | GroupData |
NumberValue3 | string | ✅ | ✅ | GroupData |
NumberValue4 | string | ✅ | ✅ | GroupData |
NumberValue5 | string | ✅ | ✅ | GroupData |
NumberValue6 | string | ✅ | ✅ | GroupData |
Phonenumber | string | ✅ | ✅ | SourcePhoneNumber |
Received | long | ✅ | ✅ | IncomingUtc |
SentDataTime | string | ✅ | ✅ | SentDateTime |
SentID | long | ✅ | ✅ | SentId |
SentMessageGRPDesc | string | ✅ | ✅ | GroupData |
SentMessageGRPName | string | ✅ | ✅ | GroupData |
To | long | ✅ | ✅ | DestinationPhoneNumber |
UserReference | string | ✅ | ✅ | CustomerId |
3. Short Code Interactions
Short code interactions are webhooks that provide feedback on SMS's sent to short codes.
Variable | Type | GET | POST | Description |
---|---|---|---|---|
Id | integer | ✅ | ✅ | The short code message ID. |
IncomingData | string | ❌ | ✅ | The message content received in the reply. |
IncomingDateTime | string | ✅ | ✅ | The date and time in SAST when the message was received (dd/MMM/yyyy HH:mm:ss ). |
IncomingUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the message was received. |
Keyword | string | ✅ | ✅ | The matched keyword. |
Mcc | integer | ✅ | ✅ | The Mobile Country Code (MCC) is the country where the mobile number is registered. |
Mnc | string | ✅ | ✅ | The Mobile Network Code (MNC) is used to identify a mobile network within a country. |
PhoneNumber | string | ✅ | ✅ | The mobile number that sent the message. |
Sc | string | ✅ | ✅ | The short code. |
Deprecated Variables
Variable | Type | GET | POST | Rather Use |
---|---|---|---|---|
ID | integer | ✅ | ✅ | Id |
Message | string | ✅ | ✅ | IncomingData |
Mobile | string | ✅ | ✅ | PhoneNumber |
SC | string | ✅ | ✅ | Sc |
4. Short URL Events
Short URL events are webhooks that provide feedback on any interactions with short URLs created in our platform.
Variable | Type | GET | POST | Description |
---|---|---|---|---|
CustomerId | string | ✅ | ✅ | An optionally supplied customer ID field. |
InteractionDateTime | string | ✅ | ✅ | The date and time in SAST when the link was interacted with (dd/MMM/yyyy HH:mm:ss ). |
InteractionUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the link was interacted with. |
PhoneNumber | string | ✅ | ✅ | The mobile number the message was sent to. |
Type | string | ✅ | ✅ | This will either be "REDIRECT" or "PREVIEW" , depending on whether the URL was clicked or previewed. |
Deprecated Variables
Variable | Type | GET | POST | Rather Use |
---|---|---|---|---|
CustomerRef | string | ✅ | ✅ | CustomerId |
LandingPageName | string | ✅ | ✅ | — |
LandingPageVersion | string | ✅ | ✅ | — |
MsgNumTo | string | ✅ | ✅ | PhoneNumber |
SentID | long | ✅ | ✅ | — |
SmppId | string | ✅ | ✅ | — |
5. Landing Page Events
Landing page events are webhooks that provide feedback on any interactions with landing pages created in our platform.
Variable | Type | GET | POST | Description |
---|---|---|---|---|
CustomerId | string | ✅ | ✅ | An optionally supplied customer ID field. |
InteractionDateTime | string | ✅ | ✅ | The date and time in SAST when the link was interacted with (dd/MMM/yyyy HH:mm:ss ). |
InteractionUtc | long | ✅ | ✅ | The UTC UNIX ticks timestamp when the link was interacted with. |
LandingPageComponentId | string | ✅ | ✅ | The ID of the component on the landing page that triggered the webhook. |
LandingPageName | string | ✅ | ✅ | The name of the landing page. |
LandingPageVersion | string | ✅ | ✅ | The version of the landing page. |
PhoneNumber | string | ✅ | ✅ | The mobile number the message was sent to. |
Type | string | ✅ | ✅ | This will either be "REDIRECT" , "PREVIEW" , "AUTHENTICATION" or "CONTENT" , depending on how the user interacted with the landing page. |
Deprecated Variables
Variable | Type | GET | POST | Rather Use |
---|---|---|---|---|
CustomerRef | string | ✅ | ✅ | CustomerId |
MsgNumTo | string | ✅ | ✅ | PhoneNumber |
Updated 4 days ago