Skip to main content

​
Ads attribution and lead ingestion

Orbit’s ads surface closes the advertising loop in two directions. The click-to-WhatsApp (CTWA) funnel captures which ad a customer tapped before a conversation starts, and credits downstream revenue back to that ad. The lead ads funnel ingests Meta instant-form submissions into your contact store. Together they let you answer “which ads bring customers in, and what are they worth” — the concept layer the ads activation guide and the ads console guide assume. Endpoint schemas live in the Ads API reference.

​
Two workflow halves

CTWA attribution covers the conversational channel: a customer taps a Facebook or Instagram ad that opens a WhatsApp, Messenger, or Instagram Direct chat. Meta stamps the first inbound message with a referral block — the source ad id, creative, and a click id — and Orbit records it on the conversation. Lead ads ingestion covers the form channel: a prospect submits a Meta instant form, Meta sends a leadgen webhook, and Orbit turns the submitted answers into a contact with the originating ad attached. Both halves report into the same attribution view, and both forward outcomes back to Meta through the Conversions API so Meta’s delivery optimization sees the conversion too.

​
CTWA attribution

Click-to-chat attribution is first-touch: a contact’s earliest captured referral fixes their entry ad, and every order that contact places at or after that touch is credited to it. First-touch keeps the per-ad contact counts partition-clean — summing across ads never double-counts a contact — and makes the per-ad entry counts reconcile against the raw referral volume. The report rolls up over a configurable window (1–365 days, 30 by default):
  • Entry counts — raw referral messages and distinct first-touched contacts per ad.
  • Attributed revenue — local orders (for example, WhatsApp catalog orders) credited to the entry ad. Mixed currencies blend into one reporting currency using caller-supplied FX rates; revenue in a currency with no rate is surfaced separately as unconvertible rather than silently blended at 1:1.
  • Spend and ROAS — Meta ad spend fetched over the same window, joined with attributed revenue through the same return-on-ad-spend maths Orbit’s campaign reports use, so the two can never drift apart.
Individual conversions also flow back to Meta: when your agent qualifies a lead or a purchase lands, a match key — the click id stamped on the inbound message, or the contact’s SHA-256-hashed phone or email — tells Meta which ad started the conversation. Raw PII never leaves Orbit.

​
Lead ads ingestion

Meta delivers a leadgen change carrying only identifiers: the lead id, plus the page, form, ad, and adgroup that produced it. Orbit fetches the actual answers from Meta’s Graph API and maps the submitted answers into a contact draft:
  • Known question names fold onto first-class contact columns — email, phone, first and last name, company, job title, city, state, country, and postal code, including Meta’s own aliases (phone vs phone_number, zip vs postal_code).
  • A full_name answer splits into first and last name when the form did not also ask them separately.
  • Every unrecognized question is preserved as a custom field, so no answer a prospect gave is silently discarded.
  • Attribution travels with the contact — the lead, form, ad, adgroup, and campaign ids land on the contact record so closed-loop reporting can join the contact back to the ad.
  • A lead with neither email nor phone is skipped, not stored — an empty contact record is worse than no record.
Ingestion runs through the same deduplication machinery as a contact CSV import, and each lead’s Meta lead id serves as its idempotency key — a retried webhook cannot create a duplicate, and a resubmission of the same form updates in place rather than creating a second contact.

​
Where ads events surface

Attribution data lands in three places:
  • The attribution report — per-ad entry counts, first-touched contacts, attributed revenue, spend, and ROAS, sorted best earners first.
  • CDP events — conversions posted to Meta are first modeled as outcomes in Orbit, so the analytics funnel and segment builders can filter on ad-driven entry points.
  • The Ads console — campaign insights (impressions, clicks, spend, started conversations) and the conversions configuration share the same connected account.
Because every ad event carries its source ids, joins across these views are deterministic — an attributed contact always resolves back to the ad and campaign that produced it.

​
Setup summary

  1. Connect one Meta ad account — OAuth from Settings > Channels; one account per organization. Writes need owner or admin. See the ads activation guide.
  2. Launch click-to-chat campaigns on WhatsApp, Messenger, or Instagram Direct from the Ads console. See the ads console guide.
  3. Subscribe the page webhook to leadgen so instant-form leads ingest into contacts.
  4. Set the Conversions dataset id and post outcomes with a click id or hashed phone/email match key, then read attribution back.

​
Closing thought

The two funnels share one rule: attribution travels with the event. Capture the source ad at the entry point, carry it on the contact and conversation, and reporting — local or forwarded to Meta — joins spend to revenue without guesswork.