---
title: "Трекинговые ссылки для экосистемы Telegram"
description: "Как настроить трекинговые ссылки и макросы AdsGram для кампаний в экосистеме Telegram, включая goaltype и тестирование конверсий."
outline: [2,4]
---
# Трекинг для ссылок внутри Telegram
Для более детального отслеживания результативности рекламных кампаний и корректной атрибуции источников целевых действий рекомендуется использовать **систему аналитики**.

## Макросы, которые раскрывает AdsGram
Для детального трекинга используйте макросы. AdsGram автоматически заменит их на реальные данные в вашей трекинговой ссылке.
- `{campaign_id}`
- `{banner_id}`
- `{publisher_id}`
- `{useragent}`
- `{device_model}`
- `{click_id}`
- `{ip}`
- `{campaign}` — название кампании
- `{os_version}`
- `{lang}`
- `{gaid}`
- `{idfa}`
- `{record_data}`

::: warning ВНИМАНИЕ:
Для корректной работы API подтверждения конверсий для ссылок внутри Telegram в ссылке рекламной кампании должен присутствовать обязательный макрос `{campaign_id}`. Если обязательный макрос отсутствует, отслеживание конверсий работать не будет.
:::

> [!IMPORTANT] ВАЖНО
> Макрос `{publisher_id}` раскрывается только как уникальный идентификатор издателя — без указания его названия или другой идентифицирующей информации.

> [!IMPORTANT] ВАЖНО
> Если ваша посадочная ссылка открывает TMA через параметр start, используйте, например, следующую ссылку:
> ```
>https://t.me/[name_of_the_bot]?start=[unique_referral_link]_{campaign_id}_{banner_id}_{publisher_id}_{click_id}_{record_data}
> ```

Кабинет подсвечивает добавленные в ссылку макросы <img src="../../images/icons/added_macros.png" alt="Added macros" width="18" style="display: inline" />  и пропущенные <img src="../../images/icons/missed_macros.png" alt="Missed macros" width="18" style="display: inline" />.

![Selected macroses](./images/selected_macroses.webp =500x)

## Настройка постбеков о конверсиях для ссылок внутри Telegram
> [!WARNING] ВНИМАНИЕ
> Инструкции в этом разделе не применимы к кампаниям в **Telegram Ads**. Подробнее о трекинге конверсий для ссылок внутри Telegram в кампаниях Telegram Ads читайте в разделе [Трекинг Telegram Ads](./tg-ads-tracking-links#трекинг-конверсии-для-ссылок-внутри-telegram-в-кампаниях-telegram-ads).

### Параметры:
- `token` — Уникальный токен, связанный с вашим аккаунтом AdsGram. Доступен в рекламном кабинете. При необходимости его можно сгенерировать повторно.

  **Где получить token:**
  1. Откройте рекламный кабинет AdsGram.
  1. Нажмите на профиль в правом верхнем углу.
  1. Найдите параметр `token` и скопируйте его, нажав на кнопку <img src="../../images/icons/copy.png" alt="Copy" width="18" style="display: inline" />.

  ![Copy macros](./images/copy_macros.webp =200x)
- `tgid` — Telegram ID пользователя, совершившего переход по рекламной ссылке.
- `campaignid` — ID рекламной кампании AdsGram, к которой относится конверсия. Соответствует значению макроса `{campaign_id}`, передаваемому в рекламной ссылке. AdsGram подставляет значение макроса при переходе пользователя по ссылке.
- `goaltype` — Параметр, указывающий тип конверсии (этап воронки), который помогает сегментировать различные целевые действия пользователя. Принимает целочисленные значения от 1 до 3.

  #### Использование goaltype:
  1. Определите этапы воронки в вашем продукте или сервисе.
  1. Сопоставьте этапы со значениями goaltype:
      - 1. Регистрация
      - 2. Первый депозит/покупка
      - 3. Повторный депозит/покупка
  1. Настройте отправку конверсий на нужных этапах пользовательского пути.
  1. Добавьте параметр goaltype к вашему API-запросу при отправке.
  1. Используйте данные в аналитике для детального анализа эффективности по разным типам конверсий.

### Как настроить отправку конверсий:
1. **Выберите кампанию.** Используйте существующую активную кампанию или создайте новую.
1. **Настройте рекламную ссылку.** Убедитесь, что в ней присутствует макрос `{campaign_id}`.
1. **Получите token.** Скопируйте уникальный токен из рекламного кабинета AdsGram.
1. **Настройте отправку постбеков.** На стороне вашего сервера отправляйте API-запрос в AdsGram, когда пользователь выполняет целевое действие.
1. **Передавайте правильный тип конверсии.** Указывайте соответствующее значение `goaltype`, если хотите различать этапы воронки.
1. **Проверьте интеграцию.** Выполните тестовый сценарий из раздела **Тестирование интеграции** и убедитесь, что конверсии поступают в статистику AdsGram.

#### Пример API-запроса:
```
GET
https://api.adsgram.ai/confirm_conversion?token=YOUR_UNIQUE_TOKEN&tgid=98110997&goaltype=2&campaignid=72156
```
В примере передаётся конверсия типа `2` (например, первый депозит или покупка).

Замените `YOUR_UNIQUE_TOKEN` на токен вашего аккаунта, `98110997` — на Telegram ID пользователя, перешедшего по рекламной ссылке, а `72156` — на ID вашей рекламной кампании.

Ожидаемый ответ: `200 OK` — успешная регистрация конверсии.

### Тестирование интеграции
Чтобы протестировать отслеживание конверсий, выполните следующие шаги:
1. Создайте или выберите кампанию и настройте рекламную ссылку в соответствии с документацией. Убедитесь, что в ссылке передаётся макрос `{campaign_id}`.
1. Дождитесь нескольких кликов по рекламной ссылке.
1. Получите Telegram ID (`tgid`) пользователя, который перешёл по ссылке выбранной кампании.
1. Отправьте тестовый постбек вручную. Передайте параметр `goaltype=1`, действительный `token`, Telegram ID пользователя в параметре `tgid` и ID тестовой кампании в параметре `campaignid`.
1. Убедитесь, что запрос обработан успешно, а конверсия появилась в статистике AdsGram для выбранной кампании.

- **Конверсия появилась в статистике** — интеграция успешно настроена и работает.
- **Сервер вернул ошибку** — проверьте URL запроса, `token`, значения параметров `tgid`, `campaignid` и `goaltype`.
- **Запрос выполнен успешно, но конверсия не появилась** — статистика обновляется раз в час. Если спустя час данные не появились, напишите в поддержку AdsGram или своему менеджеру. К обращению обязательно приложите логи запроса и ответа.
