WhatsApp Webhooks

MT Event Data

MT Event Data

This event type represents all MT messages sent from the client to the end user. Each MT event includes metadata and processing context, and can be updated with a delivery status such as:

• sent: The message was successfully sent to the messaging platform.
• delivered: The message was successfully delivered to the recipient’s device.
• read: The message was opened or read by the recipient.
• failed: The message could not be delivered due to an error (e.g., invalid number, expired session, or platform error).

These events are sent to the client’s webhook endpoint to provide visibility into the message delivery lifecycle.

Common Parameters

Parameter	Data Type	Description	Required?
txId	String	Transaction identifier of the message	Yes
eventId	String	Event identifier	Yes
platform	String	Origin platform (e.g., CLU, SMS, Meta or RCS)	Yes
eventType	String	Event category (e.g., MT, MO or NOTIFICATION)	Yes
sourceEventTS	DateTime	Event timestamp	Yes
content	String	Base64-encoded representation of the structured event content	Yes
errors	String?	Error description list	No

For delivery status events such as sent, delivered, and read, the content field contains a Base64-encoded string representing a JSON object.

Event parameters with content base 64.

Code

{
"txId": "6ce710c5-b52b-4380-aed1-23d6a8f75c6c",
"eventId": "evt-abc-20250516",
"platform": "Meta",
"eventType": "MT",
"sourceEventTS": "2025-05-16T12:30:00.0000000",
"content": "InNlbmRlciI6ICI1MjExMTExMTExMTEiLAogICJtc2lzZG4iOiAiNTIxMjIyMjIyMjIyIiwKICAiY29udGFjdE5hbWUiOiAiSm9obiIsCiAgIm1lc3NhZ2VDb250ZW50IjogewogICAgImVycm9ycyI6IFsKICAgICAgewogICAgICAgICAgImNvZGUiOiAxMTAxLAogICAgICAgICAgInRpdGxlIjogIk1lc3NhZ2UgdHlwZSB1bmtub3duIiwKICAgICAgICAgICJtZXNzYWdlIjogIk1lc3NhZ2UgdHlwZSB1bmtub3duIiwKICAgICAgICAgICJkZXRhaWxzIjogIk1lc3NhZ2UgdHlwZSBpcyBjdXJyZW50bHkgbm90IHN1cHBvcnRlZCIsCiAgICAgICAgICAgIAogICAgICAgIH0KICAgICBdICAgCiAgIH0="
}

This decoded object includes key metadata related to the sent message, such as the sender (From), recipient (To), message delivery status, and, when applicable, the messageType.

The following table describes the parameters included in the content field:

Message Content Parameters

Parameter	Data Type	Description	Required?
From	String	The identifier of the sender	Yes
To	String	The recipient's phone number in international format	Yes
ToBsuid	String?	BSUID of the message recipient. Omitted when empty. See Usernames	No
status	String?	Status of the send message (send, read, delivered, fail.)	No
messageType	Object	Only for delivered messages to identify the original message type (service).	No

The phone number is not guaranteed. When the customer talks to you over a WhatsApp username, Meta omits it and the identifier arrives in the BSUID property instead. Do not use the phone number as the primary key of the contact — see BSUID in Webhooks.

Event parameters without content base 64.

Code
{
"txId": "6ce710c5-b52b-4380-aed1-23d6a8f75c6c",
"eventId": "evt-abc-20250516",
"platform": "Meta",
"eventType": "MT",
"sourceEventTS": "2025-05-16T12:30:00.0000000",
"content": {
  "From": "521111111111",
  "To": "521222222222",
  "status": "delivered",
  "messageType": "service"
}
}

For failed status events, the errors field contains an array of objects that represent the reason(s) the message could not be delivered.

Each object includes the following parameters:

Error Parameters

Property	Data Type	Description	Required?
code	Integer	Numeric code representing the type of error	Yes
message	String	Message explanation of the error	Yes
details	Array String	Technical or contextual error details (if available)	Yes

Event with Error Parameters

Code
{
"txId": "6ce710c5-b52b-4380-aed1-23d6a8f75c6c",
"eventId": "evt-abc-20250516",
"platform": "Meta",
"eventType": "MT",
"sourceEventTS": "2025-05-16T12:30:00.0000000",
"content": {
  "From": "521111111111",
  "To": "521222222222",
  "status": "delivered",
  "messageType": "service"
},
"errors": [
      {
          "code": 1101,
          "message": "Message delay detected",
          "details": [
              "Latency over 5s",
              "Queue overflow retry"
          ]
      }
  ]
}