> 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-facebook.md).

# Case: sending conversions to Facebook (Meta Conversions API)

This guide walks through the whole path — from connecting a bot/channel to automatically sending server-side conversions to your Meta ad account — without writing a single line of code.

{% hint style="info" %}
**What you'll end up with:** a user clicks your ad link → lands in your bot or channel → performs the action you care about (joins, starts the bot, pays, etc.) → graspil automatically reports this to Meta's Conversions API (CAPI), bypassing the browser pixel. Facebook matches the event to a specific ad click and factors it into reporting and campaign optimization.
{% 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 %}

{% hint style="warning" %}
Conversions API is a server-side way of sending conversions, more reliable than the browser pixel (it isn't affected by ad blockers or ITP), but it still needs browser identifiers — `fbp`/`fbc` — to match an event to an ad click. You can only get those through a landing page with the intermediate page enabled (see Step 2).
{% 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. Set up a tlin landing page

A tlin.cc landing is a short link you put in your ads instead of a direct link to the bot/channel. It carries UTM tags from your ad and — important for this case — collects Meta's browser identifiers: `fbp` (browser identifier) and `fbc` (ad click identifier, derived from `fbclid`), which Facebook needs to match a server-side conversion to a specific ad impression/click.

Full guide on creating and configuring a landing — [“Landings (tlin.cc redirect)”](/en/app/landings.md). In short, here's what to do:

1. Create a landing for the bot/channel you want to drive traffic to.
2. In the landing's “Analytics and scripts” settings, specify the **Facebook Pixel ID** — the same Pixel/Dataset ID you'll use in Step 3.
3. Use the link to this landing (`tlin.cc/your-alias`) in your ads instead of a direct link to the bot/channel.

{% hint style="warning" %}
A landing is required here, and specifically the intermediate page must be enabled (not an instant redirect) — only there does tlin have time to initialize the pixel and capture `fbp`/`fbc` before redirecting to Telegram. You don't need to install the Facebook pixel code on your site separately — tlin does it for you from the ID you provide. Landings are a paid feature.
{% endhint %}

## Step 3. Route the identifiers into user fields

The `fbp` and `fbc` identifiers arrive in the bot deeplink's start parameter together with the rest of the UTM tags. To reference them as variables in automations, map them into user custom fields:

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 custom user fields beforehand (e.g. `fbp` and `fbc`) in the [“Custom fields”](/en/app/custom-fields.md) section, if they don't exist yet.
3. In the **“Parameters to custom fields”** block, add routes: parameter `fbp` → field `fbp`, parameter `fbc` → field `fbc`.

After that, the identifiers are available in automation templates as `{{ user.addition_fields.fbp }}` and `{{ user.addition_fields.fbc }}` — these are actually the default values the automation builder pre-fills.

## Step 4. Connect the Facebook (Meta) integration

1. Go to the **“Integrations”** section in your dashboard.
2. Find the **Facebook (Meta) Conversions API** card in the list of available integrations and click **“Configure.”**
3. Choose one of two connection methods:
   * **Events Manager token (faster)** — in Meta Events Manager, open your dataset/pixel → “Settings” → the Conversions API section → “Generate access token.” Enter the **Dataset (Pixel) ID** and the resulting **access token** in graspil. That token belongs to a system user and does not expire.
   * **Log in with Facebook (OAuth)** — click **“Log in with Facebook,”** authorize, and grant access (requires the `ads_management` and `business_management` permissions). graspil will discover the available datasets on its own — just pick the right one from the list.
4. Optionally, set a **test event code** — events will then land in Meta's “Test Events” tab and won't count toward reporting while you verify the setup. Clear the field once you're done testing.
5. Click **“Save,”** then use **“Test connection”** to confirm the integration can actually reach the dataset.

## Step 5. Create an automation

There's no ready-made template for Facebook 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 this use case, the natural default choices are:

   * `new_user` — the user started the bot, or
   * `user_chat_new` — the user joined the channel.

   But you can pick **any other event** — a payment (`successful_payment`), opening a mini app, clicking a button, or your own custom event. See the full list in the [“Event reference”](/en/app/reports/events.md).
3. Add an **“Integrations”** action block, choose the **“Facebook (Meta) Conversions API”** type, and fill in:
   * **Integration** — the one you connected in Step 4.
   * **Event name** — a standard Meta event (`Lead`, `Purchase`, `CompleteRegistration`, etc.) or your own name.
   * **Event source (action\_source)** — usually `website` when the user came from a landing; for events happening inside a conversation you can use `chat`.
   * **Source URL** — required when `action_source = website`, e.g. `{{ user.addition_fields.fb_source_url }}` (this field is also collected by the landing alongside `fbp`/`fbc`, same as in Step 3).
   * **User identifiers (user\_data)** — at least one is required. Technical identifiers (`fbp`, `fbc`) are sent as-is; enter personal data (email, phone, name, etc.) in plain form — graspil hashes it for you before sending.
   * **Skip when no identifiers resolve** — turn this on if you want organic users without `fbp`/`fbc` to simply skip this step instead of failing the scenario.
   * Optionally, you can also send the **value and currency**, arbitrary `custom_data` parameters, an `event_id` for deduplication with the browser pixel, and other fields.
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 data is automatically sent to Meta Conversions API — with no further action from you.

{% hint style="info" %}
Meta answers `200 OK` with `events_received` even when it later drops the event for a low match quality (e.g. a stale `fbc`). That means “event accepted,” not “conversion is guaranteed to be attributed” — check actual attribution in Events Manager.
{% endhint %}

***

## Any event, and end-to-end analytics

By default, the simplest setup is to send data on joining a channel or starting a bot — that covers the basic “ad → subscription” case. But you can choose literally any event as the trigger — a payment, a form submission, any custom event from your own system.

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

> Joined the channel → started the bot → made a purchase (conversion) → sent a `Purchase` event to Meta 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 Meta 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 conversions to Facebook (Meta) for your specific case.