Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
WhatsApp

Send WhatsApp conversion event

Forward a WhatsApp Business Messaging conversion event (LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent) to Meta's Conversions API with action_source = business_messaging and messaging_channel = whatsapp. The endpoint looks up the originating CTWA click ID (ctwa_clid) captured on the first inbound message of the conversation and replays it on every event so Meta can attribute the conversion back to the Click-to-WhatsApp ad that drove the chat.

Configuration prerequisite on the WhatsApp account metadata:

  • metaCapiDatasetId: the Meta dataset ID linked to the WABA. Provision one with POST /v1/whatsapp/dataset.

The WABA ID (already set automatically at connect time) is forwarded as user_data.whatsapp_business_account_id, which is the per-channel attribution identifier Meta requires for WhatsApp events. No Facebook Page ID is needed (that field is the Messenger-branch identifier).

Identify the conversation by either conversationId (preferred) or phoneE164 (digits only, no +). At least one is required. If the conversation has no captured ctwa_clid, the request returns 422 because there is nothing to attribute.

Token and dataset coupling: the WhatsApp account's accessToken must have access to the configured metaCapiDatasetId. By default a WABA's system-user token is scoped to the WABA's own Business Manager and cannot post to a pixel owned by a different Business; Meta returns code 100 in that case. Either share the dataset with the WhatsApp app's Business in BM, or use a dataset already in the same Business as the WABA.

post/v1/whatsapp/conversions

Request body

accountIdstring required

WhatsApp SocialAccount ID.

eventName'LeadSubmitted' | 'Purchase' | 'AddToCart' | 'InitiateCheckout' | 'ViewContent' required

Live-verified allowlist of event names accepted by Meta's CAPI for Business Messaging (Graph API v25.0). Other standard pixel events including Lead, CompleteRegistration, Subscribe, Schedule, Contact, StartTrial, AddPaymentInfo, Search, and SubmitApplication are rejected with subcode 2804066 ("Messaging Event Invalid Event Type") on action_source = business_messaging events. Custom event names are also rejected.

Use LeadSubmitted (NOT Lead) for lead-style conversions.

eventTimenumber

Unix seconds. Defaults to the time of the request when omitted. Meta's attribution window is 7 days from click; events older than that lose attribution.

eventIdstring required

Stable dedup key. Reuse to suppress duplicate events (Meta dedupes against pixel events with the same id).

conversationIdstring

Zernio Conversation _id (preferred lookup). The conversation must have a captured ctwa_clid in metadata (set automatically by the WhatsApp webhook on the first inbound message after a CTWA ad click).

phoneE164string

Contact phone number, digits only with no '+'. When used in lieu of conversationId, the handler resolves to the most recent CTWA-attributed conversation for this phone on the supplied account.

valuenumber

Conversion value (e.g. order total).

currencystring

ISO 4217 currency code (e.g. USD).

contentIdsstring[]

Optional product / content identifiers.

emailstring email

User email. Normalized + SHA-256 hashed before sending to Meta.

externalIdstring

Stable customer identifier. Lowercased + SHA-256 hashed before sending to Meta.

testCodestring

Meta test_event_code passthrough. Routes the event to the Test Events tab in Events Manager instead of the production dataset, useful for development.

Response

Event submitted to Meta. Inspect eventsFailed and failures[] to detect partial failures. A 200 does not mean Meta accepted the event; the status reflects "request reached Meta" only.

platform'metaads'
eventsReceivedinteger

Events accepted by Meta.

eventsFailedinteger

Events rejected by Meta (see failures).

traceIdstring

Meta fbtrace_id for debugging. Surface in support tickets.