---
title: "Send WhatsApp conversion event"
method: POST
path: "/v1/messaging/whatsapp/conversions"
tags: ["WhatsApp"]
---

# Send WhatsApp conversion event

`POST /v1/messaging/whatsapp/conversions`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/whatsapp/conversions`
- Auth: HTTP bearer

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.


**Billing:** Request; paid actions are priced in credits (see GET /v1/messaging/prices) · **Rate limit:** 60/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object: 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.
  - `email` string, email: User email. Normalized + SHA-256 hashed before sending to Meta.
  - `value` number: Conversion value (e.g. order total).
  - `eventId` string, required: Stable dedup key. Reuse to suppress duplicate events (Meta dedupes against pixel events with the same id).
  - `currency` string: ISO 4217 currency code (e.g. `USD`).
  - `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.
  - `accountId` string, 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.
  - `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.
  - `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.
  - `contentIds` string[]: Optional product / content identifiers.
  - `externalId` string: Stable customer identifier. Lowercased + SHA-256 hashed before sending to Meta.
  - `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).

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `traceId` string: Meta `fbtrace_id` for debugging. Surface in support tickets.
    - `failures` object[]: Per-event failure detail. Empty when all events were accepted.
      - `code` union
        - string
        - integer
      - `eventId` string: Echoes back the eventId of the failed event.
      - `message` string
      - `eventIndex` integer: Index into the submitted events array.
    - `platform` 'metaads'
    - `eventsFailed` integer: Events rejected by Meta (see failures).
    - `eventsReceived` integer: Events accepted by Meta.
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)