> For the complete documentation index, see [llms.txt](https://docs.patagon.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.patagon.ai/en/marketing-and-attribution/meta-ads/meta-conversions-api.md). # How to connect Meta and map conversions For rating definitions, see the [ILA lead rating system](/en/agent-optimization/ila-rating-system.md). When a lead qualifies on WhatsApp, Patagon AI can send that conversion back to your ad platform. This lets the platform's optimization model learn from your *qualified* leads instead of every reply, improving Click-to-WhatsApp (CTWA) ad performance over time. **Meta** is supported today. Google Ads, TikTok Ads, LinkedIn Ads, Snapchat Ads, and X Ads are coming soon. ## Prerequisites * An active Meta ad account * WhatsApp connected and your agent live in Patagon AI * Admin access to Meta Business Manager ## 1. Connect Meta 1. Go to **Leads → Attribution → Settings → Connect Platforms**. 2. On **Meta Business**, click **Connect** and complete the OAuth flow. ![Connect Platforms](/files/SqL0TO3LLbqlFyhOOzBp) 3. In **Configure Meta Integration**, choose: * **Ad Account** — the account that runs your campaigns. * **Pixel / Dataset** — where conversions will be sent (typically your Meta Conversions API dataset). 4. Click **Save**. ![Configure Meta Integration](/files/E9j2YmTdx2TKhPlovPAa) {% hint style="info" %} The Meta connection is configured **per agent**, so each agent can point to its own ad account and dataset. {% endhint %} ### The dataset your CTWA conversions need A **dataset** is where Meta collects the events from your ads. (Meta used to call these "pixels" and the UI still says "Datasets and pixels" — it's the same thing.) The events a dataset receives give it a type: * A **website dataset** is for journeys that **start on your website**: someone clicks your ad, lands on a page, and opens WhatsApp from there — your **Landing → WhatsApp** campaigns. The conversion still happens in the WhatsApp conversation, but because the journey began on the web, Patagon AI sends it to your website dataset. * A **business messaging dataset** is for journeys that go **straight to WhatsApp**, with no landing page in between: someone clicks a **Click-to-WhatsApp** ad and lands directly in a conversation. These conversions must flow to a business messaging dataset so Meta can attribute them correctly. So what sets the two apart isn't *where* the conversion happens — it's always the WhatsApp conversation — it's **how the person got there**. For Meta to accept your CTWA conversions, they have to land in a dataset that can receive **business messaging events**. There are two ways to have one: | Your situation | How you get a messaging-capable dataset | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You **already have a website dataset** and want to use it for CTWA too | Add a Messaging data source to it, **once**, so it receives **both** web and messaging events. Follow [How to add business messaging events to your website dataset](/en/marketing-and-attribution/meta-ads/meta-conversions-api/ctwa-offline-conversions.md). | | You **don't have a business messaging dataset** | When you turn on the **WhatsApp Business Dataset** toggle, Patagon AI **creates one for you** — named **` - Patagon Event Data`** and owned by Patagon AI. See [How Patagon AI creates your business messaging dataset](/en/marketing-and-attribution/meta-ads/meta-conversions-api/business-messaging-dataset.md). | {% hint style="info" %} Turn on the **WhatsApp Business Dataset** toggle in your Meta integration for **Click-to-WhatsApp** campaigns (where people reach WhatsApp directly from the ad, with no landing page). Patagon AI detects an existing messaging-capable dataset automatically and only creates one if you don't have it. **Landing → WhatsApp campaigns don't need this** — they use your website dataset. In Meta's technical view, the two dataset types show as `website` and `business_messaging`. {% endhint %} #### Connect the dataset to your ad account Your CTWA dataset has to be connected to the ad account that runs those campaigns — otherwise it won't appear when you build or optimize a CTWA campaign. If Patagon AI created the dataset for you, connect it once yourself, in Meta Business Manager: 1. Go to **Business settings → Data sources → Datasets and pixels** and select the dataset named **` - Patagon Event Data`**. Open its **Connected assets** tab. ![Find the Patagon-created dataset under Datasets and pixels](/files/0CLdIH3VDjv0rsYfRB1q) 2. Click **Connect assets**. ![Connect assets](/files/98yY68F1nVrHE482dGoF) 3. Choose **Ad accounts**, tick the ad account you'll use for your CTWA campaigns, and click **Add**. ![Select your ad account and click Add](/files/l2jZihLS0zQR3STgE9TR) ## 2. Map conversions A mapping tells Patagon AI which in-product event should fire a conversion, and which conversion action to send to the ad platform. 1. Go to **Leads → Attribution → Settings → Map Conversions** and click **Add mapping**. 2. In **Add Conversion Mapping**, choose: * **Patagon AI Event** — the trigger, based on lead rating: `Lead 3 Star`, `Lead 4 Star`, `Lead 5 Star`, `Lead 3+ Star`, or `Lead 4+ Star`. * **Platform** — Meta. * **Account** — the connected Meta account. * **Conversion Action** — the Meta standard event to record (e.g. `Lead`, `Purchase`). 3. Click **Create Mapping**. It's now live for any new lead matching the trigger. ![Add Conversion Mapping](/files/AAGbUQUpMftYZW2Jtj2M) {% hint style="warning" %} **CTWA conversions use a business messaging dataset** (Meta's `business_messaging` action source). Meta only accepts a limited set of standard events for it. When mapping conversions for Click-to-WhatsApp, use only: `Lead`, `Purchase`, `AddToCart`, `ViewContent`, `InitiateCheckout`. {% endhint %} ## 3. Verify it's working You can confirm conversions in two places. **In Patagon AI** — go to **Leads → Attribution → Settings → Events**. Each row shows the date, platform, the Patagon AI event that triggered it, the conversion name, and the status — **Confirmed**, **Pending**, or **Failed**. If one fails, use the retry action to resend it. ![Conversion Events log](/files/zGsAy50uefBBdgkbT6x3) **In Meta** — open **Ads Manager → Events Manager → Datasets**, select the dataset connected to Patagon AI, and check the **Overview** tab. Conversions appear within about a minute. ## Common errors | Error message | What it means | Fix | | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *event\_name "Lead" not valid for business\_messaging* | The event isn't allowed for Click-to-WhatsApp events on Meta's side. | Map a CTWA-supported event (`Lead`, `Purchase`, `AddToCart`, `ViewContent`, `InitiateCheckout`). If it persists, contact support. | | *missing page\_id or whatsapp\_business\_account\_id* | Patagon AI isn't sending the WhatsApp Business Account ID with the event. | Your WhatsApp channel may not have completed embedded signup correctly. Re-run the WhatsApp connection wizard. | | *the dataset must have a WhatsApp Business account associated* | The dataset isn't linked to your WABA. | Turn on the **WhatsApp Business Dataset** toggle (step 1), or follow [How to add business messaging events to your website dataset](/en/marketing-and-attribution/meta-ads/meta-conversions-api/ctwa-offline-conversions.md). | | *(#100) OAuthException — Invalid parameter* | The dataset isn't bound to an active ad account, or your token lacks access. | Verify the dataset is enabled in Events Manager, your ad account has full access to it, and the OAuth token has the `ads_management` scope. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.patagon.ai/en/marketing-and-attribution/meta-ads/meta-conversions-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.