Webhooks

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.

Webhooks first must be registered, see Setting up Webhooks to learn more.

Webhooks Event Payloads

Optional Fields

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.

status

MTADeliveryStatus

The delivery status. See MTA Delivery Status Codes.

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

The webhook event type, identifying it as delivery status.

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

status

MTADeliveryStatus

The delivery status. See MTA Delivery Status Codes.

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

The webhook event type, identifying it as delivery status.

V3 Delivery Status 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.

timestamp

string | date:UTC:ISO-8601

A date string. The timezone and format are specified.

status

number |MTADeliveryStatus

The delivery status code. See MTA Delivery Status Codes.

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

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.

optInType

enum NumberOptInType

Identifies how the method used to opt-in, see Number Opt-In Types.

type

type: MTAWebhook.NUMBER_OPT_IN

The webhook event type, identifying it as number opt-in.

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

optInType

enum NumberOptInType

Identifies how the method used to opt-in, see Number Opt-In Types.

type

MTAWebhook.NUMBER_OPT_IN

The webhook event type, identifying it as number opt-in.

V3 Number Opt-In Payload
Field
Type
Description

fromNumber

string

The number the message was sent from.

toNumber *

string

The number the message was sent to.

senderName *

string

The sender name used to pre-populate the "To:" field for iMessages.

type

enum NumberOptInType

The webhook event type, identifying it as number opt-in.

timestamp

string | date:UTC:ISO-8601

A date string. The timezone and format are specified.

Number Opt-In Types

One of the fields of the number opt-in webhook is optInType which will return one of the following types, used to indicate the method used to opt-in:

enum NumberOptInType {
    SMS = 'sms',
    EMAIL = 'email',
    IMessage = 'imessage',
    RCS = 'rcs',
}

Last updated

Was this helpful?