> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/en/cases/case-keitaro.md).

# Case: sending postbacks to Keitaro

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.

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

***

## 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”](/en/connect-bot.md). 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”](/en/connecting-channels.md).

{% hint style="info" %}
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.”
{% endhint %}

## 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`.

{% hint style="info" %}
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).
{% endhint %}

## 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”](/en/app/start-utm.md) 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”](/en/app/custom-fields.md) 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.

{% hint style="info" %}
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_(.+)$/`.
{% endhint %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

## 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](/en/app/automations.md)).

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”](/en/app/reports/events.md).
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.

{% hint style="info" %}
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.
{% endhint %}

***

## 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”](/en/app/automations.md) 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.