POST
/
whatsapp
/
conversion-tracking
curl --request POST \
  --url https://api.chatvolt.ai/whatsapp/conversion-tracking \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "conversationId": "clx0abc123def456"
}'

Tracks a conversion event in the Meta Conversions API (CAPI) for Click-to-WhatsApp (CTWA) ads and WhatsApp business messaging.

​
Overview

This endpoint confirms to Meta Ads that an advertisement replied to by a customer resulted in a conversion (such as LeadSubmitted or Purchase).

When parameters are omitted, ChatVolt automatically resolves:

  • Active conversation ID (via phoneNumber, email, contactId, or ctwa_clid)
  • Click-to-WhatsApp click identifier (ctwa_clid) from stored attribution records within the 7-day attribution window
  • WhatsApp Business Account ID (wabaId) and Page ID
  • Meta Dataset ID (Pixel ID) and Access Token from channel credentials, agent config, or conversation variables
  • Automatic phone hashing (ph) with Brazilian 9th digit variations and email hashing (em)

​
Authentication

Bearer Token (ChatVolt API Key) passed via Authorization: Bearer <API_KEY>.

​
Example Request (Purchase)

{
  "conversationId": "clx0abc123def456",
  "eventName": "Purchase",
  "value": 150.00,
  "currency": "BRL",
  "orderId": "PED-12345"
}

​
Example Request (Lead Resolution by Phone)

{
  "phoneNumber": "5511999998888",
  "eventName": "LeadSubmitted"
}

​
Example Response

{
  "success": true,
  "metaAccepted": true,
  "attributionType": "ctwa_direct",
  "hasCtwaClid": true,
  "ctwaExpired": false,
  "eventId": "ctwa_clx0abc123_Purchase",
  "eventName": "Purchase",
  "events_received": 1,
  "messages": [],
  "fbtrace_id": "AbCdEfGhIjK"
}

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

conversationId
string

The ID of the conversation. Required if not provided in the request body or identified by phoneNumber/contactId/ctwa_clid.

phoneNumber
string

Customer's phone number to resolve the active conversation if conversationId is omitted.

email
string

Customer's email to resolve the active conversation or enrich Meta event match quality.

contactId
string

Customer's contact ID in ChatVolt to resolve the conversation.

ctwa_clid
string

Click-to-WhatsApp Click ID from Meta Ad to resolve the conversation.

wabaId
string

WhatsApp Business Account ID (WABA ID) for business messaging attribution. Optional if configured in channel or agent.

pageId
string

Facebook Page ID connected to the WhatsApp account/ad. Optional if configured in channel or agent.

datasetId
string

Meta Pixel or Dataset ID. Optional if configured in channel, agent, or conversation variables.

Body

application/json
conversationId
string | null

The ID of the conversation. Required if not provided in query parameters or identified by phoneNumber/email/contactId/ctwa_clid.

phoneNumber
string | null

Customer's phone number for conversation lookup if conversationId is omitted.

email
string | null

Customer's email for conversation lookup and Meta event matching.

contactId
string | null

Customer contact ID for conversation lookup.

datasetId
string | null

Meta Dataset ID (Pixel ID). Falls back to conversation variables, metadata, agent config, or channel config.

accessToken
string | null

Custom Meta Access Token (CAPI Token). If omitted, uses channel credentials or system token.

wabaId
string | null

WhatsApp Business Account ID (WABA ID) for business messaging attribution.

pageId
string | null

Facebook Page ID associated with the WhatsApp ad.

eventName
string | null

Name of the Meta conversion event (e.g., 'Purchase', 'LeadSubmitted', 'CompleteRegistration'). In business_messaging, Meta requires 'LeadSubmitted' for leads. Defaults to 'Purchase' if value > 0, otherwise defaults to 'LeadSubmitted'. Note that 'Purchase' requires a positive monetary value.

eventTime
integer | null

Unix timestamp in seconds when the event occurred (must be within the last 7 days). If omitted, automatically filled with current server timestamp.

ctwa_clid
string | null

The Click-to-WhatsApp click identifier (ctwa_clid). If omitted, it is automatically retrieved from conversation attribution records if within the 7-day window.

value
number | null

Monetary value of the conversion. Accepts numbers or localized strings (e.g. '150,50' or '150.50'). Falls back to conversation variables or metadata.

currency
string | null

Three-letter ISO currency code (e.g., 'BRL', 'USD'). Falls back to conversation variable 'currency', metadata, or defaults to 'BRL'.

eventId
string | null

Unique event identifier for deduplication in Meta. Defaults to a deterministic unique ID ('ctwa_{ctwaClickId || conversationId}_{eventName}') ensuring strict idempotency on automatic retries.

orderId
string | null

Order identifier used as eventId for deduplication and forwarded to Meta custom_data.order_id for order reconciliation.

transactionId
string | null

Transaction identifier used as eventId for deduplication.

test_event_code
string | null

Code from Meta Events Manager 'Test Events' tool to verify delivery in real-time.

Response

200 - application/json
success
boolean
metaAccepted
boolean

True if Meta accepted and processed at least one event (events_received > 0).

attributionType
enum<string>

Whether conversion matched via direct CTWA ad click (ctwa_direct), phone number match (phone_match), or customer email match (email_match).

Available options:
ctwa_direct,
phone_match,
email_match,
none
hasCtwaClid
boolean
ctwaExpired
boolean

True if CTWA click occurred more than 7 days ago. Note that ctwa_clid is still forwarded to Meta to enable extended ad attribution.

eventId
string
eventName
string
events_received
integer

Number of events received by Meta.

messages
string[]

Informational or warning messages returned by Meta API.

warnings
string[]

Array of warning messages from Meta.

fbtrace_id
string

Meta internal trace ID for debugging.

Was this page helpful?

Create Meta TemplateSend Buttons