Platform Events Reference

message

Triggered whenever a message's delivery status changes, or when an inbound message is received. Each status transition fires a separate event with a matching event.

Outbound message status events:

All outbound status events share one payload shape. Only event, payload.message_status, and the timestamps change between sub-types; the Status Definitions table below lists every pairing.

{
  "field": "message",
  "event": "message.delivered",
  "timestamp": "2025-10-31T12:15:42Z",
  "payload": {
    "updated_at": "2025-10-31T12:15:42Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "outbound_number": "+1987654321",
    "message_status": "DELIVERED",
    "channel": "sms",
    "body": "Hi Jane, your order has been confirmed."
  }
}

Messages that are held or suppressed by platform policy emit three additional sub-types with the same payload shape:

• message.scheduled: the send fell inside the recipient's quiet hours and is deferred, not failed. Sent evaluates quiet-hours windows per channel against the rules for the recipient's country and time zone, both derived from the recipient's phone number. The event carries message_status: "SCHEDULED". Sent releases the message automatically when the recipient's quiet hours end and it continues through the normal send pipeline, so later status events (message.sent, message.delivered, and so on) follow. SCHEDULED is not a terminal status.
• message.filtered: a policy gate suppressed the send before any provider call. Either the recipient opted out or is on your phone-channel suppression list, or your routing rules denied the send. The message is not dispatched. payload.reason_code says which: BUSINESS_004 for an opted-out or suppressed recipient, DELIVERY_004 for a denied destination.
• message.blocked: a precondition gated the send: an account-level one such as insufficient balance or an onboarding message quota, a template that is not approved for sending, or a free-form send to a contact with no open conversation. The message is not dispatched. payload.reason_code names the precondition, for example BUSINESS_003 for the balance or BUSINESS_020 for the onboarding limit.

Why a message didn't go out. message.failed, message.filtered and message.blocked carry payload.reason_code and payload.reason. reason_code is a stable code from the Error Catalog to branch on; reason is a sentence to show a person, and its wording may improve. A cause the API also rejects synchronously keeps the same code on the message: an opted-out recipient is BUSINESS_004 whether the send request was refused or a later filter stopped it. Causes only a message outcome can have are DELIVERY_001 to DELIVERY_016. The codes are Sent's classification of the outcome, never a carrier's or provider's own code. Both fields are omitted on every other sub-type.

{
  "field": "message",
  "event": "message.blocked",
  "timestamp": "2025-10-31T12:15:42Z",
  "payload": {
    "updated_at": "2025-10-31T12:15:42Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "outbound_number": "+1987654321",
    "message_status": "BLOCKED",
    "channel": "sent",
    "body": null,
    "reason_code": "BUSINESS_003",
    "reason": "The account balance is too low to send this message. Add funds to resume sending"
  }
}

The rendered body. payload.body carries the message text as plain text. The field is always present, so read it and test for null rather than testing whether the key exists. When it holds a value, that value is the render for the same event's channel, which lets you read the two fields as one fact: the copy that was dispatched on message.sent, message.delivered, message.read and a carrier-reported message.failed, and the copy that would have gone out on message.filtered, message.blocked and a pipeline-side message.failed.

null means Sent is not asserting a body for the event. Three cases produce it:

• message.queued, message.routed and message.scheduled, which all fire before routing picks a channel.
• A message.filtered, message.blocked or message.failed whose channel is a pseudo-channel (sent or auto). The send was stopped before routing picked a channel, and a template can author different copy per channel, so there is no single body to name.
• A delivery report for an attempt the message has since been rerouted away from.

Two limits to build the handler around. The body is plain text only: a WhatsApp or RCS header, footer and buttons are not published here, so a short body does not mean the message had no header, and a message with buttons looks the same as one without. And the body is truncated at 3072 characters. Call GET /v3/messages/{id} when you need the full composed message.

The inbound counterpart is text on message.received, which carries what the contact sent. The names differ, so a handler that threads a conversation together reads body on the outbound events and text on the inbound one.

Outbound Message Event Fields (all outbound sub-types):

Inbound message event (message.received):

Fires when an end-user sends a message to one of your provisioned numbers, for example, a reply to an outbound campaign, a STOP/START/HELP keyword on SMS, or a free-text reply on WhatsApp. The payload shape is different from outbound status events:

{
  "field": "message",
  "event": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "message_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "updated_at": "2025-10-31T10:10:40Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "text": "Hello, I have a question about my order",
    "channel": "sms",
    "received_at": "2025-10-31T10:10:40Z"
  }
}

{
  "field": "message",
  "event": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "message_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "updated_at": "2025-10-31T10:10:40Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "text": "Thanks, got your message!",
    "channel": "whatsapp",
    "received_at": "2025-10-31T10:10:40Z"
  }
}

{
  "field": "message",
  "event": "message.received",
  "timestamp": "2025-10-31T10:10:42Z",
  "payload": {
    "message_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "updated_at": "2025-10-31T10:10:40Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "inbound_number": "+1234567890",
    "outbound_number": "+1987654321",
    "text": "Tapped: View order",
    "channel": "rcs",
    "received_at": "2025-10-31T10:10:40Z"
  }
}

Inbound Message Event Fields (message.received):

Status Definitions:

templates

Triggered when a template moves through review. Each transition fires a separate event with a matching event.

Approval is tracked per channel, and who reviews a template depends on the account:

• With a connected WhatsApp Business Account, Meta reviews it. An APPROVED or PENDING verdict applies to every channel; a rejection from Meta applies to the WhatsApp leg only, and the other legs keep the state they had.
• Without one, Sent's compliance team reviews it and decides each channel individually, usually within minutes rather than days.

Either way the legs can settle at different times, so each decision reports on its own. payload.channel names the leg, and is omitted when a decision applies to the whole template.

{
  "field": "templates",
  "event": "templates.approved",
  "timestamp": "2025-10-31T12:18:14Z",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "whatsapp_template_id": "1234567890123456",
    "status": "APPROVED",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp"
  }
}

Template sub-types

All template events share one payload shape. Only event, payload.status, and payload.reason change between sub-types.

Sent creates three auto-replies for you, answering opt-in, opt-out, and help keywords, and you can add your own for any keyword you choose. All of them are reviewed like any other template, so they raise these events too. payload.auto_reply_action is how you tell them apart from the templates you author: the three report OPT_IN, OPT_OUT, and HELP, and one of yours reports OTHER.

Meta forwards a wider set of lifecycle values than the preceding table covers, and adds to it without notice. A status outside the table arrives on the bare templates parent with no event key and the status reported verbatim in payload.status, so route on field first and treat event as optional.

Template Event Fields:

channel

Triggered when one of your channels moves through provisioning and compliance. Getting a sender live is the longest-running asynchronous process on the platform. A 10DLC registration goes to The Campaign Registry, and a sender ID in some markets pre-registers with the destination's regulator, so these events tell you where a market stands without polling GET /v3/channels.

The subject is always one market, not the account. payload.country names it, and payload.number_type and payload.sender_value say which sender it uses. A market that registers with nobody reports the same way as one that does.

Two fields answer two different questions. event says what happened; payload.status says whether the market can send. They move independently: a resubmission filed against a market whose sender is already live arrives as channel.submitted carrying ACTIVE. Route on event and read status for the current state.

{
  "field": "channel",
  "event": "channel.activated",
  "timestamp": "2025-10-31T14:22:09Z",
  "request_id": "req_7X9zKp2jDw",
  "payload": {
    "channel": "sms",
    "status": "ACTIVE",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "country": "XK",
    "number_type": "ALPHANUMERIC",
    "sender_value": "SENTDM",
    "updated_at": "2025-10-31T14:22:09Z"
  }
}

{
  "field": "channel",
  "event": "channel.activated",
  "timestamp": "2025-10-31T14:22:09Z",
  "request_id": "req_7X9zKp2jDw",
  "payload": {
    "channel": "sms",
    "status": "ACTIVE",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "country": "US",
    "number_type": "TEN_DLC",
    "sender_value": "+12015550101",
    "compliance": {
      "brand": {
        "inherit": false,
        "legal_name": "Tenant 42 Coffee Company LLC",
        "business_name": "Tenant 42 Coffee Co",
        "tax_id": "12-3456789",
        "tax_id_type": "us_ein",
        "ein_issuing_country": "US",
        "entity_type": "PRIVATE_PROFIT",
        "street": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US",
        "website": "https://tenant42.example.com",
        "contact_name": "Jane Doe",
        "contact_email": "jane@tenant42.example.com",
        "contact_phone": "+12125550123"
      },
      "campaign": {
        "inherit": false,
        "description": "Order and delivery updates for coffee subscriptions",
        "message_flow": "Customers opt in at checkout on tenant42.example.com by ticking a box that is unchecked by default. Consent is not a condition of purchase.",
        "use_cases": [
          {
            "use_case": "DELIVERY_NOTIFICATION",
            "sample_messages": ["Tenant 42 Coffee: your order #1234 ships today. Reply STOP to opt out."]
          }
        ],
        "opt_in_message": "Tenant 42 Coffee: you are subscribed to order updates. Reply STOP to opt out, HELP for help.",
        "opt_out_message": "Tenant 42 Coffee: you will receive no further messages.",
        "help_message": "Tenant 42 Coffee: for help, email support@tenant42.example.com. Reply STOP to opt out.",
        "opt_in_keywords": "START,YES",
        "opt_out_keywords": "STOP",
        "help_keywords": "HELP",
        "privacy_policy_link": "https://tenant42.example.com/privacy",
        "terms_and_conditions_link": "https://tenant42.example.com/terms",
        "volume": "1000"
      },
      "documents": []
    },
    "updated_at": "2025-10-31T14:22:09Z"
  }
}

Channel sub-types

Channel statuses

ACTIVE means provisioning and compliance are complete. It does not promise that the next send succeeds: a suspended account and a destination blocked by a routing rule both report ACTIVE.

Channel Event Fields:

Your organization's webhook receives your organization's own channel events. To receive every Sender Profile's at the same endpoint, select channel under sender_profile, which clones the webhook onto each profile, and payload.account_id names the profile whose market moved. See Sender Profile Events.

contact

Triggered when a contact signals a consent change, asks for help, or sends one of your custom auto-reply keywords. These events state the signal outright so you do not have to parse keywords out of message.received. They also cover cases that produce no inbound message at all, such as a network handling an opt-out on your behalf.

Two of the four sub-types change consent; two do not. contact.help and contact.custom_keyword report the contact's existing state without changing it. Read opt_out for the state and the envelope's event for what happened, rather than inferring one from the other.

{
  "field": "contact",
  "event": "contact.opt_out",
  "timestamp": "2026-09-24T14:00:00Z",
  "request_id": "req_9Y0aLq3kEx",
  "payload": {
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "contact_id": "a1b2c3d4-9dad-11d1-80b4-00c04fd430c8",
    "from": "+14155551234",
    "to": "+18005550100",
    "opt_out": true,
    "source": "INBOUND_KEYWORD",
    "channel": "sms",
    "text": "STOP",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c9"
  }
}

Contact sub-types

Contact Event Fields:

message.received still names the same two parties inbound_number and outbound_number rather than from and to. Join a contact event to its inbound message on message_id rather than comparing number fields.

link

Triggered when a tracked link Sent published on your behalf is used, expires, or is revoked. Sent shortens the URLs in your message copy and hosts the media you attach, and serves both from the s.dm domain. payload.link_kind says which one an event is about: url for a destination you supplied, file for media Sent hosts.

This family is opt-in and delivers nothing until you ask for it. Subscribe to link explicitly. A message subscription never inherits link events, and neither does a wildcard.

{
  "field": "link",
  "event": "link.clicked",
  "timestamp": "2025-10-31T15:04:02Z",
  "payload": {
    "customer_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "sender_profile_id": null,
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "record_id": "A78B2BU0",
    "link_kind": "url",
    "channel": "sms",
    "reference_key": "body:0",
    "occurred_at": "2025-10-31T15:04:00Z",
    "request_method": "GET",
    "status_code": 302,
    "traffic_class": "likely_human",
    "access_country": "US",
    "device": "mobile",
    "browser": "chrome"
  }
}

Link sub-types

The first two report a request that was served. The last two report a change to the link itself, so they describe no request and omit every request-shaped field, including request_method, status_code, traffic_class, access_country, device, and browser. channel and reference_key describe the link rather than the request, so a lifecycle event reports them exactly as an access event does. Both kinds of link can expire or be revoked, so read link_kind rather than assuming a lifecycle event is about a URL.

Sent forwards these four and no others. link.created, link.requested, link.tags_changed, and link.purged exist in Sent's own link analytics and are never delivered to a webhook, so do not build a handler that waits for the moment a link is minted.

Traffic classes

Every value is derived from the user agent, which makes this a filter for obvious noise rather than a fact to bill or report on.

Link Event Fields:

Link events carry no request_id.

Grouping and deduplication. One link accumulates many events, and any one of those events can be delivered more than once, so a handler needs two separate keys. payload.record_id identifies the link: group a link's events by it. The X-Webhook-Event-ID header identifies the delivery: deduplicate on it, exactly as on every other family. The payload carries no event identifier of its own.

Two timestamps that genuinely differ. The envelope's timestamp is when Sent emitted the event; payload.occurred_at is when the click, download, or lifecycle change happened. Elsewhere the two sit within the same second. Here they are separated by the time it takes Sent to receive the access, and a replay can widen that to days, so report on occurred_at and use timestamp only to reason about delivery.

The visitor's country is access_country, not country. A channel event's country is a destination market you registered for. This one is a property of a single visitor, and the two names are kept apart so a handler switching on payload shape cannot confuse them.

A Sender Profile's links go to its own webhooks. Your organization's webhook doesn't receive them, as with every family. To track every profile's links at one endpoint, select link under sender_profile, which clones your webhook onto each profile. See Sender Profile Events.

The event can arrive before the message is readable. A messaging provider may fetch a link within milliseconds of the send, and nothing delays the event to wait for the message record. If GET /v3/messages/{id} does not yet know payload.message_id, retry the read rather than treating the id as invalid.