WhatsApp Purchase conversions
Record one WhatsApp conversion (Purchase by default) for a Click-to-WhatsApp interaction through a connected WhatsApp Cloud API channel. Hub resolves the app credential and WABA; the provider manages its dataset. A provider receipt is not a guarantee that Meta attributed the purchase to an advertisement, recognized revenue, or changed a contact's CRM status.
Find the click identifier
Use the exact payload.message.ctwaClid from the Hub message webhook (the upstream field is ctwa_clid). It is case sensitive. It is not the phone number, message ID, template ID, session ID or ad ID. A click not already stored by Hub is accepted, so the integration remains responsible for using a genuine identifier from this channel context.
Submit a purchase
curl --request POST \
'https://app.chatt2.me/v1/communication/channel/whatsapp/CHANNEL_UUID/conversions' \
--header 'x-api-key: YOUR_APPLICATION_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-123' \
--data '{
"ctwa_clid": "EXACT_CLICK_ID_FROM_WEBHOOK",
"currency": "BRL",
"value": 123.45
}'
The body requires these three fields and also accepts optional event_name and event_time. currency must be a current uppercase ISO 4217 code. value is a finite non-negative number, no greater than 9007199254740991, in major currency units: 123.45 means BRL 123.45, not 12345 cents. Hub does not round or exchange the amount. ctwa_clid is 1–2048 characters without whitespace/control characters. Do not submit tokens, app/WABA IDs, dataset IDs or provider parameters.
Idempotency-Key is mandatory: 1–160 printable ASCII characters without spaces. Generate and store it in the originating purchase system, one stable key per purchase and channel. Do not generate a fresh key for every HTTP retry.
event_name is optional text: 1–255 characters, not blank and without control characters. Hub preserves it exactly and defaults to Purchase when omitted. event_time is an optional non-negative safe integer (at most 9007199254740991) in Unix seconds, not milliseconds; when omitted, Hub uses the first admission time. The provider still validates supported event names and event time windows. Do not send empty strings or null.
For example, to supply both fields:
{
"ctwa_clid": "EXACT_CLICK_ID_FROM_WEBHOOK",
"currency": "BRL",
"value": 123.45,
"event_name": "Purchase",
"event_time": 1793966400
}
The timestamp above illustrates the format; use the actual event time within the provider's accepted window. You may supply either optional field independently. Hub fixes business_messaging and whatsapp, and sends one event per request without batches. Requests are scoped to the API key's application. Unsupported/sandbox channels cannot submit events.
Receipt
{
"status": "accepted",
"eventId": "840887bc-e735-4b5f-b22e-9c476e4719e8",
"eventName": "Purchase",
"eventTime": 1793966400,
"eventsReceived": 1,
"fbtraceId": "PROVIDER_TRACE_ID",
"replayed": false
}
HTTP 200 means the provider acknowledged one event, or Hub returned its stored accepted receipt. fbtraceId can be null. replayed: true means no second provider call was made. The receipt reports the submitted event name and time, or their defaults. A replay preserves the original event name, time and event ID. The receipt does not contain the click identifier.
Idempotency and uncertain delivery
The key is scoped to the channel and shared across REST and operational MCP. The same key and body return the existing receipt. A changed body, including adding, removing or changing event_name or event_time, under that key returns WHATSAPP_CONVERSION_IDEMPOTENCY_CONFLICT. Use a new key only for a genuinely different purchase, not to bypass an error.
Concurrent submissions do not send twice. An in-progress request returns HTTP 409 WHATSAPP_CONVERSION_IN_PROGRESS; check again later using the same key and body. If the process loses the response, times out, receives an ambiguous response, or cannot persist the provider receipt, the result is WHATSAPP_CONVERSION_DELIVERY_UNKNOWN. An abandoned in-progress dispatch becomes unknown after 60 seconds. No automatic resend occurs. Reconcile it with your administrator/provider before any further sending. Reusing the same key will not force a second event.
Hub does not promise exactly-once processing inside Meta: the wrapper does not document external event deduplication. Changing the key can cause duplicates. Receipts remain durable; raw click IDs are not stored in the receipt ledger.
Limits and errors
The conservative integration-wide provider budget is 500 requests per 60 seconds, shared by REST and operational MCP. Receipt replays do not consume provider calls. Coordination failure blocks a new dispatch. HTTP 429 includes Retry-After and retryAfter; after the delay, retry the same key and body. Hub never automatically retries this POST.
| Code | HTTP | Meaning |
|---|---|---|
WHATSAPP_CONVERSION_INVALID_INPUT | 400 | Fix fields/header before a new purchase attempt |
WHATSAPP_CONVERSION_UNSUPPORTED_CHANNEL | 409 | The channel must support WhatsApp Cloud API conversions |
WHATSAPP_CONVERSION_WABA_REQUIRED | 409 | The connected app has no usable associated WABA |
WHATSAPP_CONVERSION_IDEMPOTENCY_CONFLICT | 409 | This key was used for a different payload |
WHATSAPP_CONVERSION_TARGET_CHANGED | 409 | App/WABA association changed; reconcile the old attempt |
WHATSAPP_CONVERSION_IN_PROGRESS | 409 | Existing dispatch still in progress |
WHATSAPP_CONVERSION_DELIVERY_UNKNOWN | 409 | Provider acceptance could not be confirmed; no resend |
WHATSAPP_CONVERSION_RATE_LIMITED | 429 | Wait and reuse the same key/body |
WHATSAPP_CONVERSION_PROVIDER_ACCESS | 502 | Provider rejected app authorization |
WHATSAPP_CONVERSION_PROVIDER_REJECTED | 502 | Provider rejected the event |
WHATSAPP_CONVERSION_UNAVAILABLE | 503 | Coordination/provider temporarily unavailable before dispatch |
Authentication failures for Hub itself return 401/403; a channel outside the application's scope returns 404. Provider messages and tokens are not passed through as customer errors. Responses use Cache-Control: no-store.
Operational MCP
Call hub_push_whatsapp_purchase_conversion with the selected organizationContextId, applicationId, applicationChannelId, an action idempotencyKey UUID, conversionIdempotencyKey and purchase containing the same required REST fields and optional event_name/event_time. An omitted time is fixed when the action is confirmed, not when it is prepared. The business key conversionIdempotencyKey must equal the REST Idempotency-Key for the same purchase; it is separate from the action preparation key.
The tool prepares an action. A signed-in authorized person reviews the channel, event name, supplied Unix time (if any), currency/value and masked click ID, then confirms with the existing Hub MFA flow. Preparation, cancellation and expiration send no conversion. The click identifier is sealed in the pending action and excluded from safe outputs. Confirmation revalidates the app/WABA target and permissions before calling the same conversion service as REST.
The completed action exposes its safe conversion receipt. Receipt acceptance is not ad attribution. Do not automatically create another action/key after unknown delivery. See MCP actions for confirmation and recovery, and Template insights for read-only analytics/comparison.