> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Build and run Click-to-WhatsApp (CTWA) ad campaigns on Facebook and Instagram without leaving Soneka.

**Meta Ads** lets you launch **Click-to-WhatsApp** (CTWA) campaigns — Facebook and Instagram ads whose call-to-action opens a chat on your connected WhatsApp number — directly from Soneka. Every click becomes a real conversation you can route, automate, and measure alongside every other channel.

<Info>
  Meta Ads uses Meta's **Marketing Graph API v23**. You need the **WhatsApp Cloud API** engine and a Meta Business account with an ad account, Page, and WhatsApp Business Account (WABA) that all belong to the same Business Manager.
</Info>

## What you need before you start

Gather these five values — all of them come from Meta Business Manager. Keep them handy for the setup wizard.

| Value                                   | Where to find it                                                                                                                                                                                                           |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ad Account ID**                       | Business Manager → Business Settings → Ad Accounts. Starts with `act_`.                                                                                                                                                    |
| **Page ID**                             | Business Settings → Pages, or open the Page in the browser and copy the numeric ID from the URL.                                                                                                                           |
| **WhatsApp Business Account (WABA) ID** | Business Settings → WhatsApp Accounts.                                                                                                                                                                                     |
| **Phone Number ID**                     | WhatsApp Manager → Phone numbers → the number you'll route clicks to.                                                                                                                                                      |
| **System User access token**            | Business Settings → Users → System Users → create a system user → **Generate token** with the **`ads_management`**, **`business_management`**, **`whatsapp_business_management`**, and **`pages_read_engagement`** scopes. |

<Warning>
  Use a **long-lived system user token**, not your personal token. Personal tokens expire in hours and will silently break running campaigns.
</Warning>

## Connecting your ad account

<Steps>
  <Step title="Open the integration">
    Go to **Settings → Integrations → Meta Ads** and click **Connect**.
  </Step>

  <Step title="Paste your credentials">
    Enter the Ad Account ID, Page ID, WABA ID, Phone Number ID, and the system user token.
  </Step>

  <Step title="Validate">
    Soneka calls `/me` and `/{ad_account_id}` on the Graph API to confirm the token has the right scopes and that all four objects live in the same Business Manager. Errors are shown inline (see [Troubleshooting](#troubleshooting)).
  </Step>

  <Step title="Save">
    Once validated, Meta Ads appears in the sidebar for anyone with the **Marketer** role or above.
  </Step>
</Steps>

## Building a campaign

Open **Meta Ads → New campaign**. The wizard is five steps.

### Step 1 — Objective

Pick what you want to optimize for. Soneka maps each choice onto Meta's outcome model.

| You pick              | Meta objective sent                                         | When to use it                                                                          |
| --------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Get more messages** | `OUTCOME_ENGAGEMENT` with `MESSAGING_CONVERSATIONS_STARTED` | The default for CTWA. Best for lead generation.                                         |
| **Drive traffic**     | `OUTCOME_TRAFFIC`                                           | You want cheap link clicks that open WhatsApp, but not necessarily a full conversation. |
| **Awareness**         | `OUTCOME_AWARENESS`                                         | Top-of-funnel reach; least conversion-focused.                                          |
| **Sales**             | `OUTCOME_SALES`                                             | Paired with the catalog for product-focused CTWA.                                       |

### Step 2 — Audience

Define location, age, gender, languages, and detailed targeting (interests / behaviours). You can also pick a **saved audience** or a **custom audience** from your ad account.

### Step 3 — Placement & budget

* **Placement** — Automatic (recommended) or manual (Feed, Reels, Stories, Marketplace, etc.).
* **Budget** — daily or lifetime, with a start and end date.
* **Bid strategy** — lowest cost is the default; switch to a cost cap if you need it.

### Step 4 — Creative

Upload the image or video, write the primary text, headline, and description. The preview updates live. The CTA is fixed to **Send WhatsApp Message** and the destination is your connected phone number.

### Step 5 — Entry flow

Optionally attach a **flow** that runs the moment a click arrives:

* Pre-fill a message so the contact just taps **Send**.
* Tag the contact with the ad and ad set they came from (for attribution in Analytics).
* Send a welcome message and route to the right team.

Hit **Publish** and Soneka creates the campaign, ad set, and ad through the Graph API, and starts polling for insights.

## Monitoring performance

Each campaign has its own dashboard with:

* **Impressions, Reach, Clicks, CTR, CPM, CPC** — pulled from Meta insights.
* **Conversations started** — unique contacts who sent a first message from the ad.
* **Cost per conversation** — spend divided by conversations started.
* **Downstream conversions** — goals reached in the linked flow (bookings, deals created, payments received).

Metrics roll up into the workspace **Analytics** dashboard on the **Campaign & broadcast performance** panel, so CTWA sits alongside your broadcasts and templates.

## Pausing, editing, and deleting

From the campaign detail page:

* **Pause / Resume** flips the Meta status without deleting anything.
* **Edit budget / schedule** updates the ad set. Creative changes redeploy the ad and reset learning.
* **Delete** removes the campaign in Meta and in Soneka. Insights history stays visible for 90 days.

## Troubleshooting

Soneka surfaces Meta's raw error codes so you can act on them.

| Error       | Meaning                                                                   | Fix                                                                                      |
| ----------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **190**     | Token expired or invalid.                                                 | Regenerate the system user token and paste it in **Settings → Integrations → Meta Ads**. |
| **200**     | Missing permission for the requested action.                              | The system user needs `ads_management`. Regenerate with the correct scopes.              |
| **100**     | Bad parameter — an ID is wrong or objects don't share a Business Manager. | Recheck Ad Account, Page, WABA, and Phone Number IDs.                                    |
| **1487616** | Ad account is disabled or has a billing problem.                          | Fix billing in Business Manager, then retry.                                             |
| **17**      | Rate-limited by Meta.                                                     | Wait a few minutes; Soneka retries with backoff automatically.                           |

<Warning>
  **Ads publish but no clicks reach WhatsApp.** Almost always a mismatch between the Page and the WhatsApp number: they must belong to the same WABA, and the WABA must belong to the same Business Manager as the Ad Account.
</Warning>

<Warning>
  **Insights are stuck at zero.** Meta insights can lag by a few hours, especially for new campaigns. Give it 24 hours before assuming a problem.
</Warning>

## Related

* [Flow Builder](/features/flow-builder) — the entry flow that runs on every CTWA click.
* [Analytics](/features/analytics) — attribution and cost-per-conversation reporting.
* [Team Inbox](/features/team-inbox) — auto-assign incoming ad clicks to the right team.