Events
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
idstringrequiredUnique event ID. Use it to deduplicate retries.
sessionstringrequiredThe Number that produced the event. Empty for team and project events, such as campaign lifecycle, Customer and voice events.
externalIdstringYour reference from the QuickLink that created the Number, on Number lifecycle events, when you supplied one.
timestampstringrequiredWhen the event happened, in ISO 8601.
eventstringrequiredThe event type, such as
message.received. See Types of events.payloadobjectrequiredData specific to the event type. Each type below lists its payload fields.
{
"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)requiredIdentifier for this resource.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstringrequirednullableIdentifier of the Polymorfa project that owns this resource.
typestringrequiredlength1–128Type discriminator for this object.
sourcestringrequiredSpecifies source for this management team event.
Allowed valuesruntimeplatformtestenvironmentstringrequiredSpecifies environment for this management team event.
Allowed valuesdevelopmentproductioncreatedAtstring (date-time)requiredISO 8601 timestamp when this resource was created.
payloadAvailabilitystringrequiredSpecifies payload availability for this management team event.
Allowed valuesavailablenot_retainedexpiredredactedunavailablepayloadobjectrequirednullableStructured payload carried by this event or operation.
Show 3 child fields
replayableUntilstring (date-time)requirednullableSpecifies replayable until for this management team event.
metadataExpiresAtstring (date-time)requiredTimestamp for metadata expires at.
{
"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)requiredIdentifier for this resource.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
typestringrequiredlength1–128Type discriminator for this object.
sourcestringrequiredSpecifies source for this management project event.
Allowed valuesruntimeplatformtestenvironmentstringrequiredSpecifies environment for this management project event.
Allowed valuesdevelopmentproductioncreatedAtstring (date-time)requiredISO 8601 timestamp when this resource was created.
payloadAvailabilitystringrequiredSpecifies payload availability for this management project event.
Allowed valuesavailablenot_retainedexpiredredactedunavailablepayloadobjectrequirednullableStructured payload carried by this event or operation.
Show 3 child fields
replayableUntilstring (date-time)requirednullableSpecifies replayable until for this management project event.
metadataExpiresAtstring (date-time)requiredTimestamp for metadata expires at.
{
"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
- 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
typestringType discriminator for this object.
sincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25cursorstringSpecifies 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 objectrequiredStructured data carried by this object.
Show 11 child fields
pageobjectrequiredSpecifies 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.
curl "https://api.polymorfa.com/platform/events" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
Query parameters
typestringType discriminator for this object.
sincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25cursorstringSpecifies 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 objectrequiredStructured data carried by this object.
Show 11 child fields
pageobjectrequiredSpecifies 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/events" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier for the event.
Query parameters
includePayloadbooleanWhether include payload.
Defaultfalse
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/events/<eventId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
eventIdstring (uuid)requiredIdentifier for the event.
Query parameters
includePayloadbooleanWhether include payload.
Defaultfalse
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/events/<eventId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
Query parameters
typesstringSpecifies types for this query parameter.
cursorstringmax length4096Specifies cursor for this query parameter.
ackstringSpecifies ack for this query parameter.
Allowed valuesautomanual
Headers
Last-Event-IDstringmax length4096Identifier 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 type
text/event-streamOne ofvnumberrequiredSpecifies v for this management platform access event stream ready frame.
Allowed values1streamIdstring (uuid)requiredIdentifier for the stream.
sequenceintegerrequiredmin1Frame counter for this connection. It restarts at 1 on every connection.
sentAtstring (date-time)requiredTimestamp for sent at.
typestringrequiredType discriminator for this object.
Allowed valuesreadyprojectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
connectionExpiresAtstring (date-time)requiredTimestamp for connection expires at.
heartbeatIntervalMsintegerrequiredSpecifies heartbeat interval ms for this management platform access event stream ready frame.
maxInFlightintegerrequiredSpecifies max in flight for this management platform access event stream ready frame.
ackstringrequiredSpecifies ack for this management platform access event stream ready frame.
Allowed valuesautomanualtypesarray of stringrequiredTypes associated with this management platform access event stream ready frame.
idleTimeoutMsintegerrequiredSpecifies idle timeout ms for this management platform access event stream ready frame.
resumeobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/events/stream" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"Content type text/event-stream
No example for this content type
Acknowledge project event stream
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
streamIdstring (uuid)requiredIdentifier for the stream.
Body
cursorstringrequiredlength1–4096Specifies cursor for this management platform access event stream ack request.
sequenceintegerrequiredrange1–9007199254740991Specifies sequence for this management platform access event stream ack request.
Responses
200Acknowledged
dataobjectrequiredStructured 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.
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
}'{
"data": {
"streamId": "00000000-0000-4000-8000-000000000000",
"acknowledgedCursor": "string",
"sequence": 0,
"replayed": true
}
}Replay team event
- 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)requiredIdentifier for the event.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
webhookIdstring (uuid)requiredIdentifier for the webhook.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"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
- 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)requiredIdentifier of the Polymorfa project that owns this resource.
eventIdstring (uuid)requiredIdentifier for the event.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
webhookIdstring (uuid)requiredIdentifier for the webhook.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether the connected account originated the message.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
isGroupbooleanrequiredWhether the conversation is a group chat.
typestringrequiredType discriminator for this object.
Allowed valuesShow all 18 values
textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknowntextstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
pttbooleanWhether the audio is presented as a push-to-talk voice message.
filenamestringFilename presented for the media attachment.
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction 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.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
mediastringReference to the media attached to this message.
mediaUrlstringURL used to retrieve the attached media.
editedbooleanWhether the event represents an edited message.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message payload.
accessibilityLabelstringSpecifies accessibility label for this native message payload.
stickerPackobjectSpecifies sticker pack for this native message payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message payload.
Show 5 child fields
associationobjectSpecifies association for this native message payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
timestampstringrequiredUnix timestamp in seconds represented as a decimal string.
typestringrequiredType discriminator for this object.
senderNamestringHuman-readable sender name for this native cloud message payload.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
interactiveobjectStructured interactive values for this native cloud message payload.
orderobjectSpecifies order for this native cloud message payload.
Show 3 child fields
referralobjectMeta-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" }referralidentifies the message's entry point, not a conversion or payment.orderis omitted if any cart item is unreadable. Meta-format delivery usestype: "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. parentMessageIdcan reference any quoted message. Invalid IDs are omitted; a Linked Devices reply without a valid choice ID hastype: "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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
typestringrequiredType discriminator for this object.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message sent payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message sent payload.
accessibilityLabelstringSpecifies accessibility label for this native message sent payload.
stickerPackobjectSpecifies sticker pack for this native message sent payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message sent payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message sent payload.
Show 5 child fields
associationobjectSpecifies association for this native message sent payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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 objectrequiredMessages associated with this native message ack payload.
Show 3 child fields
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromobjectStable identifier for the conversation or account that originated the event.
Show 5 child fields
senderobjectStable identifier for the user who sent the message or event.
Show 5 child fields
typestringrequiredAck type: error, delivered, read, played
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pricingobjectSpecifies 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
messagesarray 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether the connected account originated the message.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
isGroupbooleanrequiredWhether the conversation is a group chat.
typestringrequiredType discriminator for this object.
Allowed valuesShow all 18 values
textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknowntextstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
pttbooleanWhether the audio is presented as a push-to-talk voice message.
filenamestringFilename presented for the media attachment.
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction 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.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
mediastringReference to the media attached to this message.
mediaUrlstringURL used to retrieve the attached media.
editedbooleanWhether the event represents an edited message.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message payload.
accessibilityLabelstringSpecifies accessibility label for this native message payload.
stickerPackobjectSpecifies sticker pack for this native message payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message payload.
Show 5 child fields
associationobjectSpecifies association for this native message payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether the connected account originated the message.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
isGroupbooleanrequiredWhether the conversation is a group chat.
typestringrequiredType discriminator for this object.
Allowed valuesShow all 18 values
textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknowntextstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
pttbooleanWhether the audio is presented as a push-to-talk voice message.
filenamestringFilename presented for the media attachment.
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction 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.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
mediastringReference to the media attached to this message.
mediaUrlstringURL used to retrieve the attached media.
editedbooleanWhether the event represents an edited message.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message payload.
accessibilityLabelstringSpecifies accessibility label for this native message payload.
stickerPackobjectSpecifies sticker pack for this native message payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message payload.
Show 5 child fields
associationobjectSpecifies association for this native message payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
timestampstringrequiredUnix timestamp in seconds represented as a decimal string.
typestringrequiredType discriminator for this object.
senderNamestringHuman-readable sender name for this native cloud message payload.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
interactiveobjectStructured interactive values for this native cloud message payload.
orderobjectSpecifies order for this native cloud message payload.
Show 3 child fields
referralobjectMeta-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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether the connected account originated the message.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
isGroupbooleanrequiredWhether the conversation is a group chat.
typestringrequiredType discriminator for this object.
Allowed valuesShow all 18 values
textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknowntextstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
pttbooleanWhether the audio is presented as a push-to-talk voice message.
filenamestringFilename presented for the media attachment.
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction 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.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
mediastringReference to the media attached to this message.
mediaUrlstringURL used to retrieve the attached media.
editedbooleanWhether the event represents an edited message.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message payload.
accessibilityLabelstringSpecifies accessibility label for this native message payload.
stickerPackobjectSpecifies sticker pack for this native message payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message payload.
Show 5 child fields
associationobjectSpecifies association for this native message payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether the connected account originated the message.
timestampnumberrequiredUnix timestamp in seconds associated with this event.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
isGroupbooleanrequiredWhether the conversation is a group chat.
typestringrequiredType discriminator for this object.
Allowed valuesShow all 18 values
textimagevideoaudiodocumentlocationcontactphone_number_sharednative_flow_responsebutton_replylist_replypollstickersticker_packreactionrevokeeditedunknowntextstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
pttbooleanWhether the audio is presented as a push-to-talk voice message.
filenamestringFilename presented for the media attachment.
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction 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.
nativeFlowResponseobjectStructured response returned by a native Flow interaction.
Show 3 child fields
replyChoiceobjectPresent when the contact selects a reply button or list row.
Show 2 child fields
parentMessageIdstringlength1–128WhatsApp ID of the message this one quotes, when WhatsApp supplies one. It is not necessarily a message you sent.
mediastringReference to the media attached to this message.
mediaUrlstringURL used to retrieve the attached media.
editedbooleanWhether the event represents an edited message.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native message payload.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native message payload.
accessibilityLabelstringSpecifies accessibility label for this native message payload.
stickerPackobjectSpecifies sticker pack for this native message payload.
Show 6 child fields
widthintegergreater than0Image, video or sticker width in pixels, as declared by the sender.
heightintegergreater than0Image, video or sticker height in pixels, as declared by the sender.
secondsintegergreater than0Audio or video duration in seconds.
waveformarray of numbermax items64item range0–1Voice-note waveform: up to 64 samples from 0 to 1.
pageCountintegergreater than0Document page count, as declared by the sender.
thumbnailobjectSpecifies thumbnail for this native message payload.
Show 4 child fields
linkPreviewobjectSpecifies link preview for this native message payload.
Show 5 child fields
associationobjectSpecifies association for this native message payload.
Show 2 child fields
qualitystringhdon the HD half of a pair;standardon 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.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
senderobjectrequiredStable 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
fromMebooleanrequiredWhether 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.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 6 child fields
voterobjectrequiredSpecifies voter for this native poll vote payload.
Show 5 child fields
selectedHashesarray of stringrequiredSelected hashes associated with this native poll vote payload.
timestampnumberrequiredUnix 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.
sourcestringrequiredSpecifies source for this native message echo payload.
Allowed valueswhatsapp_business_appvalueobjectrequiredValue assigned to this field.
Example payload{ "source": "whatsapp_business_app", "value": {} }sticker.update
Sticker favorites, recents and phone reupload results.
kindstringrequiredKind discriminator for this object.
Allowed valuesfavoriterecentrecent_removedreuploadfileSha256stringpattern^[A-Za-z0-9+/]{43}=$Specifies file sha256 for this native sticker update.
timestampintegerrequiredmin0Unix timestamp in milliseconds.
favoritebooleanWhether favorite.
lastStickerSentTsintegermin0Last sticker use as a Unix timestamp in milliseconds.
fromFullSyncbooleanWhether from full sync.
requestIdstringmax length256Identifier used to correlate this request across systems.
statusstringmax length64Current status of this resource or operation.
mediastringmax length16384Reference to the media attached to this message.
descriptorobjectSpecifies descriptor for this native sticker update.
When
mimeTypeisimage/webp:When
mimeTypeisapplication/was, WhenstickerTypeislottie: requiresstickerType
Show 9 child fields
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieemojisarray of stringmax items10item max length128Emojis associated with this native sticker update.
accessibilityLabelstringmax length1024Specifies 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. PreservelastStickerSentTsin 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.
toobjectrequiredSpecifies to for this native message failed payload.
Show 5 child fields
typestringrequiredType of the attempted message (text, image, ...)
errorstringrequiredSanitized failure class
Allowed valuesinvalid_recipientsession_not_connectedack_timeoutsend_failedblocked_by_safetycodestringStable machine-readable code from the API error envelope, present for classified safety refusals and an unknown send outcome
retryAfterintegergreater than0Whole seconds to wait before retrying a paced send, exhausted allowance, or temporary allowance-accounting pause
timestampintegerrequiredmin0Unix 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
errorfield 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 codewhen present.blocked_by_safetyPolymorfa refused the send before it left the platform. For a classified refusal or unknown outcome, the payload carries
codewith 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 retryAfterseconds.bansafe_send_outcome_unknownAnother attempt already reserved this logical send. Do not retry it automatically; reconcile its delivery state first. retryAfteris present on a paced send, an exhausted daily allowance, and a temporary allowance-accounting pause. It is absent onbansafe_send_outcome_unknown.This event tells a caller using
Prefer: respond-async, which receives202immediately, why a message never went out. See Errors.
Numbers
Related resource Numbers
session.status
Session status change.
status
statusstringrequiredSession status: CONNECTING, CONNECTED, DISCONNECTED
statusReasonstringReason for the status: SCAN_QR, AUTO_RECONNECT, FAILED, MANUAL_STOP, QR_TIMEOUT, LOGGED_OUT, TEMPORARY_BAN, STREAM_ERROR
banCodeintegermin0WhatsApp temporary-ban code (present only when statusReason is TEMPORARY_BAN).
banReasonstringHuman-readable label for the ban code (present only when statusReason is TEMPORARY_BAN).
banExpiresAtintegerformatint64Unix timestamp in seconds when the temporary ban lifts, when WhatsApp provides a duration.
detailstringExtra context for FAILED and STREAM_ERROR statuses (for example the connect-failure reason).
CloudAccountStatusPayload
sourcestringrequiredAlways
meta: a WhatsApp Business Account notification, not a connection-state changeAllowed valuesmetakindstringrequiredWhatsApp notification field that produced the event
Allowed valuesaccount_alertsaccount_updatephone_number_name_updatewabaIdstringWhatsApp Business Account id the notification belongs to
valueobjectrequiredThe notification's
valueobject exactly as WhatsApp sent it; its fields vary by notification
Example payload{ "status": "DISCONNECTED" }With
statusReason: "TEMPORARY_BAN"the payload also carriesbanCode,banReason, andbanExpiresAt.banExpiresAtis a Unix timestamp in seconds and is present only when WhatsApp gives a duration.detailcarries extra context forFAILEDandSTREAM_ERROR.WhatsApp Business Account notifications (
account_alertsandaccount_update) arrive assession.statuswithsource: "meta",kind,wabaId, andvalue, the notification'svalueobject exactly as WhatsApp sent it. A display-name review notification uses the same event withkind: "phone_number_name_update". Itsvalueincludesdisplay_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 nostatusfield, so checksourcebefore readingstatus. Aformat: "meta"webhook receives each notification on its original field. It does not receive connection-statesession.statusevents.session.connected
Session connected to WhatsApp.
phoneNumberstringrequiredPhone number in international format.
idstringPolymorfa ID of the connected account.
pushNamestringrequiredWhatsApp display name reported by the sender's client.
phonePlatformstringrequiredWhere 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.
accountTypestringrequiredHow 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.
businessNamestringBusiness name shown to the customer.
Example payload{ "phoneNumber": "string", "pushName": "string", "phonePlatform": "android", "accountType": "whatsapp_app" }session.logged_out
Session logged out.
reasonstringrequiredWhy the session was logged out:
bannedwhen WhatsApp banned the account,device_removedwhen the linked device was removed from the phone or from another device,unknownotherwise (including a locked account).Allowed valuesbanneddevice_removedunknowncodeintegerrequiredWhatsApp's logout code: 401 (removed), 403 (locked) or 406 (banned); 0 when WhatsApp gave none.
Example payload{ "reason": "device_removed", "code": 401 }reasonsays 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)codeis WhatsApp's own logout code, or0when it gave none. Reconnect adevice_removednumber by pairing it again; abannednumber needs a new number.Code
403arrives asunknownbecause 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.
daysSinceLastSeennumberrequiredWhole days since the phone was last seen online.
daysRemainingnumberrequiredDays remaining before WhatsApp disconnects the session (clamped to 0). WhatsApp typically severs the companion link after ~14 days of phone inactivity.
lastSeenstringrequiredISO 8601 timestamp of the last time the phone was seen online.
actionstringrequiredHuman-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 length256Identifier of the connected Polymorfa session.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
statusstringrequiredCurrent status of this resource or operation.
Allowed valuessyncedunknownsyncedAtstringrequirednullableformatdate-timeTimestamp for synced at.
checkedAtstringrequirednullableformatdate-timeTimestamp for checked at.
accountTypestringrequirednullableCategory assigned to account.
Allowed valuesbusinesspersonalcapabilitiesarray of objectrequiredmax items100Capabilities associated with this native session capabilities updated payload.
Show 5 child fields
changedKeysarray of stringrequiredmax items100item max length128Changed 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.
changedKeyslists 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.
typestringrequiredThe restriction.
reachout_timelock: the number can only message or call people it has already chatted with.Allowed valuesreachout_timelockactivebooleanrequiredTrue while the restriction applies.
enforcementTypestringrequirednullableWhatsApp's category for the restriction; null when inactive or not reported.
expiresAtstringrequirednullableWhen the restriction ends (ISO 8601); null when inactive or WhatsApp gave no end.
observedAtstringrequiredWhen 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.Field Meaning typereachout_timelockactivetruewhile the restriction applies,falsewhen it endsenforcementTypeWhatsApp's category for the restriction, such as DEFAULT;nullwhen inactive or not reportedexpiresAtWhen the restriction ends (ISO 8601); nullwhen inactive or WhatsApp gave no endobservedAtWhen 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.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
archivebooleanWhether archive.
pinnedbooleanWhether pinned.
Example payload{ "from": { "id": "739182640518203" } }chat.mute
Chat muted or unmuted.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
mutedbooleanrequiredWhether notifications are muted.
muteEndTimestampnumberUnix timestamp in seconds when the chat mute expires.
Example payload{ "from": { "id": "739182640518203" }, "muted": true }chat.read
Chat marked read or unread.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
readbooleanrequiredWhether read.
Example payload{ "from": { "id": "739182640518203" }, "read": true }chat.clear
Chat cleared.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
Example payload{ "from": { "id": "739182640518203" } }chat.delete
Chat deleted.
fromobjectrequiredStable 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.
idstringrequiredIdentifier for this resource.
newSubjectstringSpecifies new subject for this native group update payload.
newDescriptionstringSpecifies new description for this native group update payload.
actionstringWhat changed, for example
joinedwhen the Number joins a group with an invite link.
Example payload{ "id": "string" }group.participant
Group participants added/removed/promoted/demoted.
idstringrequiredIdentifier for this resource.
joinedarray of objectJoined associated with this native group participant payload.
Show 5 child fields
leftarray of objectLeft associated with this native group participant payload.
Show 5 child fields
promotedarray of objectPromoted associated with this native group participant payload.
Show 5 child fields
demotedarray of objectDemoted associated with this native group participant payload.
Show 5 child fields
Example payload{ "id": "string" }presence.update
User or chat presence change.
observedAtintegerrequiredUnix timestamp in seconds when Polymorfa observed this state.
fromobjectStable identifier for the conversation or account that originated the event.
Show 5 child fields
senderobjectStable identifier for the user who sent the message or event.
Show 5 child fields
statestringComposing activity observed for the contact, such as composing or paused.
mediastringChat presence media category reported while composing or recording, such as audio.
unavailablebooleanWhether the observed contact is unavailable according to this presence update.
lastSeennumberUnix 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
eventsorcache. ItsobservedAtfield 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.
bsuidstringBusiness-scoped user identifier (BSUID), scoped to the owning business portfolio.
phoneNumberstringPhone number in international format.
usernamestringWhatsApp username when one is available.
parentBsuidstringParent 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; useidorbsuid.identityChangeobjectSpecifies identity change for this native contact update payload.
Show 3 child fields
fullNamestringHuman-readable full name for this native contact update payload.
firstNamestringHuman-readable first name for this native contact update payload.
pushNamestringWhatsApp display name reported by the sender's client.
oldPushNamestringHuman-readable old push name for this native contact update payload.
businessNamestringBusiness name shown to the customer.
oldBusinessNamestringHuman-readable old business name for this native contact update payload.
pictureIdstringIdentifier for the picture.
pictureRemovedbooleanWhether picture removed.
Example payload{ "id": "739182640518203" }Identity-change notifications become native
contact.updateevents withidentityChange, or Meta-formatmessageswithtype: "system"andsystem.type: "user_changed_number"or"user_changed_user_id". Subscribe tomessagesat Meta;user_id_updateis not a subscribable webhook field. See User identities.contact.opted_out
A contact opted out of campaigns by replying with an opt-out keyword.
phonestringrequiredContact phone number in E.164 format
sourcestringrequiredHow the suppression list changed. Keyword replies always report
stop-keyword.Allowed valuesstop-keywordkeywordstringrequiredThe configured keyword the reply matched, in upper case. The message itself is never included.
sessionstringrequiredSession name of the number that received the reply
projectIdstringProject 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_inreports the reverse.Field Meaning phoneThe contact's number in E.164 format sourceAlways stop-keyword; these events report keyword replies onlykeywordThe 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.
phonestringrequiredContact phone number in E.164 format
sourcestringrequiredHow the suppression list changed. Keyword replies always report
stop-keyword.Allowed valuesstop-keywordkeywordstringrequiredThe configured keyword the reply matched, in upper case. The message itself is never included.
sessionstringrequiredSession name of the number that received the reply
projectIdstringProject that owns the receiving number, when known
Example payload{ "phone": "+14155550123", "source": "stop-keyword", "keyword": "STOP", "session": "sales-1" }Carries the same fields as
contact.opted_out.blocklist.update
Blocklist changed.
actionstringrequiredAction represented by this native blocklist update payload.
changesarray of objectrequiredChanges 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.
actionstringrequiredAction: label_edit, label_association_chat, label_association_message, star
labelIdstringLabel ID affected by the action
fromobjectStable identifier for the conversation or account that originated the event.
Show 5 child fields
labelstringLegacy field: the label's display name for label_edit, and the label ID for association actions. Prefer labelId and name.
namestringLabel display name (present for label_edit)
colorintegerformatint32Label color index (present for label_edit)
orderIndexintegerformatint32Label ordering index when supplied by app state
deletedbooleanWhether the label definition was deleted
labeledbooleanWhether the chat or message association is active
observedAtintegerformatint64Unix 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)
starredbooleanWhether the message is starred (present for star actions)
Example payload{ "action": "label_edit" }actionidentifies the change. Alabel_editpayload includeslabelId,observedAt, and the observed definition fieldsname,color,orderIndex, anddeleted. Chat-association changes includefrom,labelId,labeled, andobservedAt. Star changes includefrom,messageId, andstarred. 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.
idstringrequiredIdentifier for this resource.
shortcutstringrequiredSpecifies shortcut for this native business quick reply update payload.
messagestringrequiredMessage content carried by the updated business quick reply.
keywordsarray of stringrequiredKeywords associated with this native business quick reply update payload.
countintegerrequiredmin0Usage count recorded for this business quick reply.
deletedbooleanrequiredWhether deleted.
associatedLabelIdsarray of stringrequiredAssociated label ids associated with this native business quick reply update payload.
observedAtintegerrequiredUnix timestamp in seconds when Polymorfa observed this state.
fromFullSyncbooleanrequiredWhether 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
eventsmode retains no content. Projects that selectcachecan read a bounded in-memory projection;offsuppresses the webhook and clears that projection. See Quick-reply observation.contact.sync
WhatsApp Business app contact synchronization.
kindstringrequiredKind discriminator for this object.
Allowed valuescontactsvalueobjectrequiredValue 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.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
callIdstringrequiredIdentifier of the WhatsApp call.
hasVideobooleanrequiredWhether the offered call advertised video.
sessionConnectionstringConnection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.
Allowed valueslinked_devicecloud_apicapabilitiesobjectWhat the call supports.
Show 2 child fields
Example payload{ "from": { "id": "739182640518203" }, "callId": "string", "hasVideo": false }call.missed
Call missed.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
callIdstringrequiredIdentifier of the WhatsApp call.
reasonstringrequiredReason for the reported state or outcome.
Example payload{ "from": { "id": "739182640518203" }, "callId": "string", "reason": "string" }call.accepted
Call accepted.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
callIdstringrequiredIdentifier of the WhatsApp call.
answeredBystringParticipant reference that answered or placed the call:
client:<id>orserver:<id>.exclusivebooleanPresent and
truewhen the answering participant claimed the call.sessionConnectionstringConnection of the session that carries the call: a linked device or the WhatsApp Business Cloud API.
Allowed valueslinked_devicecloud_apicapabilitiesobjectWhat the call supports.
Show 2 child fields
Example payload{ "from": { "id": "739182640518203" }, "callId": "string" }call.rejected
Call rejected.
fromobjectrequiredStable identifier for the conversation or account that originated the event.
Show 5 child fields
callIdstringrequiredIdentifier of the WhatsApp call.
Example payload{ "from": { "id": "739182640518203" }, "callId": "string" }call.ended
Call ended.
fromobjectrequirednullableStable identifier for the conversation or account that originated the event.
Show 5 child fields
callIdstringrequiredIdentifier of the WhatsApp call.
durationSecondsintegerrequiredTotal connected duration in seconds (0 if never answered).
reasonstringrequiredTermination 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).
directionstringrequiredCall direction.
Allowed valuesinboundoutboundhadVideobooleanrequiredWhether the call carried video.
sessionConnectionstringConnection 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.
callIdstringrequiredIdentifier of the WhatsApp call.
setupMsintegerrequiredTime from offer to media_ready, in milliseconds.
ringMsintegerrequiredTime spent ringing before accept, in milliseconds.
durationSecondsintegerrequiredTotal connected duration in seconds.
terminateReasonstringrequiredTermination reason: user_hangup | timeout | lost_connection | rejected | capacity.
codecstringrequiredNegotiated audio codec's bare subtype; empty when the audio stream does not identify its codec.
jitterMsnumberrequiredInbound RTP jitter for the audio stream, in milliseconds.
packetsLostintegerrequiredCumulative inbound RTP packets lost for the audio stream.
rttMsnumberrequiredEstimated round-trip time from the remote-inbound report, in milliseconds.
recvKbpsnumberrequiredTotal inbound volume across all RTP streams, in kilobits (cumulative).
sendKbpsnumberrequiredTotal 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.
callIdstringrequiredIdentifier of the WhatsApp call.
participantobjectrequiredSpecifies 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.
callIdstringrequiredIdentifier of the WhatsApp call.
participantobjectrequiredSpecifies 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.
callIdstringrequiredIdentifier of the WhatsApp call.
participantIdstringrequiredIdentifier for the participant.
reasonstringReason for the reported state or outcome.
Example payload{ "callId": "string", "participantId": "string" }call.connection_joined
Connection joined a call.
callIdstringrequiredIdentifier of the WhatsApp call.
connectionobjectrequiredSpecifies 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.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 4 child fields
statusstringrequiredtemporary: granted untilexpiresAt.permanent: granted without expiry.revoked: declined or withdrawn.none: no permission.Allowed valuesnonetemporarypermanentrevokedpreviousStatusstringrequiredSpecifies previous status for this native call permission changed payload.
Allowed valuesnonetemporarypermanentrevokedexpiresAtstringrequirednullableformatdate-timeWhen a temporary permission ends; null otherwise. No event is sent when it ends.
sourcestringrequireduser_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_refusedchangedAtstring (date-time)requiredTimestamp 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.
callIdstringrequiredIdentifier 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 orserver:<id>for a server credential.reasonstringrequiredleft: the connection left.replaced: a reconnect reused the connection id.claimed: another participant claimed the call.sip_busy,sip_declined,sip_no_answer,sip_unavailableandsip_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 thesip_*reasons, orcall_endedwhile it was still ringing) reports onlycall.connection_left, with nocall.connection_joinedbefore it. Connections still open when the call ends are closed bycall.endedwithout 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_readandcampaign.recipient_repliedrequire 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_openedrequires 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.
campaignIdstringrequiredCampaign id
sentCountintegerrequiredmin0Recipients sent so far
remainingCountintegerrequiredmin0Recipients still queued
pausedAtintegerrequiredmin0Unix timestamp in seconds when the campaign paused
reasonstringWhy Polymorfa paused the campaign. Present only on an automatic pause.
codestringStable 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 }reasonandcodeare 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.
campaignIdstringrequiredCampaign id
namestringrequiredHuman-readable name for this resource.
recipientCountintegerrequiredmin0Number of recipients.
scheduledbooleanrequiredWhether scheduled.
launchedAtintegerrequiredmin0Unix timestamp in milliseconds when sending began
Example payload{ "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11", "name": "string", "recipientCount": 0, "scheduled": true, "launchedAt": 0 }launchedAtuses Unix milliseconds.campaign.resumed
Campaign resumed sending.
campaignIdstringrequiredCampaign id
sentCountintegerrequiredmin0Number of sents.
remainingCountintegerrequiredmin0Number of remainings.
resumedAtintegerrequiredmin0Unix 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.
resumedAtuses Unix milliseconds.campaign.stopped
Campaign stop settled.
campaignIdstringrequiredCampaign id
sentCountintegerrequiredmin0Number of sents.
abandonedCountintegerrequiredmin0Number of abandoneds.
stoppedAtintegerrequiredmin0Unix 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.
abandonedCountcounts queued recipients skipped by cancellation; sends already in flight are excluded and may settle later.stoppedAtuses Unix milliseconds.campaign.rescheduled
A scheduled campaign's start time moved.
campaignIdstringrequiredCampaign id
previousScheduledAtintegerrequirednullablemin0The start time that was replaced, in Unix milliseconds
scheduledAtintegerrequiredmin0The new start time in Unix milliseconds. Equal to
rescheduledAtwhen the campaign was asked to start now.rescheduledAtintegerrequiredmin0Unix 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.
previousScheduledAtis the replaced start andscheduledAtthe new one; both use Unix milliseconds. For a request to start now,scheduledAtequalsrescheduledAt.campaign.completed
Campaign finished sending.
campaignIdstringrequiredCampaign id
sentCountintegerrequiredmin0Number of sents.
deliveredCountintegerrequiredmin0Number of delivereds.
readCountintegerrequiredmin0Number of reads.
failedCountintegerrequiredmin0Number of faileds.
skippedCountintegerrequiredmin0Number of skippeds.
responseCountintegerrequiredmin0Number of responses.
completedAtintegerrequiredmin0Unix timestamp in seconds when the last recipient settled
durationMsintegerrequiredmin0Wall-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.
campaignIdstringrequiredCampaign id
reasonstringrequiredStable reason the campaign failed
failedAtintegerrequiredmin0Unix 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.
reasonisall_recipients_failed.campaign.recipient_sent
A campaign recipient was sent.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
sessionKeystringrequiredSending number's session key
externalMessageIdstringrequiredWhatsApp message id of the delivered send
variantKeystringrequiredContent variant used for this recipient
attemptintegerrequiredgreater than0Attempt number that succeeded
messageIndexintegermin0Position 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;
messageIndexis its position, from0. MatchexternalMessageIdagainst latermessage.ackevents for delivery and read receipts.campaign.recipient_delivered
A campaign recipient's first delivery receipt.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
sessionKeystringrequiredSending number's session key
externalMessageIdstringrequiredmin length1WhatsApp message id of the campaign send
deliveredAtintegerrequiredmin0Unix 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.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
sessionKeystringrequiredSending number's session key
externalMessageIdstringrequiredmin length1WhatsApp message id of the campaign send
readAtintegerrequiredmin0Unix 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.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
sessionKeystringrequiredSending number's session key
externalMessageIdstringrequirednullablemin length1WhatsApp message id of the campaign send, or null when unavailable
repliedAtintegerrequiredmin0Unix timestamp in seconds of the first attributed reply
responseMsintegerrequiredmin0Milliseconds 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_link_opened
A campaign recipient's first open of a tracked link.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
linkKeystringrequiredpattern^[a-z0-9_]{1,32}$Key of the tracked link that was opened
openedAtintegerrequiredmin0Unix timestamp in seconds of the recipient's first open of this link
Example payload{ "campaignId": "01936b2e-5f2a-7c1d-9a3e-8b4c2d1e0f11", "recipientId": "01936b2e-6a11-7d2e-8f4a-1c2b3d4e5f66", "linkKey": "offer", "openedAt": 1757161200 }The first open of a tracked link by a recipient.
openedAtuses Unix seconds. An open can come from a link preview or security scanner, so it is not proof of a click. It carries no phone number, link, destination, IP address, or user agent. Each recipient produces at most one event per tracked link.campaign.recipient_failed
A campaign recipient failed after its last attempt.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
attemptsintegerrequiredmin0Attempts made before giving up
errorstringrequiredSanitized failure class or stable code
failedAtintegerrequiredmin0Unix timestamp in seconds when the recipient was marked failed
messageIndexintegermin0Position 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
messageIndexis above0, the earlier messages were sent, the recipient stayssent, and its remaining messages are not sent.campaign.recipient_skipped
A campaign recipient was skipped.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
reasonstringrequiredStable 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
messageIndexintegermin0Position 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.
skippedAtintegerrequiredmin0Unix 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 (
reasonoptout) or a variable with no value and no fallback (reasonmissing_variable).whatsapp_marketing_limitis reported by WhatsApp after it accepted the send and withheld a marketing message because the person reached their marketing message limit; that recipient moves fromsenttoskipped, and the event arrives with an emptysession.campaign.throttled
Campaign sending was paced.
campaignIdstringrequiredCampaign id
sessionKeystringrequiredSending number's session key
reasonstringrequiredWhy sending was paced:
paced,bansafe_throttled,daily_allowance_reached, ornew_chat_limit_reached(WhatsApp capped this number's new chats for the current cycle)deferredCountintegerrequiredmin0Recipients deferred in this pass
atintegerrequiredmin0Unix 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.
reasonnames what held the pass back.pacedmeans no number in the campaign's own pool could send this pass. Once automatic restrictions are enabled,bansafe_throttledmeans a restriction on the sending Number paced it.new_chat_limit_reachedmeans 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, andfailedCountdoes not move. See Campaigns and number safety.campaign.cap_reached
A sending number reached its hourly or daily cap.
campaignIdstringrequiredCampaign id
sessionKeystringrequiredSending number's session key
phonestringrequiredSending number in E.164
capTypestringrequiredWhich cap was reached:
hourlyordaily(the campaign's own caps), ornew_chat(WhatsApp's per-number new-chat cap)capLimitintegerrequiredmin0The cap that was reached. For
new_chat, the quota WhatsApp reportedwindowResetsAtintegerrequiredmin0Unix 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 cycleatintegerrequiredmin0Unix 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 (
capTypenew_chat), and left the pool for that window.campaign.cold_blocked
A campaign recipient was held because they never wrote first.
campaignIdstringrequiredCampaign id
recipientIdstringrequiredCampaign recipient id
phonestringrequiredRecipient phone number in E.164
surfacestringrequiredCampaign surface
reasonstringrequiredStable hold reason
atintegerrequiredmin0Unix 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 leavesfailedCountat zero. To message them anyway, setsenderConfig.throughput.coldSendPolicytoallow. See Campaigns and BanSafe.
Customers
Related resource Customers
Customer events go to team webhooks.
customer.enabled
Customers enabled for a project.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemmigratedNumberCountintegerrequiredmin0Number 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemfieldsarray of stringrequireditems1–3Fields 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemblockingNumberCountintegerrequiredmin0Number of blocking numbers.
revokedPairingLinkCountintegerrequiredmin0Number 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory 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.pairing_link.created
Customer pairing link created.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier 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", "pairingLinkId": "00000000-0000-4000-8000-000000000000" }customer.pairing_link.opened
Customer pairing link opened.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier 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", "pairingLinkId": "00000000-0000-4000-8000-000000000000" }customer.pairing_link.connected
Customer pairing link connected.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier for the pairing link.
sessionIdstring (uuid)requiredIdentifier of the connected Polymorfa session.
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", "pairingLinkId": "00000000-0000-4000-8000-000000000000", "sessionId": "00000000-0000-4000-8000-000000000000" }customer.pairing_link.failed
Customer pairing attempt failed.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier for the pairing link.
errorCodestringrequiredpattern^[a-z0-9_]{1,64}$Machine-readable error code for this native customer pairing link failed payload.
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", "pairingLinkId": "00000000-0000-4000-8000-000000000000", "errorCode": "string" }customer.pairing_link.expired
Customer pairing link expired.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier 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", "pairingLinkId": "00000000-0000-4000-8000-000000000000" }customer.pairing_link.revoked
Customer pairing link revoked.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystempairingLinkIdstring (uuid)requiredIdentifier for the pairing link.
reasonstringReason for the reported state or outcome.
Allowed valuescustomer_archivedphone_mismatch_limitexchange_failure_limitterminal_failure
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", "pairingLinkId": "00000000-0000-4000-8000-000000000000" }customer.number.attached
Number attached to a Customer.
eventIdstring (uuid)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemsessionIdstring (uuid)requiredIdentifier 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemsessionIdstring (uuid)requiredIdentifier of the connected Polymorfa session.
sourceCustomerIdstring (uuid)requiredIdentifier 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)requiredIdentifier for the event.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
customerIdstring (uuid)requiredIdentifier for the customer.
actorKindstringrequiredCategory assigned to actor.
Allowed valuesbetter_authteam_keyproject_tokencli_grantsystemsessionIdstring (uuid)requiredIdentifier 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.
actionstringrequiredWhether the restriction was newly applied, moved, or removed.
daily_allowance_reachedreports 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_reachedscopestringrequiredWhether this covers one number or every number in the workspace.
Allowed valuesnumberteamrungstringrequiredRestriction now in force.
Allowed valuesnonenotifythrottleblock_coldsuspendpreviousRungstringrequirednullableRestriction previously in force, or null when none was.
Allowed valuesnonenotifythrottleblock_coldsuspendreasonstringrequiredWhy the restriction changed.
Allowed valueshealthfindingteam_patternrepeatrestrictionoperatorhealth_model_cutoverwarmuphealthintegerrequirednullablerange0–100Measured health from 0 (worst) to 100 (best), or null when not measured.
healthBandstringrequiredHealth band matching health.
Allowed valuesgoodfairpoorfailingunknownrequiresarray of objectrequiredmax items25Findings that must resolve before this restriction lifts.
Show 3 child fields
throughputPerMinuteintegerrequirednullablerange0–10000Messages per minute allowed while paced, or null when not paced.
eligibleLiftAtstringrequirednullableformatdate-timeEarliest instant the restriction can step down, ISO 8601.
liftRequiresstringrequiredlength1–240One sentence describing what lifts the restriction.
appealUrlstring (uri)requiredmax length500Where to appeal this action.
startedAtstring (date-time)requiredISO 8601 timestamp when this restriction took effect.
docsstring (uri)requiredmax length500Documentation 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"andreason: "warmup"; its rung does not change andeligibleLiftAtgives the next reset.bansafe.health_threshold
A project's present Health rule crossed below its threshold.
sessionIdstring (uuid)requiredSession whose present Health crossed the project threshold.
projectIdstring (uuid)requiredProject whose Health rule produced this action.
healthnumberrequiredrange0–100Present Health; higher is healthier.
thresholdintegerrequiredrange0–100Configured project threshold crossed by this evaluation.
healthSourcestringrequiredEstimator family used by the evaluation.
Allowed valuesrules_v1ml_modelestimatorVersionstringrequiredlength1–128Estimator version used by the evaluation.
modelVersionstringrequirednullablelength1–128Learned-model version, or null for a rules-based estimate.
evaluatedAtstring (date-time)requiredEvaluation time in ISO 8601 format.
policyVersionintegerrequiredrange1–9007199254740991Project Health rule version evaluated.
episodeIdstring (uuid)requiredStable below-threshold episode identifier.
actionIdstring (uuid)requiredStable 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
modelVersionto null. The eventidis 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.
idstringrequiredIncident 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.
kindstringrequiredWhat WhatsApp did, or customer_report when you reported it.
Allowed valuescap_warningcap_reachedtimelocktemporary_banpermanent_banconnect_blockedcustomer_reportsourcestringrequiredWhether Polymorfa observed it or you reported it.
Allowed valuesruntimecustomerstartedAtstring (date-time)requiredISO 8601 timestamp when the restriction started.
endsAtstringrequirednullableformatdate-timeISO 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–1How 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.
resolutionstringrequiredHow 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_switchfinalclaimIdstringrequirednullableThe Ban Credit claim this incident belongs to, or null when there is none.
closedAtstringrequirednullableformatdate-timeISO 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;
kindandsourcesay what happened and who observed it.bansafe.claim
A Ban Credit claim was filed on a ban, decided, paid, or reversed.
idstringrequiredClaim id. Stable and quotable.
incidentIdstringrequiredThe incident this claim was filed against.
phoneNumberstringrequiredpattern^\+[1-9]\d{1,14}$The customer's own number in E.164 format.
statusstringrequiredWhere 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_reviewapproveddeniedpaidreversedverdictstringrequiredWhat 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_interactivewindowStartstring (date-time)requiredISO 8601 start of the 30 days the refund covers.
windowEndstring (date-time)requiredISO 8601 end of the window: the moment the ban started.
measuredCentsnumberrequiredmin0multiple of0.000001Credit quantity this number consumed inside the window, with up to six decimal places.
capCentsnumberrequiredmin0multiple of0.000001Maximum credit quantity this claim can return, with up to six decimal places.
amountCentsnumberrequiredmin0multiple of0.000001Credit quantity this claim returns, with up to six decimal places.
summarystringrequiredOne sentence describing the claim's state.
reasonstringrequiredOne sentence describing what the ban was attributed to.
decidedAtstringrequirednullableformatdate-timeISO 8601 timestamp of the decision, or null while none was taken.
paidAtstringrequirednullableformatdate-timeISO 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
templateNamestringrequiredTemplate name as registered with Meta
templateIdstringrequiredMeta template id
statusstringrequiredNew approval status: APPROVED, REJECTED, PAUSED, DISABLED, DELETED
categorystringrequiredTemplate category (MARKETING, UTILITY, AUTHENTICATION)
reasonstringrequiredReason for the status change; empty unless REJECTED, PAUSED or DISABLED
qualityRatingstringrequiredQuality rating bucket reported by Meta (GREEN, YELLOW, RED)
kind
kindstringrequiredmessage_template_status_updatefor an approval change,message_template_quality_updatefor a quality changeAllowed valuesmessage_template_status_updatemessage_template_quality_updateeventstringNew template status reported by WhatsApp; for a quality change, the new quality score
templateIdstringWhatsApp template id
templateNamestringTemplate name
languagestringTemplate language code
reasonstringWhatsApp's explanation for the change, when supplied
previousQualityScorestringQuality score before a quality change
newQualityScorestringQuality score after a quality change
wabaIdstringWhatsApp 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.
kindismessage_template_status_updatefor an approval change andmessage_template_quality_updatefor a quality change.eventcarries the new status andreasoncarries WhatsApp's explanation when it gives one. A quality change carriespreviousQualityScoreandnewQualityScore, and itseventis the new quality score.templateId(a string),templateName,language, andwabaIdidentify the template and the WhatsApp Business Account that owns it. Onlykindis 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)requiredStable event ID for receiver idempotency.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
assetIdstring (uuid)requiredIdentifier for the asset.
namestringrequiredHuman-readable name for this resource.
sourcestringrequireduploadortts. Treat unknown values asupload.Allowed valuesuploadttsdurationMsintegerrequiredgreater than0Specifies 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.
originalFormatstringrequiredSpecifies 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)requiredStable event ID for receiver idempotency.
occurredAtstring (date-time)requiredTimestamp for occurred at.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
assetIdstring (uuid)requiredIdentifier for the asset.
namestringrequiredHuman-readable name for this resource.
sourcestringrequireduploadortts. Treat unknown values asupload.Allowed valuesuploadttsfailureReasonstringrequiredTreat 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)requiredUsage record id. Stable across revisions.
meterstringrequiredWhat was measured. Calls produce
call.duration, and outgoing Cloud API calls alsocall.cloud_pulses.Allowed valuescall.durationcall.cloud_pulsescampaign.calltts.characterstts.secondsstt.secondsagent.secondsagent.tokensagent.provider_costchannels.peakstorage.byte_daysquantitynumberrequiredmin0Measured amount in
unit.unitstringrequiredSpecifies unit for this native usage recorded payload.
Allowed valuessecondpulsecallcharactertokenprovider_unitchannelbyte_daydimensionsobjectrequiredClosed, per-meter attributes. Call meters carry
direction,upstream(linked_deviceorcloud_api),origin,participants,connections,sipLegsandvideo.keySourcestringrequiredWhose provider key produced the usage.
nonefor calls.Allowed valuesnonemanagedcustomersourceKindstringrequiredCategory assigned to source.
Allowed valuescallattemptflow_runconversationassetteamsourceIdstringrequiredThe call id for call meters.
projectIdstringrequirednullableformatuuidIdentifier of the Polymorfa project that owns this resource.
sessionstringrequirednullableThe number (session name) the usage belongs to.
occurredAtstring (date-time)requiredWhen the usage happened. For calls, when the call ended.
recordedAtstring (date-time)requiredTimestamp for recorded at.
revisionintegerrequiredmin1Starts at 1. A higher revision of the same
idreplaces the earlier one.pricingStatestringrequiredunpricedwhile usage is measured but not charged.Allowed valuesunpricedpricedwaivedsettledrateCardobjectrequirednullableStructured rate card values for this native usage recorded payload.
Show 2 child fields
pricedCreditsnumberrequirednullableSpecifies 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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
original_whatsapp_idsobjectSpecifies original whatsapp ids for this native linked history sync payload.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
original_whatsapp_idstringdeprecatedlength1–512Temporary singular original provider reference for older consumers. Use original_whatsapp_ids for transport-specific references.
messagesarray of objectrequiredMessages associated with this native linked history sync payload.
Show 5 child fields
modestringrequiredOperating mode selected for this feature.
Allowed valuesdeliversyncTypestringrequiredCategory assigned to sync.
chunkOrderintegermin0Specifies chunk order for this native linked history sync payload.
progressintegerrange0–100Specifies progress for this native linked history sync payload.
fileLengthintegerrequiredmin0Size of the media file in bytes.
conversationCountintegerrequiredmin0Number of conversations.
messageCountintegerrequiredmin0Number of messages.
pushNameCountintegerrequiredmin0Number of push names.
statusMessageCountintegerrequiredmin0Number of status messages.
whatsappobjectrequiredUnmodified provider archive. Its protobuf retains provider addresses; use messages for Polymorfa identities.
Show 2 child fields
media
deliverystringrequiredSpecifies delivery for this any of.
Allowed valuesdescriptorwhatsapp_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
original_whatsapp_idsobjectSpecifies original whatsapp ids for this any of.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
original_whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
syncTypestringrequiredmin length1Category assigned to sync.
chunkOrderintegermin0Specifies chunk order for this any of.
progressintegerrange0–100Specifies progress for this any of.
fileLengthintegerrequiredmin0Size of the media file in bytes.
oldestMessageAtstring (date-time)Timestamp for oldest message at.
peerDataRequestSessionIdstringIdentifier for the peer data request session.
mediaobjectrequiredReference to the media attached to this message.
Show 6 child fields
inline
deliverystringrequiredSpecifies delivery for this any of.
Allowed valuesdescriptorwhatsapp_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
original_whatsapp_idsobjectSpecifies original whatsapp ids for this any of.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
original_whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
syncTypestringrequiredmin length1Category assigned to sync.
chunkOrderintegermin0Specifies chunk order for this any of.
progressintegerrange0–100Specifies progress for this any of.
fileLengthintegerrequiredmin0Size of the media file in bytes.
oldestMessageAtstring (date-time)Timestamp for oldest message at.
peerDataRequestSessionIdstringIdentifier for the peer data request session.
inlineobjectrequiredStructured inline values for this any of.
Show 2 child fields
CloudHistorySyncPayload
kindstringrequiredKind discriminator for this object.
Allowed valueshistoryvalueobjectrequiredValue 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.
requestIdstringrequiredIdentifier used to correlate this request across systems.
commandstringrequiredSpecifies command for this native command result payload.
successbooleanrequiredWhether the request succeeded.
dataobjectStructured data carried by this object.
errorstringError details returned when the operation fails.
Example payload{ "requestId": "string", "command": "string", "success": true }