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 prerequisites on the WhatsApp account metadata:

• metaCapiDatasetId: the Meta Pixel/Dataset ID linked to the WABA.
• connectedFacebookPageId: the Facebook Page paired with the WhatsApp Business number.

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

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 prerequisites on the WhatsApp account metadata:

• metaCapiDatasetId: the Meta Pixel/Dataset ID linked to the WABA.
• connectedFacebookPageId: the Facebook Page paired with the WhatsApp Business number.

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.

Request body

Content-Type: application/json

• accountId (string) required — WhatsApp SocialAccount ID.
• eventName (string) required (enum: LeadSubmitted, Purchase, AddToCart, InitiateCheckout, ViewContent) — 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,...
• eventTime (number) — 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.
• eventId (string) required — Stable dedup key. Reuse to suppress duplicate events (Meta dedupes against pixel events with the same id).
• conversationId (string) — 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 clic...
• phoneE164 (string) — 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.
• value (number) — Conversion value (e.g. order total).
• currency (string) — ISO 4217 currency code (e.g. USD).
• contentIds (array) — Optional product / content identifiers.
• email (string) — User email. Normalized + SHA-256 hashed before sending to Meta.
• externalId (string) — Stable customer identifier. Lowercased + SHA-256 hashed before sending to Meta.
• testCode (string) — Meta test_event_code passthrough. Routes the event to the Test Events tab in Events Manager instead of the production dataset, useful for development.

Responses

200 — 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 (string) (enum: metaads)
• eventsReceived (integer) — Events accepted by Meta.
• eventsFailed (integer) — Events rejected by Meta (see failures).
• failures (array) — Per-event failure detail. Empty when all events were accepted.
• traceId (string) — Meta fbtrace_id for debugging. Surface in support tickets.

400 — Invalid body.

401

404 — Conversation not found.

422 — Configuration missing (no metaCapiDatasetId / connectedFacebookPageId on the account) OR the resolved conversation has no captured ctwa_clid.