How do I tell Meta which click-to-WhatsApp or Messenger chats turned into qualified B2B leads?
TofuAnswer by the Tofu team · checked

Use Meta's Conversions API for Business Messaging. When a chat starts from your ad, save its ID: the ctwa_clid click ID on WhatsApp, or the page-scoped user ID (PSID) on Messenger. When sales qualifies the lead, send a QualifiedLead event with that ID to your dataset, with action_source set to business_messaging. If an inbox or chatbot partner runs your chats, switch it on in their tool: Meta wrote the guide for those partners. Meta's messaging guide promises optimization only for purchases, so expect qualified-lead events to help mainly with measurement and audiences.
Ask Tofu next
Pick a question and Tofu Ads Agent answers it in chat.
- Should my click-to-WhatsApp ads optimize for conversations or leads?
- How do I match click-to-WhatsApp leads in my CRM without a phone number?
- Which WhatsApp inbox tools can send QualifiedLead events to Meta?
- Show me cost per conversation for my click-to-message ads last month
- How do I send Instant Form lead stages from HubSpot back to Meta?
As of November 2026.
Getting leads from Instant Forms instead of chats? Their stages go back by another route: see how to send CRM lead stages back to Meta.
Before you start
- Chats that run on Meta's messaging APIs. For WhatsApp, Meta's guide requires the WhatsApp Business Platform: the Cloud API (recommended) or the On-Premises API, whose last client expired on October 23, 2025. For Messenger and Instagram Direct, it requires the Messenger API.
- A partner, or your own developer app. Meta wrote its onboarding guide for Business Messaging Partners, the inbox and chatbot platforms that run conversations for advertisers. If yours supports it, use their setup. To build it yourself, you need a Meta developer app with advanced access to each channel's event permission:
page_events(Messenger),whatsapp_business_managementpluswhatsapp_business_manage_events(WhatsApp), orinstagram_manage_events(Instagram). - Marketing API access. The app also needs Full Access to the Marketing API Access Tier (once called Advanced Access), and Meta's pages disagree on what that takes. A banner at the top of the guide says the bar dropped from 1,500 to 500 Marketing API calls in the past 15 days, and Meta's Marketing API authorization page asks for at least 500 successful calls in the last 15 days with an error rate under 15% over the last 500 calls. The channel sections further down the guide still say 1,500 successful calls with an error rate under 10%. The App Dashboard shows the requirement that applies to your app.
- A clear point where a chat counts as qualified. That can be a label in your inbox tool or a stage in your CRM. The event can only go out once a person or a rule decides.
Step 1: Save the chat's ID when it starts
Every event you send later has to point back to the person who clicked your ad. Store these with the conversation, and copy them to the lead's CRM record.
| Channel | IDs to store | Where they come from |
|---|---|---|
ctwa_clid and your WhatsApp Business Account ID | ctwa_clid: the referral object in the Messages webhook. Account ID: your WhatsApp signup (Embedded Signup) | |
| Messenger | PSID and your Page ID | PSID: the Messages webhook. Page ID: your Page |
| Instagram Direct | IGSID (Instagram-scoped ID) and your Instagram account ID | IGSID: the Messages webhook. Account ID: your Instagram account |
Meta describes ctwa_clid as unique per click and present only when the chat started from a click-to-WhatsApp ad. Organic chats won't have one. If WhatsApp usernames are changing how you match these people in your CRM, see how to match click-to-WhatsApp leads now that people can hide their number.
Step 2: Create or find the dataset
Events go to a dataset, the same kind of container Events Manager uses for website events. Meta says datasets are created through a partner platform or in Events Manager. A developer can also create one with a single POST call to the Dataset API on the Page ID (Messenger), the WhatsApp Business Account ID (WhatsApp) or the Instagram user ID (Instagram). If that asset already has a dataset, the call returns its ID instead of making a new one.
What else Meta's guide says:
- Your business owns the dataset. A partner gets access to it.
- One Page can have only one linked dataset.
- You can reuse an existing dataset. Meta says adding business messaging to a website Conversions API setup doesn't interfere with it.
- For Messenger, the dataset shows under your business only if the Page belongs to a business account and the
business_managementpermission was granted. Otherwise it's hidden from you.
Step 3: Decide which outcomes to send
Meta's guide lists 14 events for business messaging. Three fit a B2B lead funnel:
| Event | Send it when |
|---|---|
LeadSubmitted | The person shares their contact details in the chat |
QualifiedLead | Your team decides the lead fits (your MQL or SQL point) |
Purchase | A deal closes, with currency and value |
Meta says these events should describe what happens in the chat, and a conversion on your website goes through the website Conversions API instead. Write down one rule for "qualified" and apply it the same way every time, so the signal Meta gets stays consistent.
Step 4: Send the event
Post to https://graph.facebook.com/v27.0/{DATASET_ID}/events. Each event in the data array carries these fields:
| Field | Value |
|---|---|
event_name | For example QualifiedLead |
event_time | Unix time when the lead was qualified |
action_source | business_messaging |
messaging_channel | whatsapp, messenger or instagram |
user_data | WhatsApp: whatsapp_business_account_id and ctwa_clid. Messenger: page_id and page_scoped_user_id. Instagram: instagram_business_account_id and ig_sid |
custom_data | currency and value, for purchases |
Partners also add partner_agent, set to the name Meta assigned them. Build in three rules:
- Send within 7 days. Meta's parameter reference says
event_timecan be at most 7 days before you send. One older event makes Meta reject the whole request. - Remove duplicates yourself. Meta says it doesn't deduplicate these events.
- No click ID? On WhatsApp you can send hashed customer details instead:
page_idplus at least one field such as email or phone, hashed with SHA-256. Events withoutpage_idare rejected, andexternal_idisn't used for matching. Meta says this path only attributes to ad interactions from the past 7 days, works in some countries only, and matches less reliably thanctwa_clid.
Step 5: Check the events in Events Manager
Open the dataset in Events Manager and confirm the events arrive. If a partner built the connection, Meta asks them to show you where your dataset is.
Optional: let Meta flag WhatsApp leads for you
If your WhatsApp provider onboarded you through Meta's Embedded Signup, Meta can read new chats from click-to-WhatsApp ads and flag when a lead or a purchase happened, so the provider can report it as LeadSubmitted or Purchase. Turn it on in Meta Business Suite: Settings > Accounts > WhatsApp accounts, pick the account, then in the Summary tab under Privacy and data sharing use the toggle Automatically identify order, lead & other events from conversations in this account. Meta says it isn't available in the EU, the UK, Japan or South Korea. It spots leads, not qualified ones, so it doesn't replace Step 4.
What does Meta do with the events?
Meta's parameter reference says every action source, business_messaging included, enables measurement, custom audiences and ad optimization. The business messaging guide is narrower: its FAQ only promises purchase optimization, for ads that click to Messenger or WhatsApp, and says Instagram Direct ads can optimize for conversations instead. Neither page says whether click-to-message ads can optimize for QualifiedLead. To choose the goal itself, see whether click-to-message ads should optimize for conversations or leads. If Meta's Business Agent answers your chats, how to tell if it's qualifying your leads covers its own reporting.
Partner tools can add rules of their own. respond.io's help page (updated October 2026) says that for click-to-WhatsApp ads only one event can go out per ad event, within 7 days of the ad click, and that the Conversions API isn't supported for Facebook and Instagram Pages registered in the EU, Norway, Iceland, Liechtenstein, the UK or Japan. Its step offers two event types, Purchase and Lead Generated. Meta's guide doesn't state those limits for ctwa_clid events, so ask your partner what applies. Kommo's guide (November 2026) shows the B2B pattern: a pipeline trigger on a "Qualified" stage sends a Qualified Lead event.
Common problems
| Problem | Why it happens | Fix |
|---|---|---|
No ctwa_clid in the webhook | The chat didn't start from a click-to-WhatsApp ad | Send hashed details with page_id, or treat it as organic |
| Whole request rejected | One event_time is more than 7 days old | Send qualified events daily and leave out old ones |
| Hashed events rejected | page_id is missing | Add page_id to user_data |
| Counts look doubled | Meta doesn't deduplicate | Send each lead's QualifiedLead once |
| The dataset doesn't show in your business | The Page isn't in a business account, or business_management wasn't granted (Messenger) | Put the Page in your business portfolio and reconnect the partner |
| No optimization option for Instagram Direct | Meta offers none for these events yet | Optimize those ads for conversations |
Sources (6)
- Conversions API for Business Messaging: Onboarding Guide (Meta for Developers), checked November 8, 2026
- Server event parameters (Meta for Developers), checked November 8, 2026
- Automatic Events API (Meta for Developers), checked November 8, 2026
- Marketing API: Authorization (Meta for Developers), checked November 8, 2026
- Step: Send Conversions API Event (respond.io Help Center, updated October 13, 2026), checked November 8, 2026
- Meta Conversions API (CAPI) overview (Kommo, updated November 3, 2026), checked November 8, 2026