Case: sending postbacks to Keitaro

Step-by-step guide: how to connect a bot or channel and automatically send conversion postbacks to your Keitaro tracker by click_id (subid) whenever any event happens — registration, payment

This guide walks through the whole path — from connecting a bot/channel to automatically sending conversion postbacks to your Keitaro tracker — without writing a single line of code.

What you'll end up with: a user clicks a link from a Keitaro campaign → lands in your bot or channel → performs the action you care about (registration, payment, etc.) → graspil automatically sends a postback to Keitaro with the click_id. Keitaro records the conversion and forwards it on its own to Facebook, Google Ads, TikTok and other ad platforms through its own modules — no separate integrations with ad platforms are needed on your side.

If anything is unclear along the way, open the AI assistant chat in your dashboard and describe what you're trying to do in your own words — it will guide you through the specific steps for your situation.

---

Step 1. Connect a bot or channel

For graspil to see what your users do, you first need to connect a resource — a bot or a Telegram channel.

• Detailed guide on connecting a bot — “Bot connection”. There are three ways: auto-setup with a token, proxying, or connecting via API — pick whichever is convenient.

• Detailed guide on connecting a channel — “Connecting channels”.

You can connect both a bot and a channel at the same time — for example, to track the whole chain “joined the channel → started the bot.”

Step 2. Point your Keitaro campaign at the bot

Unlike the Yandex Metrika, Google Analytics, and Facebook cases, you don't need a tlin landing here — Keitaro already generates its own click identifier (click_id, a.k.a. subid), and all you need to do is pass it into the bot's deeplink start parameter.

1. In your Keitaro campaign, set the final action (flow/offer result) to redirect straight to your bot, e.g. https://t.me/your_bot?start=VALUE, where VALUE contains Keitaro's subid macro — for example t.me/your_bot?start={subid}.

   • If you need to pass anything besides subid in the start parameter, combine the values with a separator of your choice — in Step 3 you can extract just the click_id from that string using a regular expression.

2. Publish the campaign and run a test click to confirm the user actually lands in the bot and the start parameter contains a non-empty subid.

The exact subid (or sub_id) macro syntax and flow setup depend on your Keitaro version — if you're unsure, check with your Keitaro specialist or the tracker's own documentation (linked from the integration settings in graspil, Step 3).

Step 3. Route the click_id into a user field

To reference the click_id as a variable in automations, map it into a user custom field:

1. Open the bot page → “UTM tags” section (start parameter processing rules) — see “Configuring start parameter processing” for details. Parameter mapping only works in the mode where the start string is parsed into parameters, not in simplified mode.

2. Create a custom user field beforehand (e.g. keitaro_click_id) in the “Custom fields” section, if it doesn't exist yet.

3. In the “Parameters to custom fields” block, add a route: the parameter carrying your subid → field keitaro_click_id.

After that, the identifier is available in automation templates as {{ user.addition_fields.keitaro_click_id }} — this is actually the default value the automation builder pre-fills into the Keitaro node.

If the start parameter carries more than just subid (for example, you combined several values with your own separator), both the integration and the automation node have a click_id regular expression field — the click_id is taken from the first capture group, e.g. /^kt_(.+)$/.

Step 4. Connect the Keitaro integration

1. Go to the “Integrations” section in your dashboard.

2. Find the Keitaro card in the list of available integrations and click “Configure.”

3. Fill in:

   • Tracker domain — your Keitaro address, e.g. https://track.example.com.

   • Postback key — the key from Keitaro itself: Settings → Postback URL.

   • Optionally — a default currency (used when the automation node leaves currency empty) and a postback path, if your Keitaro doesn't use the default {key}/postback format.

4. Click “Save,” then use “Send test postback” to confirm the domain and key are correct.

The test postback uses a random subid, so no real conversion is attributed by it — a successful response only confirms the domain and postback key are working; actual click matching is verified once the live automation runs.

Step 5. Create an automation

There's no ready-made template for Keitaro in the automation catalog yet — you'll need to build the scheme manually. This is done in the “Automations” section (full documentation).

1. Open “Automations” → “Create automation”, and select the bot/channel.

2. Open the builder and add an “By event” trigger. For Keitaro, it's usually the events closer to the end of the funnel — what the advertiser actually pays for — that matter most:

   • successful_payment — a payment, or

   • your own custom event (registration, deposit, etc.).

   But you can also pick new_user/user_chat_new if an early conversion (a lead) matters to you. See the full list in the “Event reference”.

3. Add an “Integrations” action block, choose the “Keitaro” type, and fill in:

   • Integration — the one you connected in Step 4.

   • subid (click_id) — defaults to {{ user.addition_fields.keitaro_click_id }} (the field from Step 3).

   • Conversion status — what to record in Keitaro: lead, sale, reg, deposit, rejected, trash, or your own status.

   • Skip users without a click_id — turn this on if you want organic traffic without a subid to simply skip this step instead of failing the scenario.

   • Optionally, you can also send the amount (payout) and currency, a tid (to record a repeat conversion without overwriting the previous one), and arbitrary extra parameters (sub_id_1…sub_id_30, em, ph, fn, ln) — Keitaro forwards those on to its own integrations, including as user_data for Facebook CAPI.

4. Connect the trigger and the action with an arrow, click “Run test” to check the scheme, then publish the automation.

From this point on, every time the chosen event happens, the postback is automatically sent to Keitaro — with no further action from you.

Keitaro answers 200 OK even when the subid doesn't match any click (for example, for an organic user with no tag). That means “the tracker accepted the request,” not “the conversion is guaranteed to be attributed” — Keitaro's short reply is kept in the automation's execution log, so you can see exactly what the tracker said.

---

Any event, and end-to-end analytics

By default, it makes more sense for Keitaro to send the postback on an event that's actually monetized (a payment, a deposit, a qualified lead) rather than simply on entering the bot — that's closer to how offer payouts are usually calculated. But you can choose literally any event as the trigger.

You can also build an end-to-end chain of several steps, for example:

Started the bot → nurtured inside the bot → made a purchase (conversion) → sent a sale postback to Keitaro with the payment's amount and currency

This uses the “Condition” and “Wait for event” blocks inside a single automation (for instance, waiting for a payment after the bot start, with a timeout) — see the “Automations” section for details. That way Keitaro only receives a conversion once the user has gone through the entire chain, not just on the first step.

---

Need help setting this up?

If something isn't working or you still have questions, contact graspil support — we'll help you set up sending postbacks to Keitaro for your specific case.