> 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/app/start-utm.md).

# Processing start parameters (UTM)

## **What is the start parameter?**

The start parameter is the only way to pass data to the bot when it's launched. To use it, you need to add the string `?start={ your data }` to a regular bot link — such links are called Deep links.

<details>

<summary>How do I get this data in the bot?</summary>

Example bot link: `https://t.me/Graspil_bot?start=docs`

The value the bot receives: `docs`

When the user launches the bot, you receive an [Update](https://core.telegram.org/bots/api#update) of type\
[Message](https://core.telegram.org/bots/api#message). It contains a `text` parameter equal to `/start`; in the case of a deep link, the `text` parameter will equal `/start docs`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```json
{
   update_id":10000,
   "message":{
     "date":1441645532,
     "chat":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "message_id":1365,
     "from":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "text":"/start docs" // <----- data passed in start
   }
}
```

{% endcode %}

</details>

{% hint style="info" %}
There's a 64-character limit on the length of the string in the start parameter
{% endhint %}

## What is it used for in Graspil?

Telegram gives you a single opaque string in `start`. On top of it, Graspil recognizes a few conventions that let the same parameter drive several different features at once:

1. **Tracking user sources (UTM)** — split the string into `parameter=value` pairs to see where a user came from, filter, and build reports. This is the classic use case and the rest of this page is about it. Read more in our [blog](https://graspil.com/ru/post/utm_for_telegram_bot).
2. **Referral program registration** — a link like `?start=ref-<code>` (parameter name is configurable) registers the user as someone's referral. See [Referral system](/en/app/referral-system.md).
3. **Writing a value into a user's custom field** — you can route a specific `start` parameter straight into a [custom field](/en/app/custom-fields.md) instead of (or in addition to) a UTM label — see [Routing a parameter into a custom field](#routing-a-parameter-into-a-custom-field) below.
4. **Carrying data collected on your website or from an outside link** — the [website script](/en/app/website-script.md) and [tlin.cc redirect links](/en/app/landings.md) put a special `li1…` token into `start`/`startapp`; when the bot is launched, Graspil looks it up and attaches the UTM tags, geolocation, and custom fields collected earlier for that visitor.

These features can be combined: for example, a single link can carry a referral code in one parameter and a UTM source in another, and a `li1` token replaces the whole string when it's used, transferring everything that was collected on the site.

### How does graspil handle the start parameter?

Graspil uses this parameter to [track user sources](https://graspil.com/ru/post/utm_for_telegram_bot). Telegram doesn't support additional parameters, so we've added the ability to configure how this parameter is processed.

Since start can only carry a single string, we've added rules that let you split such a string into separate parameters.

For example, you need to pass the referral source and the source type (e.g. email). To do this, you can use a string like `start=source-news1_medium-email` and set up the appropriate processing rules.

In graspil, all such parameters are converted into `parameter=value` pairs — in other words, into a table that you can then work with (build reports, filter data).

| Parameter | Value |
| --------- | ----- |
| source    | news1 |
| medium    | email |

## Configuring start parameter processing

> You can configure processing rules for each bot. To do this, go to [My Bots](https://app.graspil.com/bots) and select the bot you need. On the bot information page, find the "UTM Tags" item (start processing rules) and go to its settings.

The processing rules settings page consists of two parts:

1. The settings form (more on this below)
2. A preview of the result. When you change the settings, you'll see how various links will be processed. You can add your own example links.

### Simplified mode

{% hint style="info" %}
This mode is selected by default for all new bots
{% endhint %}

Simplified mode doesn't process the start parameter and uses it as-is. This mode works well if you don't need additional parameters. For example, the string `start=docs` will be processed as follows:

<table><thead><tr><th width="246.5">Parameter</th><th>Value</th></tr></thead><tbody><tr><td>none</td><td>docs</td></tr></tbody></table>

{% hint style="warning" %}
In simplified mode the string isn't split into named parameters, so referral-code detection, source detection, and custom-field routing (all described below) don't work — turn simplified mode off if you need any of them.
{% endhint %}

#### Processing type

The string processing type lets you exclude certain parameters. This field offers 3 options:

1. **All parameters** — will take all parameters into account
2. **Only specified parameters** — will only take into account the parameters you specify
3. **All except specified parameters** — will take into account all parameters except the ones you specify

#### Parameter list

If "**processing type**" is set to "**only specified parameters**" or "**all except specified parameters**", you can specify the list of these parameters in this field.

#### Parameter separator and value separator

These are the characters that split the string to determine the parameters and their values. In the image below, <mark style="background-color:purple;">the parameter separator is "\_"</mark>, and <mark style="background-color:green;">the value separator is "—"</mark>

<figure><img src="/files/UlRoc8HwP0YORlnrhDRH" alt=""><figcaption></figcaption></figure>

The algorithm for processing the string <mark style="color:blue;">source</mark><mark style="background-color:green;">—</mark><mark style="color:orange;">google</mark><mark style="color:purple;background-color:purple;">\_</mark><mark style="color:blue;">campaign</mark><mark style="background-color:green;">—</mark><mark style="color:orange;">cpc</mark> is as follows:

1. Split the string by the parameter separator "<mark style="background-color:purple;">\_</mark>", getting:
   1. <mark style="color:blue;">source</mark><mark style="background-color:green;">—</mark><mark style="color:orange;">google</mark>
   2. <mark style="color:blue;">campaign</mark><mark style="background-color:green;">—</mark><mark style="color:orange;">cpc</mark>
2. Split the resulting parts by the value separator "<mark style="background-color:green;">—</mark>", getting:

| Parameter                                 | Value                                     |
| ----------------------------------------- | ----------------------------------------- |
| <mark style="color:blue;">source</mark>   | <mark style="color:orange;">google</mark> |
| <mark style="color:blue;">campaign</mark> | <mark style="color:orange;">cpc</mark>    |

### Routing a parameter into a custom field

On the same settings page, in the **"Parameters to custom fields"** block, you can route a specific parameter straight into a [custom field](/en/app/custom-fields.md) instead of treating it as a UTM label. This is useful for identifiers that are meaningless as a label — an external id, a partner number, and so on.

For each route you set:

* **Parameter** — the name of the parameter in the start string (as produced by the parsing rules above).
* **Field** — which custom field to write the value into.
* **Also keep as a UTM label** — off by default; when enabled, the value is written to the custom field *and* still appears among the UTM labels.
* **Do not overwrite a filled field** — first-touch behavior: if the field already has a value, a new value from `start` won't replace it.

{% hint style="info" %}
Field routing doesn't work in simplified mode, since the start string isn't split into named parameters there.
{% endhint %}

## What's next

* [Referral system](/en/app/referral-system.md) — turning a start parameter into referral tracking and rewards.
* [Custom fields](/en/app/custom-fields.md) — all the ways to fill a custom field, including routing described above.
* [Website script](/en/app/website-script.md) — carrying data collected on your site into the bot via `start`.