> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/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/ru/app/start-utm.md).

# Обработка параметров start (UTM)

## **Что такое параметр start?**

Параметр start - это единственный способ передать данные в бот при его запуске. Чтобы его использовать нужно к обычной ссылке на бот добавить строку `?start={ ваши данные }`, такие ссылки называются Deep links.

<details>

<summary>Как получить эти данные в боте?</summary>

Пример ссылки на бот: `https://t.me/Graspil_bot?start=docs`

Значение, которое получит бот `docs`

Когда пользователь запускает бот, вам приходит [Update](https://core.telegram.org/bots/api#update) типа\
[Message](https://core.telegram.org/bots/api#message). В нем есть параметр `text` который равен `/start`, в случае с deep link параметр `text` будет равен `/start docs`

**Пример**

{% 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" // <----- данные переданные в start
   }
}
```

{% endcode %}

</details>

{% hint style="info" %}
Существует ограничение в 64 символа на длину строки в параметре start
{% endhint %}

## Для чего он используется в Graspil?

Телеграм передаёт в `start` всего одну непрозрачную строку. Поверх неё Graspil поддерживает несколько соглашений, которые позволяют одному и тому же параметру управлять сразу несколькими функциями:

1. **Отслеживание источника пользователей (UTM)** — разбить строку на пары `параметр=значение`, чтобы видеть, откуда пришёл пользователь, фильтровать и строить отчёты. Это классический сценарий, ему посвящена основная часть этой страницы. Подробнее — в [блоге](https://graspil.com/ru/post/utm_for_telegram_bot).
2. **Регистрация в реферальной программе** — ссылка вида `?start=ref-<код>` (имя параметра настраивается) регистрирует пользователя как чьего-то реферала. См. [Реферальная система](/ru/app/referral-system.md).
3. **Запись значения в доп. поле пользователя** — конкретный параметр из `start` можно направить прямо в [доп. поле](/ru/app/custom-fields.md) вместо UTM-метки (или вместе с ней) — см. раздел «Маршрутизация параметра в доп. поле» ниже.
4. **Перенос данных, собранных на вашем сайте или по внешней ссылке** — [скрипт для сайта](/ru/app/website-script.md) и [редирект-ссылки tlin.cc](/ru/app/landings.md) кладут в `start`/`startapp` специальный токен `li1…`; при запуске бота Graspil находит по нему UTM-метки, геолокацию и доп. поля, собранные ранее для этого посетителя.

Эти сценарии можно совмещать: например, одна ссылка может нести реферальный код в одном параметре и UTM-источник в другом, а токен `li1` заменяет всю строку целиком и переносит всё, что было собрано на сайте.

### Как graspil обрабатывает параметр start?

Graspil использует этот параметр для [отслеживания источника пользователей](https://graspil.com/ru/post/utm_for_telegram_bot). Телеграм не поддерживает дополнительных параметров, поэтому мы добавили возможность настроить логику обработки данного параметра.

Так как в start можно передать только одну строку, мы добавили правила с помощью которых такую строку можно разделить на разные параметры.

Например, вам нужно передать источник перехода по ссылке и тип источника (например email). Для этого вы можете использовать строку такого вида `start=source-news1_medium-email` и задать нужные настройки для ее обработки.

В graspil все такие параметры преобразовываются в `параметр=значение` иными словами в таблицу, с которыми в дальнейшем можно работать (строить отчеты, фильтровать данные).

| Параметр | Значение |
| -------- | -------- |
| source   | news1    |
| medium   | email    |

## Настройка обработки параметра start

> Вы можете настроить правила обработки для каждого бота. Для этого перейдите в раздел [Мои боты](https://app.graspil.com/bots) и выберите нужного бота. На странице информации о боте найдите пункт "UTM-метки" (правила обработки start) и перейдите к их настройке.

Страница настройки правил обработки состоит из двух частей:

1. Форма настроек (о ней ниже)
2. Предпросмотр результата. При смене настроек вы увидите как будут обрабатываться те или иные ссылки. Вы можете добавить свои примеры ссылок.

### Упрощенный режим

{% hint style="info" %}
Этот режим выбран по умолчанию для всех новых ботов
{% endhint %}

Упрощенный режим не обрабатывает параметр start и используется как есть. Этот режим подойдет в том случае, если не нужны дополнительные параметры. Например, строка `start=docs` будет обработана так:

<table><thead><tr><th width="246.5">Параметр</th><th>Значение</th></tr></thead><tbody><tr><td>none</td><td>docs</td></tr></tbody></table>

{% hint style="warning" %}
В упрощённом режиме строка не разбивается на именованные параметры, поэтому определение реферального кода, определение источника и маршрутизация в доп. поля (всё описано ниже) не работают — выключите упрощённый режим, если вам нужна любая из этих функций.
{% endhint %}

#### Тип обработки

Тип обработки строки позволяет исключить какие-то параметры. Это поле дает 3 варианта выбора:

1. **Все параметры** — будет учитывать все параметры
2. **Только указанные параметры** — будет учитывать только те параметры, которые вы укажите
3. **Все кроме указанных параметров** — будет учитывать все параметры кроме тех, которые вы укажите

#### Список параметров

Если "**тип обработки"** равен "**только указанные параметры**" или "**все кроме указанных параметров**", то в этом поле вы можете задать список этих самых параметров.

#### Разделитель параметров и Разделитель значений

Это символы, которые будут делить строку для определения параметра и их значений. На изображении ниже <mark style="background-color:purple;">разделитель параметров равен "\_"</mark>, а <mark style="background-color:green;">разделитель значений равен "—"</mark>

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

Алгоритм обработки строки <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> будет следующий:

1. Делим строку по разделителю параметров "<mark style="background-color:purple;">\_</mark>", получаем
   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. Полученный результат делим по разделителю значений "<mark style="background-color:green;">—</mark>", получаем:

| Параметр                                  | Значение                                  |
| ----------------------------------------- | ----------------------------------------- |
| <mark style="color:blue;">source</mark>   | <mark style="color:orange;">google</mark> |
| <mark style="color:blue;">campaign</mark> | <mark style="color:orange;">cpc</mark>    |

### Маршрутизация параметра в доп. поле

На той же странице настроек, в блоке **«Параметры в кастомные поля»**, можно направить конкретный параметр прямо в [доп. поле](/ru/app/custom-fields.md), вместо того чтобы учитывать его как UTM-метку. Это удобно для идентификаторов, которые бесполезны как метка: внешний id, номер партнёра и т. п.

Для каждого маршрута задаются:

* **Параметр** — имя параметра в строке start (после разбора по правилам выше).
* **Поле** — в какое доп. поле записать значение.
* **Оставить также в UTM-метках** — по умолчанию выключено; если включить, значение запишется в доп. поле *и* останется среди UTM-меток.
* **Не перезаписывать заполненное поле** — поведение first-touch: если поле уже заполнено, новое значение из `start` его не заменит.

{% hint style="info" %}
Маршрутизация в доп. поля не работает в упрощённом режиме, так как в нём строка start не разбирается на именованные параметры.
{% endhint %}

## Что дальше

* [Реферальная система](/ru/app/referral-system.md) — как параметр start превращается в реферальный трекинг и начисления.
* [Доп. поля](/ru/app/custom-fields.md) — все способы заполнить доп. поле, включая маршрутизацию, описанную выше.
* [Скрипт для сайта](/ru/app/website-script.md) — перенос данных, собранных на вашем сайте, в бота через `start`.