How do I tell Meta which click-to-WhatsApp or Messenger chats turned into qualified B2B leads?

TofuAnswer by the Tofu team · checked

A few ripe strawberries held in a fine steel mesh strainer on a wet grey counter

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.

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_management plus whatsapp_business_manage_events (WhatsApp), or instagram_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.

ChannelIDs to storeWhere they come from
WhatsAppctwa_clid and your WhatsApp Business Account IDctwa_clid: the referral object in the Messages webhook. Account ID: your WhatsApp signup (Embedded Signup)
MessengerPSID and your Page IDPSID: the Messages webhook. Page ID: your Page
Instagram DirectIGSID (Instagram-scoped ID) and your Instagram account IDIGSID: 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_management permission 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:

EventSend it when
LeadSubmittedThe person shares their contact details in the chat
QualifiedLeadYour team decides the lead fits (your MQL or SQL point)
PurchaseA 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:

FieldValue
event_nameFor example QualifiedLead
event_timeUnix time when the lead was qualified
action_sourcebusiness_messaging
messaging_channelwhatsapp, messenger or instagram
user_dataWhatsApp: whatsapp_business_account_id and ctwa_clid. Messenger: page_id and page_scoped_user_id. Instagram: instagram_business_account_id and ig_sid
custom_datacurrency 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_time can 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_id plus at least one field such as email or phone, hashed with SHA-256. Events without page_id are rejected, and external_id isn'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 than ctwa_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

ProblemWhy it happensFix
No ctwa_clid in the webhookThe chat didn't start from a click-to-WhatsApp adSend hashed details with page_id, or treat it as organic
Whole request rejectedOne event_time is more than 7 days oldSend qualified events daily and leave out old ones
Hashed events rejectedpage_id is missingAdd page_id to user_data
Counts look doubledMeta doesn't deduplicateSend each lead's QualifiedLead once
The dataset doesn't show in your businessThe 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 DirectMeta offers none for these events yetOptimize those ads for conversations
Sources (6)

Related resources