Skip to content
Shortcut: /, ⌘K or Ctrl+K

Events

View as Markdown

Receive Polymorfa events through webhooks, event streams or event history:

  • Webhook endpoints receive each event as a signed HTTP POST. See Webhooks for verifying signatures and retries, and the webhooks quickstart to receive your first event.
  • Event streams deliver a project's events over a server-sent event connection that resumes from a cursor. See Event streams.
  • Event history lists past events and replays a retained event to a webhook. See Event history.

Event records and payloads are kept for a bounded time. Each event record reports payloadAvailability, replayableUntil and metadataExpiresAt. These timestamps are authoritative; do not assume a fixed retention period. A stream cursor is valid for 24 hours.

The Event object

Every native event has the same envelope. Event history and event streams return an event record; with the payload included, its payload holds this object's exact bytes, base64-encoded.

Webhook endpoints with format: "meta" receive Meta's object/entry/changes/value envelope instead, and only for events that have a Meta equivalent. See Delivery formats.

Attributes

  • idstringrequired

    Unique event ID. Use it to deduplicate retries.

  • sessionstringrequired

    The Number that produced the event. Empty for team and project events, such as campaign lifecycle, Customer and voice events.

  • externalIdstring

    Your reference from the QuickLink that created the Number, on Number lifecycle events, when you supplied one.

  • timestampstringrequired

    When the event happened, in ISO 8601.

  • eventstringrequired

    The event type, such as message.received. See Types of events.

  • payloadobjectrequired

    Data specific to the event type. Each type below lists its payload fields.

The Event object
{
  "id": "0190f2a4-6c1e-7b9d-9f3a-2e8c4d5b6a71",
  "session": "739182640518203",
  "timestamp": "2026-10-19T14:03:22.000Z",
  "event": "message.received",
  "payload": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string"
    },
    "conversation": {
      "id": "739182640518203"
    },
    "fromMe": true,
    "timestamp": 0,
    "pushName": "string",
    "isGroup": true,
    "type": "text"
  }
}

The team event record object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • teamIdstring (uuid)required

    Identifier for the team.

  • projectIdstringrequirednullable

    Identifier of the Polymorfa project that owns this resource.

  • typestringrequiredlength1–128

    Type discriminator for this object.

  • sourcestringrequired

    Specifies source for this management team event.

    Allowed valuesruntimeplatformtest
  • environmentstringrequired

    Specifies environment for this management team event.

    Allowed valuesdevelopmentproduction
  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

  • payloadAvailabilitystringrequired

    Specifies payload availability for this management team event.

    Allowed valuesavailablenot_retainedexpiredredactedunavailable
  • payloadobjectrequirednullable

    Structured payload carried by this event or operation.

    Show 3 child fields
  • replayableUntilstring (date-time)requirednullable

    Specifies replayable until for this management team event.

  • metadataExpiresAtstring (date-time)required

    Timestamp for metadata expires at.

The team event record object
{
  "id": "00000000-0000-4000-8000-000000000000",
  "teamId": "00000000-0000-4000-8000-000000000000",
  "projectId": null,
  "type": "string",
  "source": "runtime",
  "environment": "development",
  "createdAt": "2026-09-22T12:00:00Z",
  "payloadAvailability": "available",
  "payload": {
    "encoding": "base64",
    "contentType": "application/json",
    "data": "string"
  },
  "replayableUntil": "2026-09-22T12:00:00Z",
  "metadataExpiresAt": "2026-09-22T12:00:00Z"
}

The project event record object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • teamIdstring (uuid)required

    Identifier for the team.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • typestringrequiredlength1–128

    Type discriminator for this object.

  • sourcestringrequired

    Specifies source for this management project event.

    Allowed valuesruntimeplatformtest
  • environmentstringrequired

    Specifies environment for this management project event.

    Allowed valuesdevelopmentproduction
  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

  • payloadAvailabilitystringrequired

    Specifies payload availability for this management project event.

    Allowed valuesavailablenot_retainedexpiredredactedunavailable
  • payloadobjectrequirednullable

    Structured payload carried by this event or operation.

    Show 3 child fields
  • replayableUntilstring (date-time)requirednullable

    Specifies replayable until for this management project event.

  • metadataExpiresAtstring (date-time)required

    Timestamp for metadata expires at.

The project event record object
{
  "id": "00000000-0000-4000-8000-000000000000",
  "teamId": "00000000-0000-4000-8000-000000000000",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "type": "string",
  "source": "runtime",
  "environment": "development",
  "createdAt": "2026-09-22T12:00:00Z",
  "payloadAvailability": "available",
  "payload": {
    "encoding": "base64",
    "contentType": "application/json",
    "data": "string"
  },
  "replayableUntil": "2026-09-22T12:00:00Z",
  "metadataExpiresAt": "2026-09-22T12:00:00Z"
}

List team events

GET/platform/eventsPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:read

Lists team-owned event metadata. Project-owned events are excluded.

Team keys require events:read. Project tokens are not accepted.

Query parameters

  • typestring

    Type discriminator for this object.

  • sincestring (date-time)

    Specifies since for this query parameter.

  • untilstring (date-time)

    Specifies until for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstring

    Specifies cursor for this query parameter.

  • afterOffsetstringpattern^(0|[1-9][0-9]*)$

    Return events indexed after this retained-stream offset, in ingestion order. Cannot be combined with cursor, since, or until. Pass 0 to obtain page.highWatermark for an initial wait baseline.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 11 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/eventscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": null,
      "type": "string",
      "source": "runtime",
      "environment": "development",
      "createdAt": "2026-09-22T12:00:00Z",
      "payloadAvailability": "available",
      "payload": {
        "encoding": "base64",
        "contentType": "application/json",
        "data": "string"
      },
      "replayableUntil": "2026-09-22T12:00:00Z",
      "metadataExpiresAt": "2026-09-22T12:00:00Z"
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}

List project events

GET/platform/projects/{projectId}/eventsPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:read

Lists event metadata owned by the exact project in the route.

Requires events:read. Project tokens only access resources in their own project.

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Query parameters

  • typestring

    Type discriminator for this object.

  • sincestring (date-time)

    Specifies since for this query parameter.

  • untilstring (date-time)

    Specifies until for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • cursorstring

    Specifies cursor for this query parameter.

  • afterOffsetstringpattern^(0|[1-9][0-9]*)$

    Return events indexed after this retained-stream offset, in ingestion order. Cannot be combined with cursor, since, or until. Pass 0 to obtain page.highWatermark for an initial wait baseline.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 11 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/projects/{projectId}/eventscURL
curl "https://api.polymorfa.com/platform/projects/<projectId>/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "type": "string",
      "source": "runtime",
      "environment": "development",
      "createdAt": "2026-09-22T12:00:00Z",
      "payloadAvailability": "available",
      "payload": {
        "encoding": "base64",
        "contentType": "application/json",
        "data": "string"
      },
      "replayableUntil": "2026-09-22T12:00:00Z",
      "metadataExpiresAt": "2026-09-22T12:00:00Z"
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Get team event

GET/platform/events/{eventId}Platform API
Base URL
https://api.polymorfa.com
Required permission
events:read

Returns one team-owned event and includes exact payload bytes only when requested and available.

Team keys require events:read. Project tokens are not accepted.

Path parameters

  • eventIdstring (uuid)required

    Identifier for the event.

Query parameters

  • includePayloadboolean

    Whether include payload.

    Default false

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/events/{eventId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/events/<eventId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "teamId": "00000000-0000-4000-8000-000000000000",
    "projectId": null,
    "type": "string",
    "source": "runtime",
    "environment": "development",
    "createdAt": "2026-09-22T12:00:00Z",
    "payloadAvailability": "available",
    "payload": {
      "encoding": "base64",
      "contentType": "application/json",
      "data": "string"
    },
    "replayableUntil": "2026-09-22T12:00:00Z",
    "metadataExpiresAt": "2026-09-22T12:00:00Z"
  }
}

Get project event

GET/platform/projects/{projectId}/events/{eventId}Platform API
Base URL
https://api.polymorfa.com
Required permission
events:read

Returns one event owned by the exact project and includes exact payload bytes only when requested and available.

Requires events:read. Project tokens only access resources in their own project.

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • eventIdstring (uuid)required

    Identifier for the event.

Query parameters

  • includePayloadboolean

    Whether include payload.

    Default false

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 11 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/projects/{projectId}/events/{eventId}cURL
curl "https://api.polymorfa.com/platform/projects/<projectId>/events/<eventId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "teamId": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "type": "string",
    "source": "runtime",
    "environment": "development",
    "createdAt": "2026-09-22T12:00:00Z",
    "payloadAvailability": "available",
    "payload": {
      "encoding": "base64",
      "contentType": "application/json",
      "data": "string"
    },
    "replayableUntil": "2026-09-22T12:00:00Z",
    "metadataExpiresAt": "2026-09-22T12:00:00Z"
  }
}

Stream project events

GET/platform/projects/{projectId}/events/streamPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:listen

Opens a server-sent event (SSE) stream of this project's events. Every event frame carries the same event object as the events API and the exact webhook body when it is available.

Send Accept: text/event-stream. Resume after a disconnect by sending the last received cursor as Last-Event-ID or cursor. Cursors are valid for 24 hours and are bound to the team, project and types filter.

With ack=auto (default), each event is released as soon as it is written. With ack=manual, at most maxInFlight events are outstanding until you acknowledge them; unacknowledged events produce a backpressure frame and then a dropped frame.

The stream sends a heartbeat frame every heartbeatIntervalMs. It closes with revoked within one heartbeat after the credential, project or feature access ends, and with expiry at connectionExpiresAt or after idleTimeoutMs without an event. Reconnect from the last cursor after expiry, dropped or a recoverable gap.

Requires events:listen and the Event streams beta. Team keys and project tokens are accepted; client tokens are rejected.

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Query parameters

  • typesstring

    Specifies types for this query parameter.

  • cursorstringmax length4096

    Specifies cursor for this query parameter.

  • ackstring

    Specifies ack for this query parameter.

    Allowed valuesautomanual

Headers

  • Last-Event-IDstringmax length4096

    Identifier for the last event.

Responses

  • 200An SSE stream. The first frame is `ready`. `revoked`, `expiry`, `dropped` and `gap` frames end the connection, except a `gap` with reason `retention_exceeded`, which reports skipped events and the stream continues.

    Content typetext/event-stream

    One of
    • vnumberrequired

      Specifies v for this management platform access event stream ready frame.

      Allowed values1
    • streamIdstring (uuid)required

      Identifier for the stream.

    • sequenceintegerrequiredmin1

      Frame counter for this connection. It restarts at 1 on every connection.

    • sentAtstring (date-time)required

      Timestamp for sent at.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesready
    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • connectionExpiresAtstring (date-time)required

      Timestamp for connection expires at.

    • heartbeatIntervalMsintegerrequired

      Specifies heartbeat interval ms for this management platform access event stream ready frame.

    • maxInFlightintegerrequired

      Specifies max in flight for this management platform access event stream ready frame.

    • ackstringrequired

      Specifies ack for this management platform access event stream ready frame.

      Allowed valuesautomanual
    • typesarray of stringrequired

      Types associated with this management platform access event stream ready frame.

    • idleTimeoutMsintegerrequired

      Specifies idle timeout ms for this management platform access event stream ready frame.

    • resumeobjectrequired

      Structured resume values for this management platform access event stream ready frame.

      Show 4 child fields
    Show 4 headers
  • 400Invalid parameter, or `stream_cursor_invalid` when the cursor belongs to another project or filter.
  • 401Missing or invalid credential.
  • 403`missing_scope`, `permission_denied`, or `feature_unavailable` when Event streams is not enabled for the team.
  • 406The request did not accept `text/event-stream`.
  • 410`stream_cursor_expired`: the cursor is older than 24 hours. Reconnect without a cursor and read missed events from the events API.
  • 429`stream_connection_limit_reached` or `rate_limit_exceeded`. Follow `Retry-After`.
  • 503A required service is unavailable. Retry with backoff.
GET /platform/projects/{projectId}/events/streamcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/events/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response

Content type text/event-stream

No example for this content type

Acknowledge project event stream

POST/platform/projects/{projectId}/events/stream/{streamId}/ackPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:listen

Acknowledges every event up to and including sequence on a stream opened with ack=manual. Acknowledgements are cumulative and idempotent. Use the same credential that opened the stream.

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • streamIdstring (uuid)required

    Identifier for the stream.

Body

  • cursorstringrequiredlength1–4096

    Specifies cursor for this management platform access event stream ack request.

  • sequenceintegerrequiredrange1–9007199254740991

    Specifies sequence for this management platform access event stream ack request.

Responses

  • 200Acknowledged
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400Invalid acknowledgement.
  • 401Missing or invalid credential.
  • 403`missing_scope` or `permission_denied`.
  • 404The stream is not open for this credential and project.
  • 409`state_conflict`: the stream closed or the acknowledgement regressed or is ahead of delivery.
  • 429`rate_limit_exceeded`. Follow `Retry-After`.
  • 503A required service is unavailable. Retry with backoff.
POST /platform/projects/{projectId}/events/stream/{streamId}/ackcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/events/stream/<streamId>/ack" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "cursor": "string",
  "sequence": 1
}'
Response
{
  "data": {
    "streamId": "00000000-0000-4000-8000-000000000000",
    "acknowledgedCursor": "string",
    "sequence": 0,
    "replayed": true
  }
}

Replay team event

POST/platform/events/{eventId}/replaysPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:replay

Creates a new logical delivery for a retained team event.

Team keys require events:replay. Project tokens are not accepted.

Path parameters

  • eventIdstring (uuid)required

    Identifier for the event.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The retained payload is unavailable or no longer replayable.
POST /platform/events/{eventId}/replayscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/events/<eventId>/replays" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "webhookId": "00000000-0000-4000-8000-000000000000"
}'
Response
{
  "data": {
    "operationId": "00000000-0000-4000-8000-000000000000",
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "eventId": "00000000-0000-4000-8000-000000000000",
    "deliveryId": "00000000-0000-4000-8000-000000000000"
  }
}

Replay project event

POST/platform/projects/{projectId}/events/{eventId}/replaysPlatform API
Base URL
https://api.polymorfa.com
Required permission
events:replay

Creates a new logical delivery for a retained event owned by the exact project.

Requires events:replay. Project tokens only access resources in their own project.

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • eventIdstring (uuid)required

    Identifier for the event.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • webhookIdstring (uuid)required

    Identifier for the webhook.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 422The retained payload is unavailable or no longer replayable.
POST /platform/projects/{projectId}/events/{eventId}/replayscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/events/<eventId>/replays" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "webhookId": "00000000-0000-4000-8000-000000000000"
}'
Response
{
  "data": {
    "operationId": "00000000-0000-4000-8000-000000000000",
    "idempotency": {
      "id": "00000000-0000-4000-8000-000000000000",
      "key": "string",
      "replayed": true,
      "createdAt": "2026-09-22T12:00:00Z",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "eventId": "00000000-0000-4000-8000-000000000000",
    "deliveryId": "00000000-0000-4000-8000-000000000000"
  }
}

Types of events

Project webhooks receive events from their Numbers. Team webhooks receive Customer and campaign lifecycle events, plus campaign.recipient_failed. Subscribe with eventTypes and ignore types you do not handle.

Messages

Related resource Messages

Native message events carry a Polymorfa id and the exact provider whatsapp_ids object. Its linked_devices and official_api keys contain observed provider references; unknown keys are omitted. Conversation and sender objects contain id with optional phoneNumber, bsuid, and username. Match receipts using the Polymorfa message ID, scoped to the Number that emitted the event. Do not treat a native event ID, a Polymorfa message ID, and a Meta message ID as the same identifier.

Use each identity's id as its key. Phone numbers and usernames are aliases. See User identities and media previews.

  • message.received

    Incoming message.

    MessagePayload
    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • isGroupbooleanrequired

      Whether the conversation is a group chat.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesShow all 18 values
      textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknown
    • textstring

      Text content carried by this object.

    • captionstring

      Caption shown with the attached media.

    • mimeTypestring

      IANA media type that matches the media payload.

      • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

    • pttboolean

      Whether the audio is presented as a push-to-talk voice message.

    • filenamestring

      Filename presented for the media attachment.

    • latitudenumber

      Latitude in decimal degrees.

    • longitudenumber

      Longitude in decimal degrees.

    • displayNamestring

      Human-readable display name.

    • titlestring

      Human-readable title shown to the recipient or operator.

    • reactionstring

      Reaction applied to the referenced message.

    • reactionTostringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • revokedIdstringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • mediastring

      Reference to the media attached to this message.

    • mediaUrlstring

      URL used to retrieve the attached media.

    • editedboolean

      Whether the event represents an edited message.

    • pollOptionsarray of object

      Options recipients can choose in the poll.

      Show 2 child fields
    • unavailableboolean

      Whether the content is unavailable.

    • unavailableReasonstring

      Reason the content is unavailable.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message payload.

    • stickerPackobject

      Specifies sticker pack for this native message payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    CloudMessagePayload
    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • timestampstringrequired

      Unix timestamp in seconds represented as a decimal string.

    • typestringrequired

      Type discriminator for this object.

    • senderNamestring

      Human-readable sender name for this native cloud message payload.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • interactiveobject

      Structured interactive values for this native cloud message payload.

    • orderobject

      Specifies order for this native cloud message payload.

      Show 3 child fields
    • referralobject

      Meta-supplied Click-to-WhatsApp entry point. Does not establish a conversion or payment.

      Show 4 child fields
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true,
      "timestamp": 0,
      "pushName": "string",
      "isGroup": true,
      "type": "text"
    }
    • referral identifies the message's entry point, not a conversion or payment.
    • order is omitted if any cart item is unreadable. Meta-format delivery uses type: "unsupported" instead. Confirm prices and stock before fulfilment.
    • Match replies on replyChoice.id. Template quick replies without a payload use the button text as their ID.
    • parentMessageId can reference any quoted message. Invalid IDs are omitted; a Linked Devices reply without a valid choice ID has type: "unknown".
  • message.sent

    Outgoing message successfully sent.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • typestringrequired

      Type discriminator for this object.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message sent payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message sent payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message sent payload.

    • stickerPackobject

      Specifies sticker pack for this native message sent payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message sent payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message sent payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message sent payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "type": "string",
      "timestamp": 0
    }
  • message.ack

    Delivery acknowledgement.

    • messagesarray of objectrequired

      Messages associated with this native message ack payload.

      Show 3 child fields
    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromobject

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • senderobject

      Stable identifier for the user who sent the message or event.

      Show 5 child fields
    • typestringrequired

      Ack type: error, delivered, read, played

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pricingobject

      Specifies pricing for this native message ack payload.

      Show 4 child fields
    Example payload
    {
      "messages": [
        {
          "id": "739182640518203",
          "whatsapp_ids": {
            "linked_devices": "string"
          }
        }
      ],
      "conversation": {
        "id": "739182640518203"
      },
      "type": "string",
      "timestamp": 0
    }

    The event identifies its conversation and a messages array of { id, whatsapp_ids } references.

  • message.revoked

    Message revoked.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • isGroupbooleanrequired

      Whether the conversation is a group chat.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesShow all 18 values
      textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknown
    • textstring

      Text content carried by this object.

    • captionstring

      Caption shown with the attached media.

    • mimeTypestring

      IANA media type that matches the media payload.

      • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

    • pttboolean

      Whether the audio is presented as a push-to-talk voice message.

    • filenamestring

      Filename presented for the media attachment.

    • latitudenumber

      Latitude in decimal degrees.

    • longitudenumber

      Longitude in decimal degrees.

    • displayNamestring

      Human-readable display name.

    • titlestring

      Human-readable title shown to the recipient or operator.

    • reactionstring

      Reaction applied to the referenced message.

    • reactionTostringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • revokedIdstringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • mediastring

      Reference to the media attached to this message.

    • mediaUrlstring

      URL used to retrieve the attached media.

    • editedboolean

      Whether the event represents an edited message.

    • pollOptionsarray of object

      Options recipients can choose in the poll.

      Show 2 child fields
    • unavailableboolean

      Whether the content is unavailable.

    • unavailableReasonstring

      Reason the content is unavailable.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message payload.

    • stickerPackobject

      Specifies sticker pack for this native message payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true,
      "timestamp": 0,
      "pushName": "string",
      "isGroup": true,
      "type": "text"
    }
  • message.reaction

    Reaction added or removed.

    MessagePayload
    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • isGroupbooleanrequired

      Whether the conversation is a group chat.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesShow all 18 values
      textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknown
    • textstring

      Text content carried by this object.

    • captionstring

      Caption shown with the attached media.

    • mimeTypestring

      IANA media type that matches the media payload.

      • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

    • pttboolean

      Whether the audio is presented as a push-to-talk voice message.

    • filenamestring

      Filename presented for the media attachment.

    • latitudenumber

      Latitude in decimal degrees.

    • longitudenumber

      Longitude in decimal degrees.

    • displayNamestring

      Human-readable display name.

    • titlestring

      Human-readable title shown to the recipient or operator.

    • reactionstring

      Reaction applied to the referenced message.

    • reactionTostringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • revokedIdstringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • mediastring

      Reference to the media attached to this message.

    • mediaUrlstring

      URL used to retrieve the attached media.

    • editedboolean

      Whether the event represents an edited message.

    • pollOptionsarray of object

      Options recipients can choose in the poll.

      Show 2 child fields
    • unavailableboolean

      Whether the content is unavailable.

    • unavailableReasonstring

      Reason the content is unavailable.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message payload.

    • stickerPackobject

      Specifies sticker pack for this native message payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    CloudMessagePayload
    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • timestampstringrequired

      Unix timestamp in seconds represented as a decimal string.

    • typestringrequired

      Type discriminator for this object.

    • senderNamestring

      Human-readable sender name for this native cloud message payload.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • interactiveobject

      Structured interactive values for this native cloud message payload.

    • orderobject

      Specifies order for this native cloud message payload.

      Show 3 child fields
    • referralobject

      Meta-supplied Click-to-WhatsApp entry point. Does not establish a conversion or payment.

      Show 4 child fields
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true,
      "timestamp": 0,
      "pushName": "string",
      "isGroup": true,
      "type": "text"
    }
  • message.edited

    Message edited.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • isGroupbooleanrequired

      Whether the conversation is a group chat.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesShow all 18 values
      textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknown
    • textstring

      Text content carried by this object.

    • captionstring

      Caption shown with the attached media.

    • mimeTypestring

      IANA media type that matches the media payload.

      • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

    • pttboolean

      Whether the audio is presented as a push-to-talk voice message.

    • filenamestring

      Filename presented for the media attachment.

    • latitudenumber

      Latitude in decimal degrees.

    • longitudenumber

      Longitude in decimal degrees.

    • displayNamestring

      Human-readable display name.

    • titlestring

      Human-readable title shown to the recipient or operator.

    • reactionstring

      Reaction applied to the referenced message.

    • reactionTostringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • revokedIdstringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • mediastring

      Reference to the media attached to this message.

    • mediaUrlstring

      URL used to retrieve the attached media.

    • editedboolean

      Whether the event represents an edited message.

    • pollOptionsarray of object

      Options recipients can choose in the poll.

      Show 2 child fields
    • unavailableboolean

      Whether the content is unavailable.

    • unavailableReasonstring

      Reason the content is unavailable.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message payload.

    • stickerPackobject

      Specifies sticker pack for this native message payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true,
      "timestamp": 0,
      "pushName": "string",
      "isGroup": true,
      "type": "text"
    }
  • message.update

    Generic message update.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • isGroupbooleanrequired

      Whether the conversation is a group chat.

    • typestringrequired

      Type discriminator for this object.

      Allowed valuesShow all 18 values
      textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknown
    • textstring

      Text content carried by this object.

    • captionstring

      Caption shown with the attached media.

    • mimeTypestring

      IANA media type that matches the media payload.

      • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

    • pttboolean

      Whether the audio is presented as a push-to-talk voice message.

    • filenamestring

      Filename presented for the media attachment.

    • latitudenumber

      Latitude in decimal degrees.

    • longitudenumber

      Longitude in decimal degrees.

    • displayNamestring

      Human-readable display name.

    • titlestring

      Human-readable title shown to the recipient or operator.

    • reactionstring

      Reaction applied to the referenced message.

    • reactionTostringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • revokedIdstringpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • nativeFlowResponseobject

      Structured response returned by a native Flow interaction.

      Show 3 child fields
    • replyChoiceobject

      Present when the contact selects a reply button or list row.

      Show 2 child fields
    • parentMessageIdstringlength1–128

      WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.

    • mediastring

      Reference to the media attached to this message.

    • mediaUrlstring

      URL used to retrieve the attached media.

    • editedboolean

      Whether the event represents an edited message.

    • pollOptionsarray of object

      Options recipients can choose in the poll.

      Show 2 child fields
    • unavailableboolean

      Whether the content is unavailable.

    • unavailableReasonstring

      Reason the content is unavailable.

    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • originstring

      Specifies origin for this native message payload.

      Allowed valuesavatarai
    • emojisarray of string

      Emojis associated with this native message payload.

    • accessibilityLabelstring

      Specifies accessibility label for this native message payload.

    • stickerPackobject

      Specifies sticker pack for this native message payload.

      Show 6 child fields
    • widthintegergreater than0

      Image, video or sticker width in pixels, as declared by the sender.

    • heightintegergreater than0

      Image, video or sticker height in pixels, as declared by the sender.

    • secondsintegergreater than0

      Audio or video duration in seconds.

    • waveformarray of numbermax items64item range0–1

      Voice-note waveform: up to 64 samples from 0 to 1.

    • pageCountintegergreater than0

      Document page count, as declared by the sender.

    • thumbnailobject

      Specifies thumbnail for this native message payload.

      Show 4 child fields
    • linkPreviewobject

      Specifies link preview for this native message payload.

      Show 5 child fields
    • associationobject

      Specifies association for this native message payload.

      Show 2 child fields
    • qualitystring

      hd on the HD half of a pair; standard on a standard message that announced an HD half.

      Allowed valuesstandardhd
    Example payload
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true,
      "timestamp": 0,
      "pushName": "string",
      "isGroup": true,
      "type": "text"
    }

    A sent or received message changed, such as its status or content.

  • message.delete

    Message deleted from another device.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • senderobjectrequired

      Stable identifier for the user who sent the message or event.

      Show 5 child fields
    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • fromMebooleanrequired

      Whether the connected account originated the message.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "sender": {
        "id": "739182640518203"
      },
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "fromMe": true
    }
  • message.vote

    Poll vote cast.

    • pollMessageIdstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 6 child fields
    • voterobjectrequired

      Specifies voter for this native poll vote payload.

      Show 5 child fields
    • selectedHashesarray of stringrequired

      Selected hashes associated with this native poll vote payload.

    • timestampnumberrequired

      Unix timestamp in seconds associated with this event.

    Example payload
    {
      "pollMessageId": "739182640518203",
      "conversation": {
        "id": "739182640518203"
      },
      "voter": {
        "id": "739182640518203"
      },
      "selectedHashes": [
        "string"
      ],
      "timestamp": 0
    }
  • message.echo

    Message sent from the WhatsApp Business app.

    • sourcestringrequired

      Specifies source for this native message echo payload.

      Allowed valueswhatsapp_business_app
    • valueobjectrequired

      Value assigned to this field.

    Example payload
    {
      "source": "whatsapp_business_app",
      "value": {}
    }
  • sticker.update

    Sticker favorites, recents and phone reupload results.

    • kindstringrequired

      Kind discriminator for this object.

      Allowed valuesfavoriterecentrecent_removedreupload
    • fileSha256stringpattern^[A-Za-z0-9+/]{43}=$

      Specifies file sha256 for this native sticker update.

    • timestampintegerrequiredmin0

      Unix timestamp in milliseconds.

    • favoriteboolean

      Whether favorite.

    • lastStickerSentTsintegermin0

      Last sticker use as a Unix timestamp in milliseconds.

    • fromFullSyncboolean

      Whether from full sync.

    • requestIdstringmax length256

      Identifier used to correlate this request across systems.

    • statusstringmax length64

      Current status of this resource or operation.

    • mediastringmax length16384

      Reference to the media attached to this message.

    • descriptorobject

      Specifies descriptor for this native sticker update.

      • When mimeType is image/webp:

      • When mimeType is application/was, When stickerType is lottie: requires stickerType

      Show 9 child fields
    • stickerTypestring

      Category assigned to sticker.

      Allowed valuesstaticanimatedlottie
    • emojisarray of stringmax items10item max length128

      Emojis associated with this native sticker update.

    • accessibilityLabelstringmax length1024

      Specifies accessibility label for this native sticker update.

    Example payload
    {
      "kind": "favorite",
      "timestamp": 0
    }

    This candidate event requires API version 2026-11-10; it is unavailable in staging and production. Account sticker state changed. Preserve lastStickerSentTs in milliseconds. Receiving another person's sticker does not add it to your recent stickers. A reupload request receipt does not update media. Wait for a matching successful result and preserve unknown or failed results without inventing a media reference. See Stickers and sticker packs.

  • message.failed

    Outbound send failed, including a send refused by safety.

    • toobjectrequired

      Specifies to for this native message failed payload.

      Show 5 child fields
    • typestringrequired

      Type of the attempted message (text, image, ...)

    • errorstringrequired

      Sanitized failure class

      Allowed valuesinvalid_recipientsession_not_connectedack_timeoutsend_failedblocked_by_safety
    • codestring

      Stable machine-readable code from the API error envelope, present for classified safety refusals and an unknown send outcome

    • retryAfterintegergreater than0

      Whole seconds to wait before retrying a paced send, exhausted allowance, or temporary allowance-accounting pause

    • timestampintegerrequiredmin0

      Unix timestamp in seconds when the failure occurred

    Example payload
    {
      "to": {
        "id": "739182640518203"
      },
      "type": "text",
      "error": "send_failed",
      "timestamp": 1757161200
    }

    The send failed, was refused before transport, or has an outcome that Polymorfa cannot safely repeat. Its error field is a sanitized class:

    errorMeaning
    invalid_recipientThe recipient could not be addressed.
    session_not_connectedThe Number was not connected.
    ack_timeoutWhatsApp did not acknowledge the send in time.
    send_failedThe send failed, or its outcome cannot safely be repeated. Check code when present.
    blocked_by_safetyPolymorfa refused the send before it left the platform.

    For a classified refusal or unknown outcome, the payload carries code with the stable error code the synchronous request would have received:

    codeMeaning
    bansafe_suspendedThe Number is suspended.
    bansafe_team_suspendedEvery Number in the team is suspended.
    bansafe_cold_blockedA first message to someone who never wrote to this Number is paused outside Campaigns.
    bansafe_throttledThe Number is paced while it recovers.
    bansafe_daily_allowance_reachedThe Number reached its warm-up allowance for the day. It resumes at the next reset.
    bansafe_accounting_unavailablePolymorfa could not durably authorize an allowance slot, so the message was not passed to WhatsApp. Retry after retryAfter seconds.
    bansafe_send_outcome_unknownAnother attempt already reserved this logical send. Do not retry it automatically; reconcile its delivery state first.

    retryAfter is present on a paced send, an exhausted daily allowance, and a temporary allowance-accounting pause. It is absent on bansafe_send_outcome_unknown.

    This event tells a caller using Prefer: respond-async, which receives 202 immediately, why a message never went out. See Errors.

Numbers

Related resource Numbers

  • session.status

    Session status change.

    status
    • statusstringrequired

      Session status: CONNECTING, CONNECTED, DISCONNECTED

    • statusReasonstring

      Reason for the status: SCAN_QR, AUTO_RECONNECT, FAILED, MANUAL_STOP, QR_TIMEOUT, LOGGED_OUT, TEMPORARY_BAN, STREAM_ERROR

    • banCodeintegermin0

      WhatsApp temporary-ban code (present only when statusReason is TEMPORARY_BAN).

    • banReasonstring

      Human-readable label for the ban code (present only when statusReason is TEMPORARY_BAN).

    • banExpiresAtintegerformatint64

      Unix timestamp in seconds when the temporary ban lifts, when WhatsApp provides a duration.

    • detailstring

      Extra context for FAILED and STREAM_ERROR statuses (for example the connect-failure reason).

    CloudAccountStatusPayload
    • sourcestringrequired

      Always meta: a WhatsApp Business Account notification, not a connection-state change

      Allowed valuesmeta
    • kindstringrequired

      WhatsApp notification field that produced the event

      Allowed valuesaccount_alertsaccount_updatephone_number_name_update
    • wabaIdstring

      WhatsApp Business Account id the notification belongs to

    • valueobjectrequired

      The notification's value object exactly as WhatsApp sent it; its fields vary by notification

    Example payload
    {
      "status": "DISCONNECTED"
    }

    With statusReason: "TEMPORARY_BAN" the payload also carries banCode, banReason, and banExpiresAt. banExpiresAt is a Unix timestamp in seconds and is present only when WhatsApp gives a duration. detail carries extra context for FAILED and STREAM_ERROR.

    WhatsApp Business Account notifications (account_alerts and account_update) arrive as session.status with source: "meta", kind, wabaId, and value, the notification's value object exactly as WhatsApp sent it. A display-name review notification uses the same event with kind: "phone_number_name_update". Its value includes display_phone_number, decision, requested_verified_name, and, when Meta provides it, rejection_reason. It reaches only the matching Number under the account. These events carry no status field, so check source before reading status. A format: "meta" webhook receives each notification on its original field. It does not receive connection-state session.status events.

  • session.connected

    Session connected to WhatsApp.

    • phoneNumberstringrequired

      Phone number in international format.

    • idstring

      Polymorfa ID of the connected account.

    • pushNamestringrequired

      WhatsApp display name reported by the sender's client.

    • phonePlatformstringrequired

      Where the account's primary WhatsApp client runs.

      android
      WhatsApp or WhatsApp Business on an Android phone.
      ios
      WhatsApp or WhatsApp Business on an iPhone.
      meta_cloud
      Meta hosts the number through Cloud API.
      unknown
      The phone has not reported a recognized platform.
    • accountTypestringrequired

      How the account uses WhatsApp.

      whatsapp_app
      WhatsApp app, connected as a linked device.
      business_app
      WhatsApp Business app, connected as a linked device.
      meta_cloud
      Meta Cloud API.
      meta_coexistence
      Meta Cloud API, with the WhatsApp Business app still active on the phone.
    • businessNamestring

      Business name shown to the customer.

    Example payload
    {
      "phoneNumber": "string",
      "pushName": "string",
      "phonePlatform": "android",
      "accountType": "whatsapp_app"
    }
  • session.logged_out

    Session logged out.

    • reasonstringrequired

      Why the session was logged out: banned when WhatsApp banned the account, device_removed when the linked device was removed from the phone or from another device, unknown otherwise (including a locked account).

      Allowed valuesbanneddevice_removedunknown
    • codeintegerrequired

      WhatsApp's logout code: 401 (removed), 403 (locked) or 406 (banned); 0 when WhatsApp gave none.

    Example payload
    {
      "reason": "device_removed",
      "code": 401
    }

    reason says why the Number was logged out:

    reasonMeaning
    bannedWhatsApp banned the account (code 406)
    device_removedThe linked device was removed from the phone or from another device (code 401)
    unknownAny other logout, including a locked account (code 403)

    code is WhatsApp's own logout code, or 0 when it gave none. Reconnect a device_removed number by pairing it again; a banned number needs a new number.

    Code 403 arrives as unknown because WhatsApp uses it both when it locks an account and when the phone's own account moves. Polymorfa treats it as a ban for safety: it stops sending from the Number and records the outcome in Safety. Check the Number in WhatsApp on the phone; pair it again if the account is intact.

  • session.phone_offline

    Primary phone has been offline for an extended period.

    • daysSinceLastSeennumberrequired

      Whole days since the phone was last seen online.

    • daysRemainingnumberrequired

      Days remaining before WhatsApp disconnects the session (clamped to 0). WhatsApp typically severs the companion link after ~14 days of phone inactivity.

    • lastSeenstringrequired

      ISO 8601 timestamp of the last time the phone was seen online.

    • actionstringrequired

      Human-readable action string to surface to the end user (e.g. ask them to open WhatsApp on their phone).

    Example payload
    {
      "daysSinceLastSeen": 11,
      "daysRemaining": 3,
      "lastSeen": "2026-04-05T14:30:00Z",
      "action": "Open WhatsApp on your phone to keep the session alive"
    }

    WhatsApp signs the device out on day 14 without its phone. Each webhook chooses the first day it receives this warning. See Phone offline warnings.

  • session.capabilities_updated

    The number’s WhatsApp capabilities changed.

    • sessionstringrequiredmax length256

      Identifier of the connected Polymorfa session.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • statusstringrequired

      Current status of this resource or operation.

      Allowed valuessyncedunknown
    • syncedAtstringrequirednullableformatdate-time

      Timestamp for synced at.

    • checkedAtstringrequirednullableformatdate-time

      Timestamp for checked at.

    • accountTypestringrequirednullable

      Category assigned to account.

      Allowed valuesbusinesspersonal
    • capabilitiesarray of objectrequiredmax items100

      Capabilities associated with this native session capabilities updated payload.

      Show 5 child fields
    • changedKeysarray of stringrequiredmax items100item max length128

      Changed keys associated with this native session capabilities updated payload.

    Example payload
    {
      "session": "string",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "status": "synced",
      "syncedAt": "2026-09-22T12:00:00Z",
      "checkedAt": "2026-09-22T12:00:00Z",
      "accountType": "business",
      "capabilities": [
        {
          "key": "string",
          "kind": "feature",
          "unit": "seconds",
          "value": true,
          "source": "server"
        }
      ],
      "changedKeys": [
        "string"
      ]
    }

    This event is not offered. Enrollment in the number-capabilities beta does not enable it. changedKeys lists capabilities whose value or source changed; account-type or status transitions also produce an event. Routine checks produce no event. The payload contains no raw configuration or experiment identifiers. Group capability changes are excluded.

    Eligibility is checked before publication and delivery. Queued events wait when access is unavailable and expire after seven days. Deduplicate retries by event ID. A Meta-format endpoint has no mapping for this event; use native format.

  • session.restriction_updated

    A WhatsApp restriction on the number started, changed or ended.

    • typestringrequired

      The restriction. reachout_timelock: the number can only message or call people it has already chatted with.

      Allowed valuesreachout_timelock
    • activebooleanrequired

      True while the restriction applies.

    • enforcementTypestringrequirednullable

      WhatsApp's category for the restriction; null when inactive or not reported.

    • expiresAtstringrequirednullable

      When the restriction ends (ISO 8601); null when inactive or WhatsApp gave no end.

    • observedAtstringrequired

      When the state was observed (ISO 8601).

    Example payload
    {
      "type": "reachout_timelock",
      "active": true,
      "enforcementType": "DEFAULT",
      "expiresAt": "2026-09-20T08:00:00Z",
      "observedAt": "2026-09-19T08:00:00Z"
    }

    Today the event carries one type: reachout_timelock, WhatsApp's temporary limit on starting conversations and calls with people the Number has not chatted with.

    FieldMeaning
    typereachout_timelock
    activetrue while the restriction applies, false when it ends
    enforcementTypeWhatsApp's category for the restriction, such as DEFAULT; null when inactive or not reported
    expiresAtWhen the restriction ends (ISO 8601); null when inactive or WhatsApp gave no end
    observedAtWhen Polymorfa observed the state (ISO 8601)

    While the restriction is active, messages and calls to people the Number has already chatted with continue. A call to anyone else is refused with number_restricted; see Calls.

Chats

Related resource Chats

  • chat.archive

    Chat archived or pinned.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • archiveboolean

      Whether archive.

    • pinnedboolean

      Whether pinned.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      }
    }
  • chat.mute

    Chat muted or unmuted.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • mutedbooleanrequired

      Whether notifications are muted.

    • muteEndTimestampnumber

      Unix timestamp in seconds when the chat mute expires.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "muted": true
    }
  • chat.read

    Chat marked read or unread.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • readbooleanrequired

      Whether read.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "read": true
    }
  • chat.clear

    Chat cleared.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    Example payload
    {
      "from": {
        "id": "739182640518203"
      }
    }
  • chat.delete

    Chat deleted.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    Example payload
    {
      "from": {
        "id": "739182640518203"
      }
    }

Contacts, groups and labels

Related resource Contacts

  • group.update

    Group metadata changed.

    • idstringrequired

      Identifier for this resource.

    • newSubjectstring

      Specifies new subject for this native group update payload.

    • newDescriptionstring

      Specifies new description for this native group update payload.

    • actionstring

      What changed, for example joined when the Number joins a group with an invite link.

    Example payload
    {
      "id": "string"
    }
  • group.participant

    Group participants added/removed/promoted/demoted.

    • idstringrequired

      Identifier for this resource.

    • joinedarray of object

      Joined associated with this native group participant payload.

      Show 5 child fields
    • leftarray of object

      Left associated with this native group participant payload.

      Show 5 child fields
    • promotedarray of object

      Promoted associated with this native group participant payload.

      Show 5 child fields
    • demotedarray of object

      Demoted associated with this native group participant payload.

      Show 5 child fields
    Example payload
    {
      "id": "string"
    }
  • presence.update

    User or chat presence change.

    • observedAtintegerrequired

      Unix timestamp in seconds when Polymorfa observed this state.

    • fromobject

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • senderobject

      Stable identifier for the user who sent the message or event.

      Show 5 child fields
    • statestring

      Composing activity observed for the contact, such as composing or paused.

    • mediastring

      Chat presence media category reported while composing or recording, such as audio.

    • unavailableboolean

      Whether the observed contact is unavailable according to this presence update.

    • lastSeennumber

      Unix timestamp in seconds when the user was last seen.

    Example payload
    {
      "observedAt": 0
    }

    Emitted only when the session's effective presence or typing observation mode is events or cache. Its observedAt field is the Unix timestamp when the runner accepted the WhatsApp wire event. The event is not durable presence storage, and the optional lookup cache is bounded and in-memory. See Linked-device controls for modes, subscription limits, and read semantics.

  • contact.update

    Contact info changed.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Opaque Polymorfa resource ID. Keep this value as a string.

    • bsuidstring

      Business-scoped user identifier (BSUID), scoped to the owning business portfolio.

    • phoneNumberstring

      Phone number in international format.

    • usernamestring

      WhatsApp username when one is available.

    • parentBsuidstring

      Parent business-scoped user ID (CC.ENT.…), present only when WhatsApp reports one for this person. It identifies the person across the business portfolios enrolled in one parent account. It cannot be used to send messages or block people; use id or bsuid.

    • identityChangeobject

      Specifies identity change for this native contact update payload.

      Show 3 child fields
    • fullNamestring

      Human-readable full name for this native contact update payload.

    • firstNamestring

      Human-readable first name for this native contact update payload.

    • pushNamestring

      WhatsApp display name reported by the sender's client.

    • oldPushNamestring

      Human-readable old push name for this native contact update payload.

    • businessNamestring

      Business name shown to the customer.

    • oldBusinessNamestring

      Human-readable old business name for this native contact update payload.

    • pictureIdstring

      Identifier for the picture.

    • pictureRemovedboolean

      Whether picture removed.

    Example payload
    {
      "id": "739182640518203"
    }

    Identity-change notifications become native contact.update events with identityChange, or Meta-format messages with type: "system" and system.type: "user_changed_number" or "user_changed_user_id". Subscribe to messages at Meta; user_id_update is not a subscribable webhook field. See User identities.

  • contact.opted_out

    A contact opted out of campaigns by replying with an opt-out keyword.

    • phonestringrequired

      Contact phone number in E.164 format

    • sourcestringrequired

      How the suppression list changed. Keyword replies always report stop-keyword.

      Allowed valuesstop-keyword
    • keywordstringrequired

      The configured keyword the reply matched, in upper case. The message itself is never included.

    • sessionstringrequired

      Session name of the number that received the reply

    • projectIdstring

      Project that owns the receiving number, when known

    Example payload
    {
      "phone": "+14155550123",
      "source": "stop-keyword",
      "keyword": "STOP",
      "session": "sales-1"
    }

    The contact changed your team's opt-out list by replying to a campaign message with a configured keyword. contact.opted_in reports the reverse.

    FieldMeaning
    phoneThe contact's number in E.164 format
    sourceAlways stop-keyword; these events report keyword replies only
    keywordThe configured keyword the reply matched, in upper case
    sessionThe Number that received the reply
    projectIdThe project that owns that Number, when it is known

    The reply body is matched in memory and never stored, so neither event carries the message. Changes you make through the opt-out API or the Console do not produce these events. See Opt-outs and STOP replies.

  • contact.opted_in

    A contact reversed a keyword opt-out by replying with an opt-in keyword.

    • phonestringrequired

      Contact phone number in E.164 format

    • sourcestringrequired

      How the suppression list changed. Keyword replies always report stop-keyword.

      Allowed valuesstop-keyword
    • keywordstringrequired

      The configured keyword the reply matched, in upper case. The message itself is never included.

    • sessionstringrequired

      Session name of the number that received the reply

    • projectIdstring

      Project that owns the receiving number, when known

    Example payload
    {
      "phone": "+14155550123",
      "source": "stop-keyword",
      "keyword": "STOP",
      "session": "sales-1"
    }
  • newsletter.update

    Newsletter subscription change.

    • idstringrequiredpattern^[1-9][0-9]{0,18}$

      Stable channel ID.

    • actionstringrequired

      Action, including join, leave, mute, unmute, live_update or milestone.

    • mutedboolean

      Whether notifications are muted.

    • sourceTimestampstring (date-time)

      Source notification time, when reported. The event envelope timestamp remains the publication time.

    • messagesarray of objectmax items300

      Messages associated with this native newsletter update payload.

      Show 6 child fields
    • milestoneobject

      Specifies milestone for this native newsletter update payload.

      Show 4 child fields
    Example payload
    {
      "id": "739182640518203",
      "action": "string"
    }
  • blocklist.update

    Blocklist changed.

    • actionstringrequired

      Action represented by this native blocklist update payload.

    • changesarray of objectrequired

      Changes associated with this native blocklist update payload.

      Show 5 child fields
    Example payload
    {
      "action": "string",
      "changes": [
        {
          "id": "739182640518203",
          "action": "string"
        }
      ]
    }
  • labels.update

    Label edited / associated / star toggled.

    • actionstringrequired

      Action: label_edit, label_association_chat, label_association_message, star

    • labelIdstring

      Label ID affected by the action

    • fromobject

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • labelstring

      Legacy field: the label's display name for label_edit, and the label ID for association actions. Prefer labelId and name.

    • namestring

      Label display name (present for label_edit)

    • colorintegerformatint32

      Label color index (present for label_edit)

    • orderIndexintegerformatint32

      Label ordering index when supplied by app state

    • deletedboolean

      Whether the label definition was deleted

    • labeledboolean

      Whether the chat or message association is active

    • observedAtintegerformatint64

      Unix timestamp in seconds when the app-state mutation was observed

    • messageIdstringpattern^[1-9][0-9]{0,18}$

      Polymorfa message ID (present for star and message-association actions)

    • starredboolean

      Whether the message is starred (present for star actions)

    Example payload
    {
      "action": "label_edit"
    }

    action identifies the change. A label_edit payload includes labelId, observedAt, and the observed definition fields name, color, orderIndex, and deleted. Chat-association changes include from, labelId, labeled, and observedAt. Star changes include from, messageId, and starred. These action-specific fields are optional because one event never represents every action at once.

  • business.quick_reply.update

    WhatsApp Business App quick reply changed.

    • idstringrequired

      Identifier for this resource.

    • shortcutstringrequired

      Specifies shortcut for this native business quick reply update payload.

    • messagestringrequired

      Message content carried by the updated business quick reply.

    • keywordsarray of stringrequired

      Keywords associated with this native business quick reply update payload.

    • countintegerrequiredmin0

      Usage count recorded for this business quick reply.

    • deletedbooleanrequired

      Whether deleted.

    • associatedLabelIdsarray of stringrequired

      Associated label ids associated with this native business quick reply update payload.

    • observedAtintegerrequired

      Unix timestamp in seconds when Polymorfa observed this state.

    • fromFullSyncbooleanrequired

      Whether from full sync.

    Example payload
    {
      "id": "string",
      "shortcut": "string",
      "message": "string",
      "keywords": [
        "string"
      ],
      "count": 0,
      "deleted": true,
      "associatedLabelIds": [
        "string"
      ],
      "observedAt": 0,
      "fromFullSync": true
    }

    A best-effort app-state event for a created, replaced, or deleted WhatsApp Business App quick reply. It contains the quick reply ID, shortcut, message, keywords, count, associated label IDs, observation timestamp, and deletion flag. The default events mode retains no content. Projects that select cache can read a bounded in-memory projection; off suppresses the webhook and clears that projection. See Quick-reply observation.

  • contact.sync

    WhatsApp Business app contact synchronization.

    • kindstringrequired

      Kind discriminator for this object.

      Allowed valuescontacts
    • valueobjectrequired

      Value assigned to this field.

    Example payload
    {
      "kind": "contacts",
      "value": {}
    }

Calls

Related resource Calls

The three call.participant_* events report live group-call roster changes. audioMuted and video remain false because WhatsApp does not expose those states per participant. The browser lifecycle socket uses an ephemeral feed: after a disconnect it resumes with new events and does not replay changes it missed while offline.

  • call.received

    Incoming call.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • callIdstringrequired

      Identifier of the WhatsApp call.

    • hasVideobooleanrequired

      Whether the offered call advertised video.

    • sessionConnectionstring

      Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.

      Allowed valueslinked_devicecloud_api
    • capabilitiesobject

      What the call supports.

      Show 2 child fields
    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "callId": "string",
      "hasVideo": false
    }
  • call.missed

    Call missed.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • callIdstringrequired

      Identifier of the WhatsApp call.

    • reasonstringrequired

      Reason for the reported state or outcome.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "callId": "string",
      "reason": "string"
    }
  • call.accepted

    Call accepted.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • callIdstringrequired

      Identifier of the WhatsApp call.

    • answeredBystring

      Participant reference that answered or placed the call: client:<id> or server:<id>.

    • exclusiveboolean

      Present and true when the answering participant claimed the call.

    • sessionConnectionstring

      Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.

      Allowed valueslinked_devicecloud_api
    • capabilitiesobject

      What the call supports.

      Show 2 child fields
    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "callId": "string"
    }
  • call.rejected

    Call rejected.

    • fromobjectrequired

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • callIdstringrequired

      Identifier of the WhatsApp call.

    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "callId": "string"
    }
  • call.ended

    Call ended.

    • fromobjectrequirednullable

      Stable identifier for the conversation or account that originated the event.

      Show 5 child fields
    • callIdstringrequired

      Identifier of the WhatsApp call.

    • durationSecondsintegerrequired

      Total connected duration in seconds (0 if never answered).

    • reasonstringrequired

      Termination reason: user_hangup | timeout | lost_connection | rejected | capacity | pod_lost | connection_failed | upstream_failed | call_restricted (WhatsApp refused the call because the number is restricted to calling people it has already chatted with).

    • directionstringrequired

      Call direction.

      Allowed valuesinboundoutbound
    • hadVideobooleanrequired

      Whether the call carried video.

    • sessionConnectionstring

      Connection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.

      Allowed valueslinked_devicecloud_api
    Example payload
    {
      "from": {
        "id": "739182640518203"
      },
      "callId": "string",
      "durationSeconds": 42,
      "reason": "user_hangup",
      "direction": "inbound",
      "hadVideo": false
    }
  • call.telemetry

    Call telemetry.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • setupMsintegerrequired

      Time from offer to media_ready, in milliseconds.

    • ringMsintegerrequired

      Time spent ringing before accept, in milliseconds.

    • durationSecondsintegerrequired

      Total connected duration in seconds.

    • terminateReasonstringrequired

      Termination reason: user_hangup | timeout | lost_connection | rejected | capacity.

    • codecstringrequired

      Negotiated audio codec's bare subtype; empty when the audio stream does not identify its codec.

    • jitterMsnumberrequired

      Inbound RTP jitter for the audio stream, in milliseconds.

    • packetsLostintegerrequired

      Cumulative inbound RTP packets lost for the audio stream.

    • rttMsnumberrequired

      Estimated round-trip time from the remote-inbound report, in milliseconds.

    • recvKbpsnumberrequired

      Total inbound volume across all RTP streams, in kilobits (cumulative).

    • sendKbpsnumberrequired

      Total outbound volume across all RTP streams, in kilobits (cumulative).

    Example payload
    {
      "callId": "string",
      "setupMs": 850,
      "ringMs": 3200,
      "durationSeconds": 42,
      "terminateReason": "user_hangup",
      "codec": "opus",
      "jitterMs": 12.5,
      "packetsLost": 3,
      "rttMs": 48.2,
      "recvKbps": 2048,
      "sendKbps": 2011
    }
  • call.participant_joined

    Participant joined a call.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • participantobjectrequired

      Specifies participant for this native call participant payload.

      Show 10 child fields
    Example payload
    {
      "callId": "string",
      "participant": {
        "id": "739182640518203",
        "audioMuted": false,
        "video": false,
        "state": "invited"
      }
    }
  • call.participant_state

    Participant call state changed.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • participantobjectrequired

      Specifies participant for this native call participant payload.

      Show 10 child fields
    Example payload
    {
      "callId": "string",
      "participant": {
        "id": "739182640518203",
        "audioMuted": false,
        "video": false,
        "state": "invited"
      }
    }
  • call.participant_left

    Participant left a call.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • participantIdstringrequired

      Identifier for the participant.

    • reasonstring

      Reason for the reported state or outcome.

    Example payload
    {
      "callId": "string",
      "participantId": "string"
    }
  • call.connection_joined

    Connection joined a call.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • connectionobjectrequired

      Specifies connection for this native call connection joined payload.

      Show 3 child fields
    Example payload
    {
      "callId": "string",
      "connection": {
        "id": "conn_0123456789",
        "participant": "client:agent-7",
        "transport": "webrtc"
      }
    }
  • call.permission_changed

    Call permission changed.

    • conversationobjectrequired

      Public conversation identifier or E.164 phone number.

      Show 4 child fields
    • statusstringrequired

      temporary: granted until expiresAt. permanent: granted without expiry. revoked: declined or withdrawn. none: no permission.

      Allowed valuesnonetemporarypermanentrevoked
    • previousStatusstringrequired

      Specifies previous status for this native call permission changed payload.

      Allowed valuesnonetemporarypermanentrevoked
    • expiresAtstringrequirednullableformatdate-time

      When a temporary permission ends; null otherwise. No event is sent when it ends.

    • sourcestringrequired

      user_action: the person answered a call permission request or changed it in WhatsApp. automatic: WhatsApp granted it when the person called you, or withdrew it after unanswered calls. sync: a permission read found a different state. call_refused: WhatsApp refused a call for lack of permission.

      Allowed valuesuser_actionautomaticsynccall_refused
    • changedAtstring (date-time)required

      Timestamp for changed at.

    Example payload
    {
      "conversation": {
        "id": "739182640518203"
      },
      "status": "none",
      "previousStatus": "none",
      "expiresAt": "2026-09-22T12:00:00Z",
      "source": "user_action",
      "changedAt": "2026-09-22T12:00:00Z"
    }
  • call.connection_left

    Connection left a call.

    • callIdstringrequired

      Identifier of the WhatsApp call.

    • connectionIdstringrequiredpattern^[A-Za-z0-9_-]{8,64}$

      Client-chosen connection identifier.

    • participantstringrequiredpattern^(?:client|server):[A-Za-z0-9._:@-]{1,128}$

      Participant reference: client:<id> for a client token or server:<id> for a server credential.

    • reasonstringrequired

      left: the connection left. replaced: a reconnect reused the connection id. claimed: another participant claimed the call. sip_busy, sip_declined, sip_no_answer, sip_unavailable and sip_auth_failed: a SIP trunk did not join the call. call_ended: the call ended while a SIP trunk was still ringing. A SIP trunk that never joined the call (one of the sip_* reasons, or call_ended while it was still ringing) reports only call.connection_left, with no call.connection_joined before it. Connections still open when the call ends are closed by call.ended without a separate event.

      Allowed valuesleftreplacedclaimedcall_endedsip_busysip_declinedsip_no_answersip_unavailablesip_auth_failed
    Example payload
    {
      "callId": "string",
      "connectionId": "conn_0123456789",
      "participant": "client:agent-7",
      "reason": "left"
    }

Campaigns

Related resource Campaigns

Campaign lifecycle events and campaign.recipient_failed go to team webhooks. The other campaign events go to the sending Number's project webhooks. The launch, reschedule, pause, resume, stop, completion, and failure events are campaign-scoped and arrive with an empty session. Recipient and pacing events reported by a send carry the sending Number in session.

  • campaign.recipient_delivered, campaign.recipient_read and campaign.recipient_replied require team enrollment in the recipient engagement events beta and an enabled rollout. Campaign counters continue to update when the event release is unavailable. Events from before enrollment are not sent later.
  • Delivery, read, or reply transitions for sends made before this event release are not emitted; campaign counters still update.
  • While a team is enrolled but the rollout is paused, events wait and are sent once it resumes. An event still unsent after seven days is dropped. Withdrawing from the beta drops unsent events.
  • campaign.recipient_link_opened requires team enrollment in the campaign link tracking beta and an enabled rollout, and follows the same waiting and dropping rules.
  • Events for one recipient are not guaranteed to arrive in order. Use each payload's timestamp.

campaign.throttled and campaign.cap_reached are pacing signals, not failures. Both are rate-limited: campaign.throttled at most once per campaign per cooldown window, and campaign.cap_reached once per number per cap window.

  • campaign.paused

    Campaign paused.

    • campaignIdstringrequired

      Campaign id

    • sentCountintegerrequiredmin0

      Recipients sent so far

    • remainingCountintegerrequiredmin0

      Recipients still queued

    • pausedAtintegerrequiredmin0

      Unix timestamp in seconds when the campaign paused

    • reasonstring

      Why Polymorfa paused the campaign. Present only on an automatic pause.

    • codestring

      Stable code for an automatic pause: campaigns_not_entitled, bansafe_team_suspended, bansafe_suspended, campaign_throughput_capped, invalid_parameter, hybrid_campaign_unsupported, blocked_by_safety, number_quality_dropped, or messaging_limit_dropped. Present only on an automatic pause.

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sentCount": 0,
      "remainingCount": 0,
      "pausedAt": 1757161200
    }

    reason and code are present when Polymorfa paused the campaign for you. It carries one of these codes:

    codeMeaning
    campaigns_not_entitledNo Number the campaign sends from is on a plan with Campaigns.
    bansafe_team_suspendedEvery Number in the team is suspended.
    bansafe_suspendedEvery Number the campaign sends from is suspended.
    campaign_throughput_cappedThe campaign asked for more throughput than its Numbers are allowed.
    number_quality_droppedAn official WhatsApp Business Number's quality rating dropped, or WhatsApp flagged it, while the campaign ran.
    messaging_limit_droppedWhatsApp lowered the messaging limit of an official WhatsApp Business Number while the campaign ran.
    invalid_parameterA Number selected for the campaign was removed from the project, or the selected Numbers now use different sending types. Review the selection.
    hybrid_campaign_unsupportedThe campaign sends from a Hybrid Link Number, which campaigns cannot use.
    blocked_by_safetyAnother safety check on the sending Numbers stopped the campaign.

    Resume the campaign once the cause is resolved. See Campaigns and number safety.

  • campaign.launched

    Campaign began sending.

    • campaignIdstringrequired

      Campaign id

    • namestringrequired

      Human-readable name for this resource.

    • recipientCountintegerrequiredmin0

      Number of recipients.

    • scheduledbooleanrequired

      Whether scheduled.

    • launchedAtintegerrequiredmin0

      Unix timestamp in milliseconds when sending began

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "name": "string",
      "recipientCount": 0,
      "scheduled": true,
      "launchedAt": 0
    }

    launchedAt uses Unix milliseconds.

  • campaign.resumed

    Campaign resumed sending.

    • campaignIdstringrequired

      Campaign id

    • sentCountintegerrequiredmin0

      Number of sents.

    • remainingCountintegerrequiredmin0

      Number of remainings.

    • resumedAtintegerrequiredmin0

      Unix timestamp in milliseconds when sending resumed

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sentCount": 0,
      "remainingCount": 0,
      "resumedAt": 0
    }

    A paused campaign begins sending again. resumedAt uses Unix milliseconds.

  • campaign.stopped

    Campaign stop settled.

    • campaignIdstringrequired

      Campaign id

    • sentCountintegerrequiredmin0

      Number of sents.

    • abandonedCountintegerrequiredmin0

      Number of abandoneds.

    • stoppedAtintegerrequiredmin0

      Unix timestamp in milliseconds when the stop settled

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sentCount": 0,
      "abandonedCount": 0,
      "stoppedAt": 0
    }

    The stop changes the campaign to cancelled. abandonedCount counts queued recipients skipped by cancellation; sends already in flight are excluded and may settle later. stoppedAt uses Unix milliseconds.

  • campaign.rescheduled

    A scheduled campaign's start time moved.

    • campaignIdstringrequired

      Campaign id

    • previousScheduledAtintegerrequirednullablemin0

      The start time that was replaced, in Unix milliseconds

    • scheduledAtintegerrequiredmin0

      The new start time in Unix milliseconds. Equal to rescheduledAt when the campaign was asked to start now.

    • rescheduledAtintegerrequiredmin0

      Unix timestamp in milliseconds when the new start time was accepted

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "previousScheduledAt": 0,
      "scheduledAt": 0,
      "rescheduledAt": 0
    }

    The start of a launched campaign that was still waiting for it moved. previousScheduledAt is the replaced start and scheduledAt the new one; both use Unix milliseconds. For a request to start now, scheduledAt equals rescheduledAt.

  • campaign.completed

    Campaign finished sending.

    • campaignIdstringrequired

      Campaign id

    • sentCountintegerrequiredmin0

      Number of sents.

    • deliveredCountintegerrequiredmin0

      Number of delivereds.

    • readCountintegerrequiredmin0

      Number of reads.

    • failedCountintegerrequiredmin0

      Number of faileds.

    • skippedCountintegerrequiredmin0

      Number of skippeds.

    • responseCountintegerrequiredmin0

      Number of responses.

    • completedAtintegerrequiredmin0

      Unix timestamp in seconds when the last recipient settled

    • durationMsintegerrequiredmin0

      Wall-clock duration from launch to completion, in milliseconds

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sentCount": 0,
      "deliveredCount": 0,
      "readCount": 0,
      "failedCount": 0,
      "skippedCount": 0,
      "responseCount": 0,
      "completedAt": 1757161200,
      "durationMs": 0
    }

    Every recipient has resolved, including every message of a multi-message campaign, with at least one sent or skipped recipient, or with no recipients. Carries the final counters and the time from launch to completion.

  • campaign.failed

    Campaign failed.

    • campaignIdstringrequired

      Campaign id

    • reasonstringrequired

      Stable reason the campaign failed

    • failedAtintegerrequiredmin0

      Unix timestamp in seconds when the campaign failed

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "reason": "all_recipients_failed",
      "failedAt": 1757161200
    }

    Every recipient in the campaign failed. reason is all_recipients_failed.

  • campaign.recipient_sent

    A campaign recipient was sent.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • sessionKeystringrequired

      Sending number's session key

    • externalMessageIdstringrequired

      WhatsApp message id of the delivered send

    • variantKeystringrequired

      Content variant used for this recipient

    • attemptintegerrequiredgreater than0

      Attempt number that succeeded

    • messageIndexintegermin0

      Position of this message in the campaign's message sequence, from 0. One event is sent per message; 0 is the recipient's first message. Absent on events produced before sequences, which always mean 0.

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "sessionKey": "sales-1",
      "externalMessageId": "3EB0A1B2C3D4E5F60718",
      "variantKey": "v1",
      "attempt": 1
    }

    A campaign with several messages sends one event per message; messageIndex is its position, from 0. Match externalMessageId against later message.ack events for delivery and read receipts.

  • campaign.recipient_delivered

    A campaign recipient's first delivery receipt.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • sessionKeystringrequired

      Sending number's session key

    • externalMessageIdstringrequiredmin length1

      WhatsApp message id of the campaign send

    • deliveredAtintegerrequiredmin0

      Unix timestamp in seconds of the first delivery receipt

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "sessionKey": "sales-1",
      "externalMessageId": "string",
      "deliveredAt": 1757161200
    }

    A read receipt also establishes delivery when no earlier delivery receipt arrived. Requires the recipient engagement events beta.

  • campaign.recipient_read

    A campaign recipient's first read receipt.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • sessionKeystringrequired

      Sending number's session key

    • externalMessageIdstringrequiredmin length1

      WhatsApp message id of the campaign send

    • readAtintegerrequiredmin0

      Unix timestamp in seconds of the first read receipt

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "sessionKey": "sales-1",
      "externalMessageId": "string",
      "readAt": 1757161200
    }

    Requires the recipient engagement events beta.

  • campaign.recipient_replied

    A campaign recipient's first attributed reply.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • sessionKeystringrequired

      Sending number's session key

    • externalMessageIdstringrequirednullablemin length1

      WhatsApp message id of the campaign send, or null when unavailable

    • repliedAtintegerrequiredmin0

      Unix timestamp in seconds of the first attributed reply

    • responseMsintegerrequiredmin0

      Milliseconds from send to first reply

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "sessionKey": "sales-1",
      "externalMessageId": "string",
      "repliedAt": 1757161200,
      "responseMs": 0
    }

    The first reply attributed to a recipient sent from the same Number within seven days. The event includes responseMs, not the reply body. Requires the recipient engagement events beta.

  • campaign.recipient_failed

    A campaign recipient failed after its last attempt.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • attemptsintegerrequiredmin0

      Attempts made before giving up

    • errorstringrequired

      Sanitized failure class or stable code

    • failedAtintegerrequiredmin0

      Unix timestamp in seconds when the recipient was marked failed

    • messageIndexintegermin0

      Position of the failed message in the campaign's message sequence, from 0. Above 0, the earlier messages were sent and the recipient stays sent; its remaining messages are not sent. Absent on events produced before sequences, which always mean 0.

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "attempts": 0,
      "error": "ack_timeout",
      "failedAt": 1757161200
    }

    A campaign message failed after every attempt. An attempt that will be retried does not produce this event. When messageIndex is above 0, the earlier messages were sent, the recipient stays sent, and its remaining messages are not sent.

  • campaign.recipient_skipped

    A campaign recipient was skipped.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • reasonstringrequired

      Stable skip reason: optout, frequency_cap_exceeded for a campaign contact cap, or whatsapp_marketing_limit when WhatsApp withheld a marketing message because the person reached their per-user marketing message limit

    • messageIndexintegermin0

      Position from 0 of a capped sequence message. Above 0, the initial send status is preserved and remaining sequence messages stop.

    • followUpIdstring (uuid)

      Receipt-timed follow-up cancelled by the contact frequency cap; the initial send status is preserved.

    • skippedAtintegerrequiredmin0

      Unix timestamp in milliseconds when the recipient was skipped

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "reason": "whatsapp_marketing_limit",
      "skippedAt": 1757161200000
    }

    Most reasons are decided before sending, such as an opt-out (reason optout) or a variable with no value and no fallback (reason missing_variable). whatsapp_marketing_limit is reported by WhatsApp after it accepted the send and withheld a marketing message because the person reached their marketing message limit; that recipient moves from sent to skipped, and the event arrives with an empty session.

  • campaign.throttled

    Campaign sending was paced.

    • campaignIdstringrequired

      Campaign id

    • sessionKeystringrequired

      Sending number's session key

    • reasonstringrequired

      Why sending was paced: paced, bansafe_throttled, daily_allowance_reached, or new_chat_limit_reached (WhatsApp capped this number's new chats for the current cycle)

    • deferredCountintegerrequiredmin0

      Recipients deferred in this pass

    • atintegerrequiredmin0

      Unix timestamp in seconds of the pacing decision

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sessionKey": "sales-1",
      "reason": "bansafe_throttled",
      "deferredCount": 0,
      "at": 1757161200
    }

    Sending was paced back because no Number in the pool could send this pass. reason names what held the pass back. paced means no number in the campaign's own pool could send this pass. Once automatic restrictions are enabled, bansafe_throttled means a restriction on the sending Number paced it. new_chat_limit_reached means WhatsApp capped the sending Number's new chats for the current cycle; see WhatsApp new-chat cap. Either way the recipient is queued again and retried, no delivery attempt is spent, and failedCount does not move. See Campaigns and number safety.

  • campaign.cap_reached

    A sending number reached its hourly or daily cap.

    • campaignIdstringrequired

      Campaign id

    • sessionKeystringrequired

      Sending number's session key

    • phonestringrequired

      Sending number in E.164

    • capTypestringrequired

      Which cap was reached: hourly or daily (the campaign's own caps), or new_chat (WhatsApp's per-number new-chat cap)

    • capLimitintegerrequiredmin0

      The cap that was reached. For new_chat, the quota WhatsApp reported

    • windowResetsAtintegerrequiredmin0

      Unix timestamp in seconds when the cap window resets. For new_chat, the end of WhatsApp's cycle, or of Polymorfa's one-hour hold when WhatsApp rejected a new chat without reporting a cycle

    • atintegerrequiredmin0

      Unix timestamp in seconds of the decision

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "sessionKey": "sales-1",
      "phone": "+14155550100",
      "capType": "daily",
      "capLimit": 0,
      "windowResetsAt": 1757161200,
      "at": 1757161200
    }

    The Number reached its hourly or daily cap, or WhatsApp's new-chat cap (capType new_chat), and left the pool for that window.

  • campaign.cold_blocked

    A campaign recipient was held because they never wrote first.

    • campaignIdstringrequired

      Campaign id

    • recipientIdstringrequired

      Campaign recipient id

    • phonestringrequired

      Recipient phone number in E.164

    • surfacestringrequired

      Campaign surface

    • reasonstringrequired

      Stable hold reason

    • atintegerrequiredmin0

      Unix timestamp in seconds when the recipient was held

    Example payload
    {
      "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66",
      "phone": "+14155550123",
      "surface": "whatsapp",
      "reason": "bansafe_cold_held",
      "at": 1757161200
    }

    A recipient held this way is counted once in skippedCount. Polymorfa does not attempt that recipient again and does not count the hold as a failure, so a list of people who have never written to you leaves failedCount at zero. To message them anyway, set senderConfig.throughput.coldSendPolicy to allow. See Campaigns and BanSafe.

Customers

Related resource Customers

Customer events go to team webhooks.

  • customer.enabled

    Customers enabled for a project.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • migratedNumberCountintegerrequiredmin0

      Number of migrated numbers.

    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "migratedNumberCount": 0
    }
  • customer.created

    Customer created.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth"
    }
  • customer.updated

    Customer updated.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • fieldsarray of stringrequireditems1–3

      Fields associated with this native customer updated payload.

      Allowed valuesnamephoneexternalCustomerId
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "fields": [
        "name"
      ]
    }
  • customer.archiving

    Customer archival started.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • blockingNumberCountintegerrequiredmin0

      Number of blocking numbers.

    • revokedPairingLinkCountintegerrequiredmin0

      Number of revoked pairing links.

    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "blockingNumberCount": 0,
      "revokedPairingLinkCount": 0
    }
  • customer.archived

    Customer archived.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth"
    }
  • customer.restored

    Customer restored.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth"
    }
  • customer.number.attached

    Number attached to a Customer.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • sessionIdstring (uuid)required

      Identifier of the connected Polymorfa session.

    • pairingLinkIdstring (uuid)

      Identifier for the pairing link.

    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "sessionId": "00000000-0000-4000-8000-000000000000"
    }
  • customer.number.transferred

    Number transferred to a Customer.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • sessionIdstring (uuid)required

      Identifier of the connected Polymorfa session.

    • sourceCustomerIdstring (uuid)required

      Identifier for the source customer.

    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "sessionId": "00000000-0000-4000-8000-000000000000",
      "sourceCustomerId": "00000000-0000-4000-8000-000000000000"
    }
  • customer.number.disconnected

    Customer Number disconnected.

    • eventIdstring (uuid)required

      Identifier for the event.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • customerIdstring (uuid)required

      Identifier for the customer.

    • actorKindstringrequired

      Category assigned to actor.

      Allowed valuesbetter_authteam_keyproject_tokencli_grantsystem
    • sessionIdstring (uuid)required

      Identifier of the connected Polymorfa session.

    • reasonstringrequiredpattern^[a-z0-9_]{1,64}$

      Reason for the reported state or outcome.

    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "actorKind": "better_auth",
      "sessionId": "00000000-0000-4000-8000-000000000000",
      "reason": "string"
    }

Safety

Related resource BanSafe

Safety events are session-scoped and delivered in native format only. A format: "meta" webhook does not receive them. Safety payloads identify your own sending session and do not contain message content, message IDs, recipient IDs, or chat history.

Polymorfa does not send bansafe.risk_changed, bansafe.health_changed, or bansafe.enforcement. New subscriptions cannot select them. An endpoint that already lists one keeps its other events; you can remove the old name when you edit it. Use bansafe.incident for restrictions WhatsApp applies, bansafe.health_threshold for Health alerts, and the BanSafe API to read a Number's current state. See also Warm-up plan and Ban Credit.

  • bansafe.action

    Polymorfa applied, changed, or lifted a safety restriction on a number.

    • phoneNumberstringrequiredpattern^\+[1-9]\d{1,14}$

      The customer's own number in E.164 format.

    • actionstringrequired

      Whether the restriction was newly applied, moved, or removed. daily_allowance_reached reports that the number spent its warm-up allowance for the day; nothing on the ladder moved and sending resumes at the next reset.

      Allowed valuesappliedchangedlifteddaily_allowance_reached
    • scopestringrequired

      Whether this covers one number or every number in the workspace.

      Allowed valuesnumberteam
    • rungstringrequired

      Restriction now in force.

      Allowed valuesnonenotifythrottleblock_coldsuspend
    • previousRungstringrequirednullable

      Restriction previously in force, or null when none was.

      Allowed valuesnonenotifythrottleblock_coldsuspend
    • reasonstringrequired

      Why the restriction changed.

      Allowed valueshealthfindingteam_patternrepeatrestrictionoperatorhealth_model_cutoverwarmup
    • healthintegerrequirednullablerange0–100

      Measured health from 0 (worst) to 100 (best), or null when not measured.

    • healthBandstringrequired

      Health band matching health.

      Allowed valuesgoodfairpoorfailingunknown
    • requiresarray of objectrequiredmax items25

      Findings that must resolve before this restriction lifts.

      Show 3 child fields
    • throughputPerMinuteintegerrequirednullablerange0–10000

      Messages per minute allowed while paced, or null when not paced.

    • eligibleLiftAtstringrequirednullableformatdate-time

      Earliest instant the restriction can step down, ISO 8601.

    • liftRequiresstringrequiredlength1–240

      One sentence describing what lifts the restriction.

    • appealUrlstring (uri)requiredmax length500

      Where to appeal this action.

    • startedAtstring (date-time)required

      ISO 8601 timestamp when this restriction took effect.

    • docsstring (uri)requiredmax length500

      Documentation for this restriction.

    Example payload
    {
      "phoneNumber": "+15551234567",
      "action": "applied",
      "scope": "number",
      "rung": "none",
      "previousRung": "none",
      "reason": "health",
      "health": 62,
      "healthBand": "good",
      "requires": [
        {
          "findingKey": "typing_absent",
          "title": "Messages sent without showing that you are typing",
          "severity": "info"
        }
      ],
      "throughputPerMinute": 6,
      "eligibleLiftAt": "2026-09-08T14:00:00.000Z",
      "liftRequires": "Resolve the two open checks and keep them clean for six evaluations.",
      "appealUrl": "https://app.polymorfa.com/safety/appeal",
      "startedAt": "2026-09-06T14:00:00.000Z",
      "docs": "https://docs.polymorfa.com/safety/restrictions"
    }

    Describes an action, not a Health estimate. A Polymorfa restriction changed, or the Number reached its warm-up allowance. For a daily allowance notice it uses action: "daily_allowance_reached" and reason: "warmup"; its rung does not change and eligibleLiftAt gives the next reset.

  • bansafe.health_threshold

    A project's present Health rule crossed below its threshold.

    • sessionIdstring (uuid)required

      Session whose present Health crossed the project threshold.

    • projectIdstring (uuid)required

      Project whose Health rule produced this action.

    • healthnumberrequiredrange0–100

      Present Health; higher is healthier.

    • thresholdintegerrequiredrange0–100

      Configured project threshold crossed by this evaluation.

    • healthSourcestringrequired

      Estimator family used by the evaluation.

      Allowed valuesrules_v1ml_model
    • estimatorVersionstringrequiredlength1–128

      Estimator version used by the evaluation.

    • modelVersionstringrequirednullablelength1–128

      Learned-model version, or null for a rules-based estimate.

    • evaluatedAtstring (date-time)required

      Evaluation time in ISO 8601 format.

    • policyVersionintegerrequiredrange1–9007199254740991

      Project Health rule version evaluated.

    • episodeIdstring (uuid)required

      Stable below-threshold episode identifier.

    • actionIdstring (uuid)required

      Stable event identity used for retries.

    Example payload
    {
      "sessionId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "health": 0,
      "threshold": 0,
      "healthSource": "rules_v1",
      "estimatorVersion": "string",
      "modelVersion": "string",
      "evaluatedAt": "2026-09-22T12:00:00Z",
      "policyVersion": 1,
      "episodeId": "00000000-0000-4000-8000-000000000000",
      "actionId": "00000000-0000-4000-8000-000000000000"
    }

    A configured project rule queued an action for a fresh Health estimate below its threshold. Rules-v1 events set modelVersion to null. The event id is the stable action ID, so retries can be deduplicated by event ID. An unavailable or stale Health estimate does not produce this event.

  • bansafe.incident

    A restriction was recorded on a number, or the record of one settled.

    • idstringrequired

      Incident id. Stable, quotable, and the subject of a Ban Credit claim.

    • phoneNumberstringrequiredpattern^\+[1-9]\d{1,14}$

      The customer's own number in E.164 format.

    • kindstringrequired

      What WhatsApp did, or customer_report when you reported it.

      Allowed valuescap_warningcap_reachedtimelocktemporary_banpermanent_banconnect_blockedcustomer_report
    • sourcestringrequired

      Whether Polymorfa observed it or you reported it.

      Allowed valuesruntimecustomer
    • startedAtstring (date-time)required

      ISO 8601 timestamp when the restriction started.

    • endsAtstringrequirednullableformatdate-time

      ISO 8601 timestamp when the restriction ends, or null when it has no end. A ban you report ends 24 hours after the time you give unless you report it again or Polymorfa observes the restriction itself.

    • beliefnumberrequiredrange0–1

      How confident Polymorfa is that this restriction was real, from 0 to 1. A restriction WhatsApp announced is 1. A ban you report starts at 0.9 and moves once the number's own sending shows whether it was restricted.

    • resolutionstringrequired

      How the incident settled. open: still being decided. corroborated: a report and an observed restriction agree. contradicted: the number kept sending, so there was no restriction. phone_switch: the number moved to another phone. final: settled with the confidence shown.

      Allowed valuesopencorroboratedcontradictedphone_switchfinal
    • claimIdstringrequirednullable

      The Ban Credit claim this incident belongs to, or null when there is none.

    • closedAtstringrequirednullableformatdate-time

      ISO 8601 timestamp when you closed or retracted the report, or null.

    Example payload
    {
      "id": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "phoneNumber": "+15551234567",
      "kind": "cap_warning",
      "source": "runtime",
      "startedAt": "2026-09-06T14:03:12.000Z",
      "endsAt": "2026-09-07T14:03:12.000Z",
      "belief": 1,
      "resolution": "open",
      "claimId": null,
      "closedAt": null
    }

    The durable record of a restriction WhatsApp applied or you reported. It arrives once when the record is created and again when it settles; kind and source say what happened and who observed it.

  • bansafe.claim

    A Ban Credit claim was filed on a ban, decided, paid, or reversed.

    • idstringrequired

      Claim id. Stable and quotable.

    • incidentIdstringrequired

      The incident this claim was filed against.

    • phoneNumberstringrequiredpattern^\+[1-9]\d{1,14}$

      The customer's own number in E.164 format.

    • statusstringrequired

      Where the claim sits. filed and under_review are open. approved means it was accepted, and with a zero amount that there was nothing to return. paid means the credits are on your balance. reversed means what Polymorfa knew about the ban changed afterwards and the credits were taken back.

      Allowed valuesfiledunder_reviewapproveddeniedpaidreversed
    • verdictstringrequired

      What the ban was attributed to. other_device: another device on the account was sending. customer_conduct: Polymorfa was already restricting this number, or named the same serious problem for a week. shared_network: the number shared its connection with numbers that were being restricted. ours: nothing points at how the number was used. inconclusive: Polymorfa could not see enough of the window to say. simultaneous_calls: simultaneous calls were on for the number inside the window, which voids Ban Credit; the claim is denied when filed. linked_device_interactive: the number sent an interactive message (buttons, lists, product messages, Flows and similar) from a linked device inside the window, which voids Ban Credit; the claim is denied when filed.

      Allowed valuesother_devicecustomer_conductshared_networkoursinconclusivesimultaneous_callslinked_device_interactive
    • windowStartstring (date-time)required

      ISO 8601 start of the 30 days the refund covers.

    • windowEndstring (date-time)required

      ISO 8601 end of the window: the moment the ban started.

    • measuredCentsnumberrequiredmin0multiple of0.000001

      Credit quantity this number consumed inside the window, with up to six decimal places.

    • capCentsnumberrequiredmin0multiple of0.000001

      Maximum credit quantity this claim can return, with up to six decimal places.

    • amountCentsnumberrequiredmin0multiple of0.000001

      Credit quantity this claim returns, with up to six decimal places.

    • summarystringrequired

      One sentence describing the claim's state.

    • reasonstringrequired

      One sentence describing what the ban was attributed to.

    • decidedAtstringrequirednullableformatdate-time

      ISO 8601 timestamp of the decision, or null while none was taken.

    • paidAtstringrequirednullableformatdate-time

      ISO 8601 timestamp the credits landed, or null.

    Example payload
    {
      "id": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f22",
      "incidentId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11",
      "phoneNumber": "+15551234567",
      "status": "filed",
      "verdict": "other_device",
      "windowStart": "2026-08-07T14:03:12.000Z",
      "windowEnd": "2026-09-06T14:03:12.000Z",
      "measuredCents": 1080,
      "capCents": 1080,
      "amountCents": 1080,
      "summary": "string",
      "reason": "string",
      "decidedAt": null,
      "paidAt": null
    }

Templates

Related resource Templates

Account and template changes belong to the WhatsApp Business Account, so each Cloud API Number under that account receives its own copy with its own event id. Message, status, and display-name changes reach only the Number they identify. In the format: "meta" envelope of an account, display-name, or template notification, entry.id is the WhatsApp Business Account that sent it, even if the Number has since moved to another account, and entry.time is the event timestamp in Unix seconds.

WhatsApp redelivers a notification until Polymorfa accepts it. A redelivery of the same notification to a Number produces the same event id, and Polymorfa normally suppresses the repeat. Two separate changes, such as a template that is paused and later approved again, produce different IDs. An account or template notification that arrives without a WhatsApp time is always published, so its redeliveries can arrive with different IDs. Delivery is at least once, so deduplicate on id. When WhatsApp reports a time for a template, account, Business app echo, contact sync, or history sync change, the event timestamp is that time rather than the time Polymorfa received the notification.

  • template.status

    Message template approval status changed.

    RuntimeTemplateStatusPayload
    • templateNamestringrequired

      Template name as registered with Meta

    • templateIdstringrequired

      Meta template id

    • statusstringrequired

      New approval status: APPROVED, REJECTED, PAUSED, DISABLED, DELETED

    • categorystringrequired

      Template category (MARKETING, UTILITY, AUTHENTICATION)

    • reasonstringrequired

      Reason for the status change; empty unless REJECTED, PAUSED or DISABLED

    • qualityRatingstringrequired

      Quality rating bucket reported by Meta (GREEN, YELLOW, RED)

    kind
    • kindstringrequired

      message_template_status_update for an approval change, message_template_quality_update for a quality change

      Allowed valuesmessage_template_status_updatemessage_template_quality_update
    • eventstring

      New template status reported by WhatsApp; for a quality change, the new quality score

    • templateIdstring

      WhatsApp template id

    • templateNamestring

      Template name

    • languagestring

      Template language code

    • reasonstring

      WhatsApp's explanation for the change, when supplied

    • previousQualityScorestring

      Quality score before a quality change

    • newQualityScorestring

      Quality score after a quality change

    • wabaIdstring

      WhatsApp Business Account id that owns the template

    Example payload
    {
      "templateName": "order_update",
      "templateId": "1234567890",
      "status": "APPROVED",
      "category": "UTILITY",
      "reason": "",
      "qualityRating": "GREEN"
    }

    Reports what WhatsApp did to one of your Cloud API message templates. kind is message_template_status_update for an approval change and message_template_quality_update for a quality change. event carries the new status and reason carries WhatsApp's explanation when it gives one. A quality change carries previousQualityScore and newQualityScore, and its event is the new quality score. templateId (a string), templateName, language, and wabaId identify the template and the WhatsApp Business Account that owns it. Only kind is guaranteed; the other fields are present when WhatsApp sends them.

Voice

Related resource Voice

Voice events require access to Voice Automation.

  • voice.asset_ready

    Audio asset ready.

    • eventIdstring (uuid)required

      Stable event ID for receiver idempotency.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • assetIdstring (uuid)required

      Identifier for the asset.

    • namestringrequired

      Human-readable name for this resource.

    • sourcestringrequired

      upload or tts. Treat unknown values as upload.

      Allowed valuesuploadtts
    • durationMsintegerrequiredgreater than0

      Specifies duration ms for this native voice asset ready payload.

    • contentSha256stringrequiredpattern^[0-9a-f]{64}$

      SHA-256 (hex) of the converted 16 kHz mono PCM audio.

    • originalFormatstringrequired

      Specifies original format for this native voice asset ready payload.

      Allowed valuesmp3wavoggm4a
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "assetId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "source": "upload",
      "durationMs": 0,
      "contentSha256": "string",
      "originalFormat": "mp3"
    }
  • voice.asset_failed

    Audio asset failed.

    • eventIdstring (uuid)required

      Stable event ID for receiver idempotency.

    • occurredAtstring (date-time)required

      Timestamp for occurred at.

    • teamIdstring (uuid)required

      Identifier for the team.

    • projectIdstring (uuid)required

      Identifier of the Polymorfa project that owns this resource.

    • assetIdstring (uuid)required

      Identifier for the asset.

    • namestringrequired

      Human-readable name for this resource.

    • sourcestringrequired

      upload or tts. Treat unknown values as upload.

      Allowed valuesuploadtts
    • failureReasonstringrequired

      Treat unknown values as processing_failed.

      Allowed valuesunsupported_formattoo_largetoo_longdecode_failedsilenttts_failedprocessing_failed
    Example payload
    {
      "eventId": "00000000-0000-4000-8000-000000000000",
      "occurredAt": "2026-09-22T12:00:00Z",
      "teamId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "assetId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "source": "upload",
      "failureReason": "unsupported_format"
    }

Commands, history and usage

  • usage.recorded

    Usage recorded.

    • idstring (uuid)required

      Usage record id. Stable across revisions.

    • meterstringrequired

      What was measured. Calls produce call.duration, and outgoing Cloud API calls also call.cloud_pulses.

      Allowed valuescall.durationcall.cloud_pulsescampaign.calltts.characterstts.secondsstt.secondsagent.secondsagent.tokensagent.provider_costchannels.peakstorage.byte_days
    • quantitynumberrequiredmin0

      Measured amount in unit.

    • unitstringrequired

      Specifies unit for this native usage recorded payload.

      Allowed valuessecondpulsecallcharactertokenprovider_unitchannelbyte_day
    • dimensionsobjectrequired

      Closed, per-meter attributes. Call meters carry direction, upstream (linked_device or cloud_api), origin, participants, connections, sipLegs and video.

    • keySourcestringrequired

      Whose provider key produced the usage. none for calls.

      Allowed valuesnonemanagedcustomer
    • sourceKindstringrequired

      Category assigned to source.

      Allowed valuescallattemptflow_runconversationassetteam
    • sourceIdstringrequired

      The call id for call meters.

    • projectIdstringrequirednullableformatuuid

      Identifier of the Polymorfa project that owns this resource.

    • sessionstringrequirednullable

      The number (session name) the usage belongs to.

    • occurredAtstring (date-time)required

      When the usage happened. For calls, when the call ended.

    • recordedAtstring (date-time)required

      Timestamp for recorded at.

    • revisionintegerrequiredmin1

      Starts at 1. A higher revision of the same id replaces the earlier one.

    • pricingStatestringrequired

      unpriced while usage is measured but not charged.

      Allowed valuesunpricedpricedwaivedsettled
    • rateCardobjectrequirednullable

      Structured rate card values for this native usage recorded payload.

      Show 2 child fields
    • pricedCreditsnumberrequirednullable

      Specifies priced credits for this native usage recorded payload.

    Example payload
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "meter": "call.duration",
      "quantity": 42,
      "unit": "second",
      "dimensions": {
        "direction": "outbound",
        "upstream": "linked_device",
        "origin": "direct",
        "participants": 1,
        "connections": 1,
        "sipLegs": 0,
        "video": false
      },
      "keySource": "none",
      "sourceKind": "call",
      "sourceId": "string",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "session": "string",
      "occurredAt": "2026-09-22T12:00:00Z",
      "recordedAt": "2026-09-22T12:00:00Z",
      "revision": 1,
      "pricingState": "unpriced",
      "rateCard": {
        "id": "00000000-0000-4000-8000-000000000000",
        "version": 0
      },
      "pricedCredits": 0
    }
  • history.sync

    History sync chunk.

    LinkedHistorySyncPayload
    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • original_whatsapp_idsobject

      Specifies original whatsapp ids for this native linked history sync payload.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • original_whatsapp_idstringdeprecatedlength1–512

      Temporary singular original provider reference for older consumers. Use original_whatsapp_ids for transport-specific references.

    • messagesarray of objectrequired

      Messages associated with this native linked history sync payload.

      Show 5 child fields
    • modestringrequired

      Operating mode selected for this feature.

      Allowed valuesdeliver
    • syncTypestringrequired

      Category assigned to sync.

    • chunkOrderintegermin0

      Specifies chunk order for this native linked history sync payload.

    • progressintegerrange0–100

      Specifies progress for this native linked history sync payload.

    • fileLengthintegerrequiredmin0

      Size of the media file in bytes.

    • conversationCountintegerrequiredmin0

      Number of conversations.

    • messageCountintegerrequiredmin0

      Number of messages.

    • pushNameCountintegerrequiredmin0

      Number of push names.

    • statusMessageCountintegerrequiredmin0

      Number of status messages.

    • whatsappobjectrequired

      Unmodified provider archive. Its protobuf retains provider addresses; use messages for Polymorfa identities.

      Show 2 child fields
    media
    • deliverystringrequired

      Specifies delivery for this any of.

      Allowed valuesdescriptor
    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • original_whatsapp_idsobject

      Specifies original whatsapp ids for this any of.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • original_whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • syncTypestringrequiredmin length1

      Category assigned to sync.

    • chunkOrderintegermin0

      Specifies chunk order for this any of.

    • progressintegerrange0–100

      Specifies progress for this any of.

    • fileLengthintegerrequiredmin0

      Size of the media file in bytes.

    • oldestMessageAtstring (date-time)

      Timestamp for oldest message at.

    • peerDataRequestSessionIdstring

      Identifier for the peer data request session.

    • mediaobjectrequired

      Reference to the media attached to this message.

      Show 6 child fields
    inline
    • deliverystringrequired

      Specifies delivery for this any of.

      Allowed valuesdescriptor
    • whatsapp_idsobjectrequired

      Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • original_whatsapp_idsobject

      Specifies original whatsapp ids for this any of.

      One of
      • linked_devicesstringrequiredlength1–512

        Specifies linked devices for this any of.

      • official_apistringlength1–512

        Specifies official api for this any of.

    • original_whatsapp_idstringdeprecatedlength1–512

      Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

    • syncTypestringrequiredmin length1

      Category assigned to sync.

    • chunkOrderintegermin0

      Specifies chunk order for this any of.

    • progressintegerrange0–100

      Specifies progress for this any of.

    • fileLengthintegerrequiredmin0

      Size of the media file in bytes.

    • oldestMessageAtstring (date-time)

      Timestamp for oldest message at.

    • peerDataRequestSessionIdstring

      Identifier for the peer data request session.

    • inlineobjectrequired

      Structured inline values for this any of.

      Show 2 child fields
    CloudHistorySyncPayload
    • kindstringrequired

      Kind discriminator for this object.

      Allowed valueshistory
    • valueobjectrequired

      Value assigned to this field.

    Example payload
    {
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "messages": [
        {
          "id": "739182640518203",
          "whatsapp_ids": {
            "linked_devices": null
          },
          "conversation": {
            "id": "739182640518203"
          }
        }
      ],
      "mode": "deliver",
      "syncType": "string",
      "fileLength": 0,
      "conversationCount": 0,
      "messageCount": 0,
      "pushNameCount": 0,
      "statusMessageCount": 0,
      "whatsapp": {
        "encoding": "gzip-base64-protobuf",
        "data": "string"
      }
    }
  • command.result

    Async command completed.

    • requestIdstringrequired

      Identifier used to correlate this request across systems.

    • commandstringrequired

      Specifies command for this native command result payload.

    • successbooleanrequired

      Whether the request succeeded.

    • dataobject

      Structured data carried by this object.

    • errorstring

      Error details returned when the operation fails.

    Example payload
    {
      "requestId": "string",
      "command": "string",
      "success": true
    }