Meta Ads Lead Signals

Tell Meta which of your click-to-WhatsApp leads turned out to be good. Lodgestory reports the workflow stages and disposition outcomes you choose (Lead submitted, Qualified lead, Purchase with an amount) back to Meta's Conversions API, keyed to the exact ad click that started each chat — so Meta stops optimising your campaigns for "people who start conversations" and starts optimising for people who qualify and book.

At a glance


Where	Settings → Meta Ads Lead Signals (under Channels).
Who	Organisation admins and the Account Owner. Members see a "No access" card.
Channels	WhatsApp Official numbers connected through Connections. Ad referrals on Instagram and Messenger chats are recorded too, but signals are sent for WhatsApp only in this release.
What gets sent	Meta's standard business-messaging events — `LeadSubmitted`, `QualifiedLead`, `Purchase` (with currency and value) and the rest of the catalogue — each carrying the click id Meta put on the first message.
Where it shows on Meta	Events Manager → the WhatsApp Business Account's dataset (usually "<account name> Event Data") and, once you optimise for it, the results column of the campaign in Ads Manager.

How to find it

Sidebar: Settings → Meta Ads Lead Signals (in the Channels group, next to Social Media Connections). Inside a conversation, an ad-originated chat shows a Came from a Meta ad card in the right-hand panel with the ad's headline and the signals already sent for it.

What problem it solves

A click-to-WhatsApp ad hands Meta one fact: a conversation started. Meta then buys more of whatever produced conversations — which is often people who chat and never buy. Advertisers call the result "bad leads". The fix Meta offers is the Conversions API for Business Messaging: your CRM posts what happened after the click, and Meta's delivery learns from it. Lodgestory already knows what happened — the workflow stage the chat reached and the outcome your advisor captured — so this page turns those into Meta events without anyone touching a spreadsheet.

Core concepts

Term	What it means
Ad click / attribution	When a customer taps a click-to-WhatsApp ad, Meta attaches the ad's details and a click id to the first message. Lodgestory stores it against the chat. A customer who later clicks another ad gets a new attribution; the newest one is used.
Dataset	Meta's container for events from one WhatsApp Business Account. There is exactly one per account; connecting a channel here finds it (or creates it).
Signal rule	"When a chat reaches this workflow stage, report this Meta event" — or the same for a disposition outcome. Stage rules can carry a fixed amount; disposition rules can read the amount from a numeric field on the form.
Click window	Meta attributes an event to a click for 7 days. Signals for older clicks are logged as Outside window and not sent. Per channel, you can lift the window (up to 90 days) or clear it.
Lead episode	Meta mints a new click id on every tap, and people do tap twice (about 1 in 70 ad chats, usually the same ad within a day). Taps within the click window of the previous tap — same ad or another — form one lead, and each Meta event is reported once for it, whichever mapped stage is reached first. Restarting the workflow, moving back and forth, or running a second workflow inside the episode never double-counts. A tap after a longer gap starts a new lead. Events are always credited to the most recent tap, as Meta's last-click attribution expects. Each disposition capture reports once per matching rule.

Quick start

1. Connect the WhatsApp number

Open the page. Every WhatsApp Official channel appears as a card. Press Connect. Lodgestory looks up the dataset attached to the channel's WhatsApp Business Account using the channel's own token, creates it if none exists, and switches reporting on. The card then shows the dataset id, a token check, and this week's counts.

If Meta refuses the dataset call, the channel's token was issued before the events permission was added to Lodgestory's WhatsApp sign-up. Either Reconnect the number from Connections (the new token carries the permission) or paste a Conversions API access token generated in Events Manager → dataset → Settings. Pasted tokens are stored encrypted.

2. Map what a good lead looks like

Under Workflow stage signals, press Add, pick the workflow and the stage, and choose the event: a first-response or "engaged" stage → Lead submitted; a "Qualified" stage → Qualified lead; a "Booked" / "Won" stage → Purchase with a fixed amount when the ticket size is predictable.

Under Disposition signals, map a disposition template — optionally only when one of its fields has a specific value (Outcome = Booked) — to an event, and read the amount from a numeric field on the form when the value differs per lead. Only templates usable on chats are offered; dispositions captured on calls or bookings are never sent, because Meta only accepts events that happened in the messaging thread.

Stages and templates that were later deleted or deactivated are flagged on the rule so you can fix them.

3. Send a test event

Open Events Manager → the dataset → Test events, copy the test code, paste it on the channel card and press Send test. Lodgestory sends a LeadSubmitted event for the latest real ad click on that WhatsApp Business Account with the test code; it appears in the Test events view within a minute. Meta validates click ids, so the test needs at least one click-to-WhatsApp message to have arrived since the feature was switched on — the card tells you when there is none yet. Test events are logged with the source Test and never count as real signals.

4. Optimise the campaign

In Ads Manager, build the click-to-WhatsApp campaign with the Sales (or Leads) objective, conversion location WhatsApp, and pick the dataset event as the conversion. Meta unlocks Maximise the number of purchases through messaging once roughly ten events have arrived within a week; until then it optimises for conversations as before. Keep the campaign running for the first signals to accumulate.

Features in depth

Channel cards

Per WhatsApp number: the on/off switch, dataset id and name, token status (Token OK, Token missing permission, Token unverified for tokens Meta hides scopes on, or Custom token), the last signal sent and the last error, this week's Ad leads (chats that arrived from an ad), Sent, Failed and Skipped counts, the click window and the default currency used when a rule sets none. A channel that fails 25 times in a row is paused automatically and shows Paused after repeated failures; fix the token and switch it back on to resume — re-enabling clears the failure counter.

Signal rules

Two lists — workflow stages and disposition outcomes — each with an active switch and a remove action. The event picker shows Meta's full catalogue with the three events Meta's optimisation actually trains on (Lead submitted, Qualified lead, Purchase) marked as recommended. Purchase always needs an amount. A stage can be mapped once per organisation; disposition rules can overlap (a template-wide rule and a condition-specific rule both fire when both match). Mapping the same event on both a stage and a disposition is flagged, because a booked lead would then be reported twice.

Recent signals

The last 25 signals across all channels: when the stage change or disposition happened, the event and amount, whether it came from a stage, a disposition or a test, the channel, the status (Sent, Sending, Failed, Outside window), Meta's trace id for support tickets, the error text on failures, and a link to the chat.

Inside a conversation

The right-hand panel of an ad-originated chat shows Came from a Meta ad: the creative's headline or text, thumbnail, ad id, when the click happened, and every signal reported for the chat with its status. Organic chats show nothing.

What Meta receives — and what it never does

Every signal carries only: the event name, when it happened, the click id from the ad tap, your WhatsApp Business Account id, and — for purchases — the amount and currency you chose to map. Meta never receives the customer's phone number or name, any message content or agent notes, disposition answers other than the mapped amount, or anything from chats that did not start from an ad. The How it works button on the page opens a version of this explanation you can walk a customer or a marketing team through.

How it behaves under the hood

Nothing is added to message handling: the ad referral is copied off the first inbound message and stored off the request path; stage changes and dispositions are picked up from the same internal event stream that feeds webhooks and automations.
Sends run on a background queue with retries. Meta's temporary errors are retried with backoff; a bad token or payload fails once and is shown on the card. Meta rejects events older than 7 days, so a backlog older than that is never replayed.
Every signal is recorded once — a duplicate never reaches Meta even if a stage change is processed twice.
Instagram and Messenger ad referrals are stored for the sidebar card and future reporting; sending for those channels needs additional Meta permissions and is not part of this release.

Roles and permissions

Admins and the Account Owner connect channels, manage rules and send test events. Every member sees the Came from a Meta ad card on chats they can open. Nothing here changes who can move a chat between stages or capture a disposition.

How it fits with the rest of Lodgestory CRM

Connections — the WhatsApp Official number the ad points at; reconnect from there if a token lacks the events permission.
Workflow Lifecycle Stages — the stages you map; bot-journey Workflow Stage steps and channel auto-attach rules move chats through them too, and those moves report signals like any other.
Dispositions — the outcome forms whose captures can report a signal and supply the purchase amount (closing rules can require one before a workflow ends).
Webhooks — the new disposition.created event delivers every disposition capture to your own systems.
Analytics & Insights — ask Kaylee for the ad-lead funnel per ad id (ad leads → qualified → purchased, with purchase value).

FAQ

A chat from an ad shows no card. The click arrived before the feature was switched on for this server, or the customer's first message came from a plain WhatsApp link rather than a click-to-WhatsApp ad. Only ad clicks carry a referral.

Signals show Outside window. The stage change happened more than the channel's click window after the ad click (7 days by default). Lift the window on the channel card if your sales cycle is longer.

Meta shows fewer events than the page says were sent. Events Manager can take a few minutes; the Test events view shows only events sent with a test code. Check the dataset's overview for the business_messaging action source.

Can the same stage send two events? No — one event per stage, and one event of each kind per ad click. Use a disposition rule with a condition when one outcome needs a different event.

A customer came back months later from a different ad — what happens? The new tap is outside the previous lead's window, so a new lead starts: the stages they reach now are reported against the new ad, even if the same workflow ran for them before. The earlier lead keeps whatever it reported at the time.

The same person tapped the same ad three times this week. That is one lead. The three click ids are remembered, events are reported once each and credited to the latest tap, and the chat's card shows the earlier taps.

Changelog

2026-09-04 — Launched: dataset connect per WhatsApp number, workflow-stage and disposition signal rules, test events, recent-signals log, and the Came from a Meta ad card in conversations.