Zernio
Zernio
API Reference

WhatsApp

Templates

List templatesGETCreate templatePOSTGet templateGETUpdate templatePATCHDelete templateDELETEGet template by idGETUpdate template by idPATCHDelete template by idDELETELook up a library templateGET

Business Profile

Get business profileGETUpdate business profilePOSTUpload profile picturePOSTGet display name statusGETRequest display name changePOSTGet business usernameGETGet username suggestionsGETSet business usernamePOSTDelete business usernameDELETE

Groups

List active groupsGETCreate groupPOSTGet group infoGETUpdate group settingsPOSTDelete groupDELETEAdd participantsPOSTRemove participantsDELETECreate invite linkPOSTList join requestsGETApprove join requestsPOSTReject join requestsDELETE

Blocking

Check if a user is blockedGETList blocked usersGETBlock usersPOSTUnblock usersDELETE

Media

Download WhatsApp mediaGET

Conversions

Get CTWA conversions datasetGETProvision CTWA datasetPOSTList conversion eventsGETSend WhatsApp conversion eventPOST

Account Events

List account notificationsGET

Phone Numbers

Get number statusGETRegister a connected WhatsApp number on the Cloud APIPOSTMove a number to another profilePATCHRequest a Meta re-verification code for a BYO WhatsApp numberPOSTVerify the Meta re-verification code for a BYO WhatsApp numberPOST

Calling

Get calling config for an accountGETEnable calling on a numberPOSTUpdate calling configPATCHDisable calling on a numberDELETECheck call permissionGETList call history for an accountGETInitiate outbound callPOSTGet a single callGETEstimate per-minute costGETGet calling config for a numberGETGet a call recordingGETStart caller-ID verification for a customer-brought numberPOSTConfirm the caller-ID verification codePOST

Flows

List flowsGETCreate flowPOSTGet flowGETUpdate flowPATCHDelete flowDELETEGet flow JSON assetGETUpload flow JSONPUTGet flow preview URLGETList flow versionsGETPublish flowPOSTDeprecate flowPOSTSend flow messagePOSTList flow responsesGETGet Flows encryption key statusGETRegister a Flows encryption keyPOST

Sandbox

List your sandbox sessionsGETStart a sandbox activationPOSTRevoke a sandbox sessionDELETE
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
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

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

In addition to the required list, at least one of conversationId or phoneE164 must be supplied (used to resolve the originating CTWA conversation). The route enforces this at the Zod boundary; OpenAPI's required cannot express OR-required cleanly.

Response Body

application/json

application/json

{  "platform": "metaads",  "eventsReceived": 0,  "eventsFailed": 0,  "failures": [    {      "eventIndex": 0,      "eventId": "string",      "message": "string",      "code": "string"    }  ],  "traceId": "string"}
Was this page helpful?

List conversion events

Returns the most recent conversion events sent through `POST /v1/whatsapp/conversions` for the given WhatsApp account. Sourced from delivery logs (Axiom `late` dataset), so the visible window is bounded by log retention (about 30 days). Useful for rendering a "recent activity" panel on the conversions setup tab without standing up a parallel persistence layer. Per-event payload mirrors the structured log we write on every successful send: `eventName`, `conversationId`, `eventsReceived`, `eventsFailed`, `traceId`, `durationMs`, and the wall-clock `timestamp`.

List account notifications

Returns Meta-originated events recorded for a WhatsApp account, newest first: template review outcomes (approved, rejected, paused, category changes) and WABA status changes (restricted, disabled, reinstated, disconnected). Events are captured from Meta webhooks as they happen; the feed starts at the account's first recorded event and is not backfilled. Complements the push events `whatsapp.template.status_updated` and `account.disconnected` with a pollable history.

accountId*string

WhatsApp SocialAccount ID.

Length1 <= length
eventName*string

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.

Value in

  • "LeadSubmitted"
  • "Purchase"
  • "AddToCart"
  • "InitiateCheckout"
  • "ViewContent"
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

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

Length1 <= length
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 click).

Length1 <= length
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.

Length1 <= length
value?number

Conversion value (e.g. order total).

currency?string

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

Length3 <= length <= 3
contentIds?array<string>

Optional product / content identifiers.

email?string

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

Formatemail
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.