# Meta Ads (Click-to-WhatsApp)

> Prerequisite: Click-to-WhatsApp ads talk directly to Meta's Marketing Graph API, so this feature needs a connected Meta account — an access token plus an Ad Account ID and a Facebook Page ID. To publish ads live (rather than save drafts) you also need the WhatsApp destination: WhatsApp Business Account (WABA) ID, Phone Number ID, and the E.164 number. If the platform owner has configured global Meta keys, you can run ads on those instead — but billing goes to the platform's ad account, not yours.

## Overview

Meta Ads lets you build and launch Click-to-WhatsApp (CTWA) campaigns — Facebook and Instagram ads where tapping the ad opens a WhatsApp chat with your number, pre-filled with a message. You design the whole campaign inside WaDesk (objective, budget, audience, creative), and the app pushes it to Meta as a real, billable ad over the Marketing Graph API (v23 by default).

Open it from the top navigation under Meta Ads. The list shows every campaign in the current workspace with its status, objective, spend, and clicks. From there you create a new campaign, open a campaign's detail page, refresh its numbers, or jump to analytics.

> Who can use it: Meta Ads is an admin-level area in the workspace. Everything is limited to the current workspace, so each workspace only sees and bills its own campaigns. Your ad credentials are kept separate from your messaging setup — the part of WaDesk that sends WhatsApp messages never touches your ads token.

## Step 1 — Gather your Meta credentials

Everything you paste into WaDesk comes from Meta Business Manager (business.facebook.com) and the Graph API Explorer / Business Settings → System Users. Collect these six values before you open the connect screen.

### 1.1 — Ad Account ID

1. Open Business Manager → Business Settings (the gear icon).
2. In the left rail under Accounts, click Ad accounts.
3. Select your ad account. The ID is shown as `act_1234567890` — copy only the digits (`1234567890`). WaDesk adds the `act_` prefix for you.

> You can also read it from Ads Manager: the account number sits in the top-left account switcher and in the URL as `act=…`.

### 1.2 — Facebook Page ID

1. In Business Settings → Accounts → Pages, click the Page that will run the ads.
2. Copy the numeric Page ID shown in the panel (e.g. `1029384756`).
3. Alternatively, open the Page itself → About → Page transparency, where the Page ID is listed.

CTWA creatives must be attached to a Page, so this is required even for drafts you intend to publish.

### 1.3 — WhatsApp Business Account (WABA) ID + Phone Number ID

1. In Business Settings → Accounts → WhatsApp accounts, select your WhatsApp Business Account. Copy the WABA ID (e.g. `1122334455`).
2. Open the WABA, go to its phone numbers list, and click the number. Meta shows a Phone number ID (a long internal id like `109876543210987`) — copy it. This is not the dialable number.
3. Note the actual dialable number in E.164 form, digits only, no plus sign (e.g. `919876543210`). WaDesk uses the raw digits for the Marketing API and the `wa.me` deep link, and the Phone Number ID for the WhatsApp Business routing.

### 1.4 — Graph API access token (with `ads_management`)

WaDesk needs a long-lived token that carries the `ads_management` scope (and `pages_manage_ads` so the creative can attach to your Page). The robust choice is a System User token, which does not expire on a user-session basis:

1. Open Business Settings → Users → System Users and click Add to create a system user (give it an Admin role if you want it to manage ads).
2. With the system user selected, click Assign assets and grant it full control of your Ad account and your Page.
3. Click Generate new token. Choose your Meta app, then tick the scopes `ads_management` and `pages_manage_ads` (add `business_management` and `whatsapp_business_management` if you also manage the WABA from this app).
4. Copy the generated token. System-User tokens typically start with `EAAG…`. Store it somewhere safe — Meta shows it only once.

> Quick alternative for testing: the Graph API Explorer can mint a user token with `ads_management` selected under Add a Permission. It is shorter-lived — fine to verify the connection, but prefer a System User token for production so ads don't stop publishing when the token expires.

## Step 2 — Paste them into WaDesk

The first time you click Create campaign without credentials, WaDesk takes you to the connect screen automatically. You can also open it directly under Meta Ads → Connect. The form has two sections; here are all six fields and exactly which value each one takes.

# | Field (label on screen) | Required | Paste this
--- | --- | --- | ---
1 | Access token (System User) | Yes | The `EAAG…` token from step 1.4. Stored securely. Once saved it is never shown back — the field shows a saved placeholder, with a Clear the saved token checkbox to remove it.
2 | Ad account ID | Yes | The digits from step 1.1. The screen shows a fixed `act_` prefix box — type only the number after it.
3 | Facebook Page ID | Yes | The numeric Page ID from step 1.2.
4 | WhatsApp number | No* | E.164 digits, no plus sign (step 1.3). Where ad chats land.
5 | WABA ID | No* | Your WhatsApp Business Account ID (step 1.3).
6 | Phone number ID | No* | Meta's internal Phone Number ID (step 1.3).

* Fields 4–6 are optional to save the connection, but all three (plus the Page ID) are required to publish a CTWA ad live. WaDesk treats a campaign as "CTWA ready" only when Page ID, WABA ID, Phone Number ID, and the E.164 digits are all present.

Click Connect & continue to save. These credentials are kept separate for this workspace and are used only for ads.

> Platform fallback: If the platform owner has set up shared Meta Ads keys, the connect screen shows Using platform keys and you can create campaigns without entering anything. The fallback applies field by field — if you fill in only the ad account, WaDesk borrows the platform's token for the rest. Add your own keys to bill ads to your account instead of the platform's.

> To remove your keys: open the connect screen and click Remove keys. The workspace reverts to the platform fallback (if one exists). Removing keys does not touch campaigns already live on Meta.

## Step 3 — Create a campaign (5-step form)

Open Meta Ads → Create campaign. The form is one page with a live ad preview and a WhatsApp-click preview on the right. Work top to bottom:

1. Campaign details. Enter a Campaign name and pick an Objective: Messages, Link Clicks, Conversions, Lead Generation, Reach, Brand Awareness, or Video Views. WaDesk maps each to Meta's outcome objective automatically (see the objective table).
2. Budget & ad set. Set an Ad set name and a Daily budget (minimum $1/day; Meta enforces a floor, so a lower amount is raised to Meta's minimum). The budget runs an ad set optimised for starting conversations.
3. Click to WhatsApp. Toggle Click to WhatsApp on to route taps into WhatsApp. This reveals the WhatsApp number override, a prefilled message (the customer's first message when they tap), and the CTA button (WhatsApp Message or Learn More).
4. Audience targeting. Choose one or more Target countries (ISO codes from the chip picker, e.g. `IN`, `AE`), a Min/Max age (13–80), a Gender, and Interests from the curated dropdown — see Interest targeting.
5. Ad creative. Write an Ad headline (max 100 chars), a Destination URL, the Ad text (body), and upload an Ad image. Meta needs the image at 1080×1080 or larger for CTWA; the dimensions are checked in the browser before submit so you catch under-sized images early.

Pick a Status and click Publish campaign. What happens next depends on the status:

- Save as draft — saved locally only. Nothing is sent to Meta. Edit it later and switch the status to Paused or Active to publish.
- Publish paused — the full ad is created on Meta but stays dormant. Flip the toggle on the detail page to go live.
- Active after publish — the ad is created on Meta and then activated immediately (the whole tree is set to ACTIVE).

> Build with AI: Click Build with AI in the top bar to draft the campaign and ad-set names, headline, ad text, suggested interests, age range, countries, and a Click-to-WhatsApp message from a short brief (business name, product, objective, tone, markets). It fills in the form for you to review and edit — nothing is published until you click Publish. You can only use the AI providers your platform admin has enabled.

> Publishing requires the admin switch. Campaigns only go to Meta when the platform owner has turned Meta Ads on for the whole platform. If it's off, your campaign saves in WaDesk only and the detail page shows the reason.

## Step 4 — What happens when you publish

When you publish a campaign (and the admin switch is on), WaDesk builds the whole ad on Meta for you, using your workspace's connected ad account, Page, and WhatsApp Business Account. It does this in five steps:

# | Step | Produces
--- | --- | ---
1 | Upload the ad image to Meta | An image reference
2 | Create the campaign (starts paused) | Campaign ID
3 | Create the ad set (budget, targeting, WhatsApp destination) | Ad set ID
4 | Create the ad creative (image, headline, body, WhatsApp button) | Creative ID
5 | Create the ad (links the creative to the ad set) | Ad ID

All four IDs are saved on the campaign, so later pausing or deleting applies to the whole ad. A few things WaDesk gets right for you:

- The ad is set to send taps to WhatsApp, using your Page and the plain dialable number (Meta needs the actual number here, not the internal Phone Number ID).
- The ad shows your headline, body, and image, and its button opens a WhatsApp chat with your pre-filled welcome message.
- The interest names you picked are matched to Meta's real interest list at this point (and remembered for 7 days). A name that can't be matched is simply dropped (widening the audience) rather than failing the whole ad.
- Your chosen objective is translated into the form Meta currently expects.

> Automatic cleanup: if any step fails, WaDesk does its best to delete whatever it already created on Meta, so you're never left with a half-built ad quietly billing your account. The campaign is marked Failed, any progress is kept so you can see how far it got, and the exact Meta error is saved for you to read and retry.

## The campaign detail page

After creating a campaign (or by clicking View on the list), you land on its detail page. It shows:

- Status and actions — Activate/Pause (once the ad exists on Meta), Retry sync (if it failed), and Edit.
- Performance tiles — Spend, Impressions, Clicks, Reach, Conversations, CTR, CPC, and Frequency for the last 7 days. While the campaign is Active, these refresh automatically about once a minute.
- Ad preview — your image, headline, body, and the Send-WhatsApp-message button with the pre-filled message.
- The Meta IDs — the Campaign, Ad set, Creative, and Ad IDs returned by Meta. A dash means that step hasn't run yet.
- Targeting — the countries, age range, gender, and interests this campaign uses.

### Failed syncs and retry

If publishing failed, a red banner shows the exact Meta error message. Fix the underlying issue, then click Retry sync. Retry first removes anything half-built on Meta (so you don't end up with duplicates), then rebuilds the ad from scratch. Common causes shown in the banner:

- Missing Facebook Page ID on the workspace.
- Ad image smaller than 1080 px (Meta error code `1487616`).
- Token missing the `ads_management` permission (Meta error codes `200` / `1359047`).

> Click-to-WhatsApp needs all the WhatsApp details. To go live, a campaign needs the Page ID, WhatsApp Business Account ID, Phone Number ID, and the dialable number on the workspace before Meta will route taps to WhatsApp. If any are missing, publishing stops early and the saved error tells you exactly which field to add on the connect screen.

## Status sync and toggling

Use the Activate / Pause button on the detail page (or the toggle on the list) to make a campaign live or dormant. WaDesk pauses or activates the whole ad together, so Meta never bills a live ad under a paused campaign.

To refresh performance numbers, use Sync from the list. It pulls the latest figures from Meta for every published campaign — impressions, clicks, spend, reach, CPC, CPM, CTR, frequency, and conversations (messaging conversations started) — over the last 7 days. Campaigns that aren't on Meta yet show placeholder figures so the dashboard is never blank before your first real sync.

> Editing re-syncs: when you edit a campaign that's already on Meta, WaDesk rebuilds the ad on Meta so your new image, budget, and targeting actually take effect — not just inside WaDesk. Replacing the ad image also removes the old one.

## Objective → Meta outcome mapping

The form exposes friendly objective names; WaDesk converts each to Meta's modern outcome objective before creating the campaign.

Form objective | Meta objective sent
--- | ---
Link Clicks | `OUTCOME_TRAFFIC`
Messages | `OUTCOME_ENGAGEMENT`
Conversions | `OUTCOME_SALES`
Lead Generation | `OUTCOME_LEADS`
Brand Awareness | `OUTCOME_AWARENESS`
Reach | `OUTCOME_AWARENESS`
Video Views | `OUTCOME_ENGAGEMENT`

## Interest targeting

The Interests picker on the create form comes pre-filled with a curated list of interests, grouped into categories. You pick interest names from the dropdown; when you publish, WaDesk matches each name to Meta's real interest behind the scenes (and remembers the match for 7 days), so you never have to look up Meta's internal interest codes yourself.

- Leave Interests empty for broad targeting.
- Countries are submitted as ISO codes from the chip picker (for example `IN`, `AE`). With none chosen, the ad set defaults to `IN` + `US`.
- Age range is 13–80; gender is Male, Female, or All. The ad set also enables Meta's Advantage audience expansion.

> Tip: start with a few high-intent interests and a tight age range. You can review the resolved targeting on the campaign detail page and in Analytics under the Audience tab.

## Campaign analytics

Click Analytics from the Meta Ads header to open a workspace-wide summary: total spend, revenue, ROAS, impressions, reach, clicks, CTR, CPC, CPL, conversions, a breakdown by objective, and your top campaigns by ROAS. Pick a campaign from the dropdown (or click a card's mini-chart) to drill into a single campaign with Overview, Ads & sets, Audience, Attribution, and Events tabs.

This is separate from the workspace-wide messaging dashboard — see the Analytics page for delivery, read, and conversion charts across all your WhatsApp sends.

## Troubleshooting

Symptom / Meta code | Cause | Fix
--- | --- | ---
"Meta access token expired or revoked" (code `190`) | The token was rotated, revoked, or was a short-lived user token that lapsed. | Generate a fresh System User token with `ads_management` and paste it on the connect screen (tick Clear the saved token first if needed).
"missing the ads_management permission" (codes `200` / `1359047`) | The token's app/scopes don't include `ads_management` (and `pages_manage_ads`). | Re-generate the token with both scopes ticked; ensure the system user has full control of the ad account and Page.
"Permission denied" (code `200`) | The token is valid but not authorized for this ad account or Page. | In Business Settings, assign the ad account and Page assets to the system user, then re-generate the token.
Ad account not found / "Bad parameter" (code `100`) | Wrong Ad Account ID, or the `act_` prefix typed into the digits box. | Re-copy the digits only from Business Settings → Ad accounts. Confirm the account is active and not disabled. If it still fails after a Meta update, ask your admin to update the Meta version setting.
"This WhatsApp phone number is not linked to your account" | The internal Phone Number ID was used where Meta expects dialable digits. | Make sure the WhatsApp number field holds the E.164 digits (no plus). WaDesk uses those for the ad set and creative; the Phone Number ID is only for routing.
"Ad image is too small" (code `1487616`) | Creative image below 1080×1080. | Upload a larger square image. The browser pre-check catches most of these before submit.
Campaign saved in WaDesk only, no Meta IDs | Either Meta Ads is turned off platform-wide, you chose Save as draft, or the workspace is missing a WhatsApp detail. | Switch the status to Paused/Active, ask your admin to enable Meta Ads, and confirm Page ID, WhatsApp Business Account ID, Phone Number ID, and the dialable number are all set.
"rate limit reached" (codes `17`, `4`, `32`) | Too many Marketing API calls, app-level cap, or Page-level cap. | Wait a few minutes (or an hour for app-level) and click Retry sync.