View the expected webhook event payloads to your custom defined endpoints
Here you can see the data that is sent in notification requests to your customer provided endpoints. The only requirement for a customer defined endpoint is that the response has a 200 HTTP status code.
Some fields may not always be included in the webhook payload, these are indicated with: *. These fields may either be missing from the payload or have a NULL value.
All other fields below are always expected in the webhook payload.
The payloads documented below describe the expected data to the endpoints you (as an MTA customer) must implement in order to successfully receive notifications.
Versions
Our latest webhook version is V3. If you haven't specifically requested to use or remain on an earlier version, you will receive this latest version of V3 payloads. Previous versions (V1, V2) are also included below.
Formats
Dynamic fields may also include the following format specifications:
phone_national - A phone number in the national format. (Ex:5555555555)
phone_e164 - A phone number in E164 format (Ex:[+] [country code] [subscriber number including area code] max. 15 digits)
enum - A field with a pre-defined list of values.
date - A date string. The timezone and format are specified.
Tags
Many the following payloads have the optional tags field which is an object of any tags provided by the customer when the message was sent.
Example:
"tags": {
"key": "value"
}
Delivery Status
V1 Delivery Status Payload
Field
Type
Description
destinationNumber
string
The number the message was sent to.
messageId
number
The MTA internal id of the outbound message.
externalId
string
The id provided by the customer when the message was sent.
An object of any tags provided by the customer when the message was sent.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
type
MTADeliveryStatus
The webhook event type, identifying it as delivery status.
MTA Delivery Status Codes
One of the fields of the delivery status webhook is status which will return a code that is associated with the following statuses:
QUEUED = 1,
SENDING = 2,
SENT = 3, // provider sent to carrier
DELIVERED = 4,
SENDING_FAILED = 5, // something failed on the provider end
DELIVERY_FAILED = 6, // sent to carrier, but failed to deliver
DELIVERY_UNCONFIRMED = 7, // no response from carrier
DELIVERY_REJECTED = 8, // blocked by carrier
UNDELIVERED = 9, // handset is turned off, out of coverage, or something else of that nature
INVALID_NUMBER = 10,
STOPPED_NUMBER = 11,
LANDLINE = 12,
SEND_REJECTED = 13, // blocked by provider
QUEUEING_FAILED = 14 // carrier failed to acknowledge message
Message Reply
V1 Message Reply Payload
Field
Type
Description
originationNumber
string
The number that the inbound message was sent from.
destinationNumber
number
The number that the inbound message was sent to.
message
string
The content of the inbound message.
messageId
number
The internal MTA id for the inbound message.
externalId
string
The customer provided id from the last outbound message sent to the origination number.
previousMessageId
string
The internal MTA id for the last interaction with the outbound number. This could be an outbound id or an inbound id, whichever happened last.
isOptOutMessage
boolean
If true, indicates the inbound message is considered an opt-out request.
tags *
<string, string>
An object of any tags provided by the customer from the last outbound message sent to the origination number.
url *
string
The URL of the message, if it was an MMS and had an image attached.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
type
MTAWebhook.MESSAGE_REPLY
The webhook event type, identifying it as message reply.
V2 Message Reply Payload
Field
Type
Description
originationNumber
string
The number that the inbound message was sent from.
destinationNumber
string
The number that the inbound message was sent to.
message
string
The content of the inbound message.
messageId
number
The internal MTA id for the inbound message.
externalId
string
The customer provided id from the last outbound message sent to the origination number.
previousMessageId
string
The internal MTA id for the last interaction with the outbound number. This could be an outbound id or an inbound id, whichever happened last.
isOptOutMessage
boolean
If true, indicates the inbound message is considered an opt-out request.
tags *
<string, string>
An object of any tags provided by the customer from the last outbound message sent to the origination number.
url *
string
The URL of the message, if it was an MMS and had an image attached.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
type
MTAWebhook.MESSAGE_REPLY
The webhook event type, identifying it as message reply.
V3 Message Reply Payload
Field
Type
Description
fromNumber
string |phone_e164
The number that the inbound message was sent from.
toNumber *
string |phone_e164
The number that the inbound message was sent to.
replyId
string
The MTA internal id of the message reply.
externalId *
string
The customer provided id from the last outbound message sent to the origination number.
message
string
The content of the inbound message.
messageId *
number
The internal MTA id for the inbound message.
url *
string
The URL of the message, if it was an MMS and had an image attached.
timestamp
string | date:UTC:ISO-8601
A date string. The timezone and format are specified.
tags *
<string, string>
An object of any tags provided by the customer from the last outbound message sent to the origination number.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
Message Send
V1 Message Send Payload
Field
Type
Description
destinationNumber
string
The number the message was sent to.
messageId
string | number
The MTA internal id of the outbound message.
externalId
string
The id provided by the customer when the message was sent.
message
string
The content of the outbound message.
url
string
The URL of the message, if it was an MMS and had an image attached.
tags *
<string, string>
An object of any tags provided by the customer when the message was sent.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
type
MTAWebhook.MESSAGE_SEND
The webhook event type, identifying it as message send.
V2 Message Send Payload
Field
Type
Description
destinationNumber
string
The number the message was sent to.
messageId
number
The MTA internal id of the outbound message.
externalId
string
The id provided by the customer when the message was sent.
message
string
The content of the outbound message.
url
string
The URL of the message, if it was an MMS and had an image attached.
tags *
<string, string>
An object of any tags provided by the customer when the message was sent.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
type
MTAWebhook.MESSAGE_SEND
The webhook event type, identifying it as message send.
V3 Message Send Payload
Field
Type
Description
fromNumber *
string |phone_e164
The number that the message was sent from.
toNumber
string |phone_e164
The number the message was sent to.
messageId
string
The MTA internal id of the outbound message.
externalId *
string
The id provided by the customer when the message was sent.
message
string
The content of the outbound message.
url *
string
The URL of the message, if it was an MMS and had an image attached.
timestamp
string | date:UTC:ISO-8601
A date string. The timezone and format are specified.
tags *
<string, string>
An object of any tags provided by the customer when the message was sent.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
Number Opt-In
V1 Number Opt-In Payload
Field
Type
Description
originationNumber
string
The number the message was sent from.
destinationNumber
string
The number the message was sent to.
senderName *
string
The sender name used to pre-populate the "To:" field for iMessages.
