Events and conversions: the money layer of your funnel

Clicks are a cost until an event proves they paid off. In Leadgram every conversion - a bot start, a registration, a deposit - is an event tied to one specific click, and that link drives everything downstream: revenue in Reports, postbacks to partner trackers, the server-side conversions you feed back to Meta and Google, and a push notification back to the subscriber who converted, if your flow wires one up. Get events flowing correctly and the rest of the tracker starts telling you the truth about your spend.

Event types

• Funnel events - click, land, bot_start, channel_join, join_request, first_dm, miniapp_launch. They describe how a user moves through your Telegram funnel.
• Conversion events - lead, registration, deposit, ftd, purchase. These are the events advertisers pay you for.
• Custom events - custom_1 through custom_8 for anything offer-specific.

Most conversion events also advance the click's status on the Clicks page: Clicked → Landed → Started → Registered → Lead → Deposit → FTD. Status only moves forward - a late registration arriving after an ftd never downgrades the click. purchase is the exception: it's billed and reported like any other conversion, but it never touches click status. Neither do channel_join or the custom_* events - all three get recorded, they just don't feed the funnel-stage ladder.

How events arrive

1. S2S / API. Your backend (or the advertiser's postback script) calls POST /api/events with the clickId, the event type, and optionally payout and nonce. Create an API key under Settings → API keys for external tools like Keitaro or your own scripts. Pull events back out with GET /api/events (paginated, filterable by type) when you need to reconcile what fired against your own records.
2. Flows. Drop an Event node into a Message Flow and the event fires automatically when a subscriber reaches that step - registrations and deposits straight out of your Telegram funnel, no code.

Deduplication is deterministic: the same clickId + type without a nonce is treated as a retry of the same conversion and never creates a second row, a second charge or a duplicate Meta purchase. A genuine repeat conversion (a second deposit from the same click) must send a unique nonce.

The billing gate

Recording an event and delivering it downstream are two different things. Every event row carries a billing_status: it starts pending while the debit runs, then settles to charged or free. CAPI dispatch, postbacks and event-triggered pushes to the converting subscriber only fire once that status resolves to charged or free - a paused org or an empty balance leaves the row blocked (a failed debit leaves it error), and the event sits in the database without ever reaching Meta, Google, your postback endpoint or the subscriber.

The payout field

Pass payout (USD, up to two decimals) with every paying conversion. It feeds two places:

• Reports revenue - the revenue column is the sum of payouts across confirmed events.
• Google Ads - payout becomes conversionValue on the server-side conversion, so Smart Bidding optimizes toward real money.

Postbacks don't carry payout. The macros available to partner trackers are {click_id}, {event_type}, the sub-chain and the platform-native click ids - see Postbacks for the full list. If your tracker needs the conversion amount, pass it back through your own integration.

What the CAPI column means

The Dashboard's Recent events table shows a CAPI status per event: Sent means every ad platform matched to the campaign accepted the conversion; Pending means at least one delivery is still queued or failing. Per-platform detail - attempts, last error, one-click re-fire - lives on Delivery Health.

The safe test event

On the Facebook page each Meta CAPI account has a Send test event button. It fires a synthetic Purchase with your Test Events code from Meta Events Manager, so it shows up in the Test Events tab and never touches ad optimization, attribution or billing. It's the fastest way to prove your pixel and token work before spending a dollar. The button refuses to fire without a code - an uncoded event would count as real.

Common pitfalls

• Skipping nonce on repeat conversions - the second deposit is silently treated as a retry and dropped.
• Sending events without payout - Reports revenue stays at zero and Google gets valueless conversions.
• Firing registration for a click that already reached ftd and expecting the status to change - it won't, by design.
• Expecting purchase to move the click's funnel status - it never does, even though it's billed like any other conversion.
• Reading Pending in the CAPI column as a bug - check Delivery Health first; it usually names the exact platform error.
• Assuming a recorded event was delivered - blocked, error and pending billing states mean it never reached CAPI, postbacks or pushes.