Meta WhatsApp Conversions API
Overview
Section titled “Overview”WhatsApp Conversions API reports conversions from your WhatsApp conversations back to Meta, so campaigns running Click to WhatsApp Ads can optimize towards the conversations that led somewhere rather than towards clicks.
Because the events are sent from your server rather than the browser, they arrive whether or not client-side tracking was available at the time.
The three Meta messaging destinations are separate connectors, one per channel. Connect the one that matches the ad type you are running.
Supported sources
Section titled “Supported sources”Sources supported by Meta WhatsApp Conversions API
| Category | Supported |
|---|---|
| Messaging ads |
Prerequisites
Section titled “Prerequisites”Before connecting WhatsApp Conversions API you need:
- A Meta Ads account.
- A Meta Business Manager account, with admin access so you can grant permissions.
- Server-side API permission on the dataset you intend to send to.
- If you are connecting manually, a Dataset ID and an Access Token generated in Events Manager.
- A Datahash Studio account with the target project selected.
- A Click to WhatsApp Ads source connected in the same project. Events reach Meta through the source, so a connected destination on its own sends nothing.
Authentication
Section titled “Authentication”In Studio, open Destinations, find Meta, and click the WhatsApp Conversions API tile. You can connect in two ways, and single sign-on is the recommended one.
Single sign-on
Section titled “Single sign-on”- Choose the Business Account you want to connect.
- Select the Pages you want to include.
- Complete Meta’s consent flow, granting Datahash the access it asks for.
Manual setup
Section titled “Manual setup”- Enter your Dataset ID and Access Token.
- Click Validate Credentials.
| Field | What it is | Where to find it |
|---|---|---|
| Dataset ID | The unique identifier Meta assigns to a dataset created in Events Manager. | business.facebook.com, then All tools, Events Manager, Data Sources, select your dataset, Settings. |
| Access Token | A credential authorizing Datahash to send events to that dataset on your behalf. | The same Settings screen, scroll to the Conversions API section, choose Set up manually, then Generate Access Token. |
Configuration
Section titled “Configuration”- Provide a Connection Name.
- Select the Facebook Page the conversations belong to.
- Select the Dataset ID events should be written to.
- Click Finish.
The events themselves come from the connected source. Event names, the identifiers used for matching and the deduplication key are all set by the source mapping, not here.
Manage instance
Section titled “Manage instance”To change the instance, open it from the Manage existing instance table, click the edit option in the menu to the top right, update the fields and click Finish.
Deduplication
Section titled “Deduplication”The event ID is what deduplicates. Where the dataset, the event name and the event ID all match, two deliveries are counted as one conversion, so keep the event ID stable for a given conversation.
Data & identifiers
Section titled “Data & identifiers”Signals sends the identifiers your source carries. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach Meta.
The strongest match key on this channel is ctwa_clid, the click ID Meta generates when someone taps a Click to WhatsApp ad. It arrives with the first inbound message of the conversation and ties that conversation to the click that produced it, which no hashed contact detail can do. Meta requires it unhashed. A hashed ctwa_clid matches nothing, and the conversion falls back to contact-detail matching or goes unattributed.
Send the phone number, email and name alongside it wherever your source holds them. Those are normalized and hashed as usual, and they are what covers conversations Meta cannot tie back to a click.
Best practices
Section titled “Best practices”- Connect the destination that matches your ad type. A Click to WhatsApp campaign should report to WhatsApp Conversions API, not to the web Conversions API.
- Pass
ctwa_clidthrough unhashed. It is the only identifier that attributes a conversation to the ad click rather than to a person.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Validate Credentials fails. Re-check the Dataset ID and confirm the token was generated for that dataset and has server-side API permission.
No Pages listed. The authenticated user cannot see them, or the business you selected does not own them. Check Page roles in Business Manager, then reconnect.
No events appearing in Events Manager. Confirm a Click to WhatsApp Ads source is connected in the same project and sending. A connected destination on its own produces nothing.
Conversions counted twice. The event ID is not stable across deliveries. See Deduplication.
Conversions arrive in Events Manager but are not attributed to the campaign. ctwa_clid is missing from the event, or it was hashed on the way. Meta needs it in plain text. See Data & identifiers.
Delivery stopped. The access token may have expired or been revoked. Generate a new one in Events Manager and re-validate.