Навык (skill) для ИИ для работы с сервисом

Эта инструкция помогает поручить ИИ-агенту рутину в боте «Откуда подписки». Вы пишете задачу обычными словами, а агент делает её сам. Ссылки на канал, id и JSON собирать не нужно.

Что можно поручить агенту:

создать яндекс- или VK-интеграцию;
изменить настройки уже созданной ссылки;
сделать трекинг-ссылку;
посмотреть данные каналов и список вступлений;
посмотреть статистику подписчиков на Pro;
получить ссылку на оплату или продление Pro;
отправить глубокую цель по человеку в канале.

Навык (skill) — это запись инструкции у агента. Один раз отправляете ему эту страницу, и дальше он выполняет такие задачи сам.

В этой инструкции мы по шагам разберём, как подключить навык и ставить агенту задачи обычными словами.

Как пользоваться навыком

Шаг 1 — Отправьте агенту ссылку на эту страницу

Скопируйте адрес этой страницы и отправьте его ИИ-агенту. Попросите сделать навык (skill) по ней для бота «Откуда подписки».

Ссылка: https://doc.tgtrack.ru/doc/ai-skill

Шаг 2 — Напишите, что нужно сделать

Дальше в чате пишите задачу обычными словами. Например: «сделай новую интеграцию в канале Реклама заработает».

Агент сам запросит персональный ключ и напишет, что нажать в боте.

Шаг 3 — Создайте персональный ключ, когда агент попросит

Если ключа ещё нет, агент остановится и попросит его создать. Сделайте так:

Откройте бота «Откуда подписки»: tgTrack_bot.
Отправьте команду /personal_api
Нажмите Создать персональный ключ.

Команда /personal_api и кнопка «Создать персональный ключ»

Пришлите ключ агенту в этот же чат. Бот пришлёт ключ в ответ.

Ответ бота с персональным ключом и кнопка «Перевыпустить персональный ключ»

Откройте бота «Откуда подписки»: бот в MAX.
Отправьте команду /personal_api
Нажмите Создать персональный ключ.

Команда /personal_api и кнопка «Создать персональный ключ» в MAX

Пришлите ключ агенту в этот же чат. Бот пришлёт ключ в ответ.

Ответ бота в MAX с персональным ключом и кнопка «Перевыпустить персональный ключ»

Ключ — секрет

Не показывайте ключ целиком в других чатах, тикетах и логах. Если нужно перевыпустить ключ: та же команда /personal_api, кнопка Перевыпустить. Старый ключ перестаёт работать сразу.

Если агент просит сделать первую яндекс-интеграцию в боте

Так сохраняется доступ к Яндекс.Метрике. Сделайте одну интеграцию вручную, дальше агент создаст остальные сам.

Telegram: /integration_yandex
MAX: /yandex

Если канал ещё не подключён к боту:

Telegram: /add_channel
MAX: /add_chat

Для ИИ-агента

примечание

Человеку этот раздел читать не обязательно. Дальше — инструкция для ИИ-агента.

Версия инструкции: 14. Дата инструкции: 2026-10-22.

Прочитай страницу целиком и сделай навык. В навык запиши «Версия инструкции» и «Дата инструкции» с этой страницы. Человек формулирует задачу обычными словами. Запросы к API отправляешь ты.

Перед каждой задачей заново открой https://bot-api.tgtrack.ru/personal-api.md и сравни версию и дату со значениями в навыке. Если номер или дата на странице другие, обнови навык по свежей инструкции и только потом выполняй задачу. По устаревшему навыку запросы не отправляй.

Один контракт для Telegram и MAX. Отличаются только базовый URL и вид ссылки на канал.

Ключ даёт создавать яндекс- и VK-интеграции, менять настройки уже созданных ссылок, читать данные каналов, трекинг-ссылки и статистику подписчиков по каналу с Pro, получать ссылку на оплату Pro, читать вступления за период и отправлять глубокую цель по человеку в канале. Каналы — те, к которым у владельца ключа есть доступ. Чат-методы (user_did_start_bot, send_reach_goal, вебхуки) этим ключом вызывать нельзя: у send_reach_goal канал берётся из чат-ключа. Глубокая цель персональным ключом — это send_reach_goal_in_chat, канал передаётся в теле.

Если ключа ещё нет, API не вызывай. Остановись и попроси человека создать персональный ключ. Напиши ему эти шаги:

Откройте бота «Откуда подписки»: в Telegram это бот tgtrack, в MAX — бот tgtrack.
Отправьте команду /personal_api.
Нажмите «Создать персональный ключ».
Пришлите ключ в этот чат.

Ключ — секрет. Храни его в секрете навыка. В ответах человеку ключ целиком не показывай, если он сам не попросил. В другие чаты, тикеты и логи ключ не пиши.

Перевыпуск: та же команда /personal_api, кнопка «Перевыпустить». Старый ключ перестаёт работать сразу. После перевыпуска попроси новый ключ.

Если при создании яндекс-интеграции пришёл ответ No live Yandex Metrika access. Create one integration with /integration_yandex in the bot first., попроси человека один раз сделать интеграцию в боте. Объясни, что так сохраняется доступ к Яндекс.Метрике, и следующие интеграции создашь ты.

Telegram: /integration_yandex
MAX: /yandex

Если канал не найден, код 405, попроси человека подключить его к боту:

Telegram: /add_channel
MAX: /add_chat

1. Запрос

POST, тело — JSON.

Персональный ключ и имя метода стоят в пути. Заголовки X-Api-Key, Authorization и query token не используются. Вместо <ключ> подставь персональный ключ. Полный адрес каждого метода указан в его разделе.

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_channels
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_channels

Успех:

{
  "status": "OK",
  "data": {}
}

Ошибка:

{
  "status": "error",
  "error_code": 422,
  "error_description": "Unprocessable entity",
  "error_details": "текст причины"
}

Коды:

code	когда
400	нет метода или пустое тело
401	ключ не передан или неверный
402	ключ отозван
403	нет доступа к каналу, ключ не того типа, либо на канале нет Pro
405	канал не подключён к боту
409	такое имя в канале уже есть
422	поля не прошли проверку, нет доступа к Метрике, Яндекс отказал, период слишком длинный, запрос статистики оборвался по времени или платёжный сервис не отдал ссылку
429	слишком много запросов. `retryAt` — дата и время по Москве, когда можно повторить. `retryIn` — через сколько секунд

Поле channel — ссылка на канал или его id в мессенджере. Внутренний id tgtrack не подходит. channelID из get_channels копируйте строкой, как есть.

Telegram: https://t.me/username, пригласительная https://t.me/+... или id чата, например -1001234567890
MAX: ссылка max.ru/... или id чата в MAX

2. Лимиты

Только персональный ключ: не больше 3 запросов в секунду, 60 в минуту и 1000 в сутки. При превышении код 429. Рядом retryAt — дата и время по Москве, например 21.10.2026 23:15:42 MSK, и retryIn — через сколько секунд можно повторить. error_details: retry at <retryAt>, in <retryIn> seconds.

Пачку запросов не отправляйте параллельно: в одну секунду проходят три вызова.

3. get_channels

Список каналов, к которым у владельца ключа есть доступ. Тело не нужно.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_channels
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_channels

По ответу агент сопоставляет имя из запроса пользователя с полем name и дальше передаёт channelID в поле channel других методов.

Успех, поле data:

{
  "channels": [
    {
      "channelID": "-1001234567890",
      "name": "Реклама заработает",
      "username": "reklama",
      "link": "https://t.me/reklama",
      "type": "channel",
      "addedAt": 1710000000,
      "subscribers": 15230,
      "subscribersAdjustment": -120,
      "initialSubscribers": 10000,
      "pro": true,
      "proUntil": 1762000000,
      "timeShift": 10800,
      "subscribersChangedAt": 1761000000
    }
  ]
}

channelID в Telegram — id чата, в MAX — id чата MAX. username пустой, если у канала нет публичного адреса. link — публичный адрес: в Telegram https://t.me/ и username, в MAX https://max.ru/ и username. У закрытого канала link пустой. Пригласительную ссылку метод не ищет: без публичного адреса и без уже сохранённой пригласительной канал в channel по id не создаётся, передайте пригласительную ссылку.

type: channel, group, bot, business или private. В списке не только каналы.

addedAt, proUntil и subscribersChangedAt — unix-секунды. Человеку показывай календарную дату, не число. proUntil равен null, если канал ни разу не оплачивали. subscribersChangedAt равен null, если приходов и уходов ещё не было. initialSubscribers равен null, если аудитория на момент подключения неизвестна.

subscribers — сколько подписчиков сервис считает сейчас. Это не свежий запрос в Telegram или MAX. subscribersAdjustment — накопленная корректировка со знаком, она уже входит в subscribers, складывать их не нужно. Плюс — число подняли до факта в мессенджере, минус — опустили, в том числе когда Telegram удалил пользователей.

pro — Pro включена сейчас, без льготных дней после окончания оплаты. timeShift — пояс канала, секунды от UTC. «Сегодня» и «вчера» для статистики считай по нему.

4. get_payment_link

Страница оплаты Pro одного канала. Подходит и для канала без Pro, и для продления уже оплаченного.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_payment_link
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_payment_link

Тело:

{
  "channel": "https://t.me/username"
}

channel — ссылка или id, как в остальных методах. Плательщик — владелец ключа. На странице периоды 1, 3 и 12 месяцев. Скидка этого пользователя, если она есть, уже внутри ссылки.

Успех, поле data:

{
  "paymentUrl": "https://...",
  "channelID": "-1001234567890",
  "name": "Реклама заработает",
  "pro": false,
  "proUntil": null
}

paymentUrl — страница оплаты этого канала. Ссылку самому не собирай. name, pro и proUntil те же, что в get_channels.

Если платёжный сервис не вернул адрес, код 422, error_details: payment link could not be created. Тот же запрос сразу не повторяй.

5. create_yandex_integration

Создаёт яндекс-интеграцию и возвращает код ссылки и тег скрипта для сайта.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/create_yandex_integration
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/create_yandex_integration

Тело:

{
  "name": "Директ — кампания 1",
  "counterID": "12345678",
  "channel": "https://t.me/username",
  "autoFollow": false,
  "goalToChannel": "toTelegram",
  "goalOpen": "userDidOpenTelegram",
  "goalSub": "userDidSubscribe"
}

Обязательны name, counterID, channel. Остальные поля можно не передавать: подставятся значения по умолчанию из примера. Имена целей по умолчанию в Telegram и MAX одни и те же.

channel — ссылка или id канала в мессенджере. Id берите из get_channels (channelID) и передавайте строкой, не числом.

{
  "name": "Директ — кампания 1",
  "counterID": "12345678",
  "channel": "-1001234567890"
}

Ссылка вместо id: Telegram https://t.me/username или https://t.me/+..., MAX https://max.ru/.... У закрытого канала без публичного адреса и без уже сохранённой пригласительной id не хватает: передайте пригласительную ссылку.

counterID — только цифры, длина 6–9. Имена целей уникальны, латиница, цифры и _, не длиннее 45 символов. name уникально внутри канала, не длиннее 100 символов.

Успех, поле data:

{
  "linkID": "AbCdEf",
  "script": "<script src=\"https://...\" type=\"text/javascript\" defer></script>"
}

Если живого доступа к Метрике нет, error_details: No live Yandex Metrika access. Create one integration with /integration_yandex in the bot first. В MAX текст тот же по смыслу: сначала одна интеграция через бота.

OAuth-токен Яндекса в запрос не передаётся.

6. get_yandex_integrations

Список яндекс-интеграций канала. В channel та же ссылка или тот же id, что и при создании.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_yandex_integrations
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_yandex_integrations

{
  "channel": "-1001234567890"
}

Успех, поле data:

{
  "integrations": [
    {
      "name": "Директ — кампания 1",
      "linkID": "AbCdEf",
      "counterID": "12345678",
      "autoFollow": false,
      "goalToChannel": "toTelegram",
      "goalOpen": "userDidOpenTelegram",
      "goalSub": "userDidSubscribe",
      "script": "<script src=\"https://...\" type=\"text/javascript\" defer></script>",
      "autoFollowPost": -1,
      "autoFollowRate": 0,
      "autoApprove": -1,
      "goalStayed": "userStayedInChannel",
      "sendGoalStayed": false,
      "stayedCheckDelay": 86400,
      "goalUnsubscribe": null,
      "unsubscribeWindow": null
    }
  ]
}

autoFollow — переброс реально включён: доля больше 0 и пост не выключен. В Telegram пост -1 выключает переброс, 0 — конец канала. В MAX пост null выключает, "0" — конец канала. Остальные поля настроек те же, что у set_integration_settings.

7. create_vk_integration

Создаёт VK-интеграцию и возвращает код ссылки и тег скрипта для сайта. Токен VK не нужен.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/create_vk_integration
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/create_vk_integration

{
  "name": "VK — кампания 1",
  "pixel": "12345678",
  "channel": "https://t.me/username",
  "autoFollow": false,
  "goalToChannel": "toTelegram",
  "goalOpen": "userDidOpenTelegram",
  "goalSub": "userDidSubscribe"
}

Обязательны name, pixel, channel. pixel — только цифры: в Telegram длина 6–9, в MAX длина 1–20. Цели можно не передавать. По умолчанию Telegram: toTelegram, userDidOpenTelegram, userDidSubscribe. MAX: toMax, userDidOpenMax, userDidSubscribe. Имена целей уникальны, латиница, цифры и _, не длиннее 45 символов. name уникально внутри канала, не длиннее 100 символов.

autoFollow: true включает переброс на конец канала с долей 1. false или отсутствие поля — переброс выключен.

Успех, поле data: linkID и script, как у яндекс-интеграции.

8. get_vk_integrations

Список VK-интеграций канала.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_vk_integrations
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_vk_integrations

{
  "channel": "-1001234567890"
}

Элемент data.integrations[]: name, linkID, pixel, script и те же поля настроек, что у яндекс-списка. Вместо counterID здесь pixel.

9. set_integration_settings

Меняет настройки уже созданной ссылки. Непереданные поля не меняются.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/set_integration_settings
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/set_integration_settings

Обязательны channel и linkID. linkID — публичный код из списка интеграций или трекинг-ссылок. Нужно хотя бы одно настраиваемое поле.

Название, автопереброс и автоприём можно ставить любой ссылке канала. Имена целей, отписки и «остался в канале» — только у интеграции Яндекса или VK. На обычной трекинг-ссылке эти поля дают 422, error_details: integration required.

{
  "channel": "-1001234567890",
  "linkID": "AbCdEf",
  "name": "Новое название",
  "autoFollow": true,
  "autoApprove": 60,
  "goalToChannel": "toTelegram",
  "sendGoalStayed": true,
  "unsubscribe": true
}

name — новое название ссылки, до 100 символов, уникально в канале. Занято другой ссылкой — 409.

autoFollow: false выключает переброс. Вместе с autoFollowPost или autoFollowRate — 422. autoFollow: true без поста и доли включает переброс на конец канала с долей 1. autoFollowPost в Telegram — целое: -1 выкл, 0 конец канала, больше нуля — номер поста. В MAX — строка: пустая выключает, "0" — конец канала, иначе id поста. autoFollowRate — доля от 0 до 1.

autoApprove: -1 выключен, 0 сразу, больше нуля — задержка в секундах. В ответе выключенное состояние всегда -1.

Имена целей: goalToChannel, goalOpen, goalSub, goalStayed, goalUnsubscribe. Латиница, цифры и _, до 45 символов, все имена одной интеграции уникальны. Для Яндекса новое имя ещё и заводится в Метрике, если такой цели нет. Отказ Метрики имя не откатывает: в goalsCreated у этого поля false.

unsubscribe: true включает отписки. Без окна ставится 7 суток (604800 секунд) и имя userDidUnsubscribe, если своего ещё нет. unsubscribeWindow — 0 выключает, иначе от 86400 до 1814400 секунд (1–21 сутки). unsubscribe: false выключает и стирает имя. Вместе с окном или goalUnsubscribe — 422.

sendGoalStayed: true включает цель «остался в канале». Имя по умолчанию userStayedInChannel. stayedCheckDelay — секунды строго больше нуля; без поля остаётся текущая задержка, а если её не было — сутки. sendGoalStayed: false только выключает передачу.

Пиксель VK и счётчик Яндекса этим методом не меняются.

Успех, поле data: linkID, name и сохранённые поля настроек. unsubscribeWindow равен null, если отписки выключены. goalUnsubscribe равен null, если имя не задано. goalsCreated есть только если в запросе менялись имена целей Яндекса или включались отписки либо «остался в канале».

10. create_tracking_link

Создаёт обычную трекинг-ссылку (посев, сайт, соцсеть), без рекламного кабинета.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/create_tracking_link
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/create_tracking_link

{
  "name": "Посев — канал партнёра",
  "channel": "https://t.me/username"
}

Обязательны name и channel. В channel ссылка или id канала, как в create_yandex_integration. Имя уникально в канале, не длиннее 100 символов.

Успех, поле data:

{
  "name": "Посев — канал партнёра",
  "linkID": "AbCdEf",
  "url": "https://click.example/AbCdEf",
  "urlMessenger": "https://t.me/bot?start=TL...",
  "clickCount": 0,
  "subscribersCount": 0
}

url — ссылка вне мессенджера. urlMessenger — ссылка для размещения внутри Telegram или MAX. clickCount — клики по ссылке, subscribersCount — подписки по ней. Оба числа из таблицы ссылок. У только что созданной ссылки они нули.

11. get_tracking_links

Список уже созданных трекинг-ссылок канала. Нужен, чтобы не упереться в занятое имя. В channel ссылка или id канала.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_tracking_links
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_tracking_links

{
  "channel": "-1001234567890"
}

Успех, поле data:

{
  "links": [
    {
      "name": "Посев — канал партнёра",
      "linkID": "AbCdEf",
      "url": "https://click.example/AbCdEf",
      "urlMessenger": "https://t.me/bot?start=TL...",
      "clickCount": 120,
      "subscribersCount": 34
    }
  ]
}

clickCount — клики по ссылке, subscribersCount — подписки по ней. Оба числа из таблицы ссылок.

12. get_subscriber_stats

Статистика канала за период: переходы, подписки, отписки, отписки в первые 7 суток и сколько из подписавшихся в этот период ещё в канале. Только если на канале есть Pro.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_subscriber_stats
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_subscriber_stats

{
  "channel": "-1001234567890",
  "from": "2026-10-01 00:00:00 +03:00",
  "to": "2026-10-08 00:00:00 +03:00",
  "linkIDs": ["AbCdEf"]
}

Обязательны channel, from, to. Период — полуинтервал: from входит, to нет. from и to — unix-секунды числом или строка гггг-мм-дд чч:мм:сс ±чч:мм. Без смещения строка не принимается. Длина периода не больше 31 дня. from не старше 365 дней: более старые переходы уже удалены.

linkIDs необязателен. Это публичные коды из get_tracking_links и get_yandex_integrations, не больше 20, все из этого канала. Нет поля — цифры по всему каналу.

Успех, поле data:

{
  "from": 1759262400,
  "to": 1759867200,
  "clicks": 120,
  "subscriptions": 40,
  "unsubscriptions": 12,
  "unsubscriptionsIn7Days": 5,
  "subscribers": 31,
  "links": [
    {
      "linkID": "AbCdEf",
      "name": "Посев — канал партнёра",
      "clicks": 80,
      "subscriptions": 25,
      "unsubscriptions": 4,
      "unsubscriptionsIn7Days": 2,
      "subscribers": 22
    }
  ]
}

clicks — переходы. subscriptions — вступления в период. unsubscriptions — выходы в период, в том числе тех, кто вступил раньше. unsubscriptionsIn7Days — часть этих выходов: человек ушёл не позже 7 суток после последнего вступления. subscribers — из вступивших в период те, кто сейчас ещё в канале. links есть только если в запросе были linkIDs. Итог сверху — сумма по этим ссылкам.

Одинаковый запрос в течение 10 минут может вернуть те же цифры: ответ кэшируется. Повторно за тем же периодом сразу не вызывай.

Нет Pro — код 403, error_details: PRO version required for this channel. Рядом может быть paymentUrl — страница оплаты Pro этого канала. Если поля нет, ссылку самому не собирай.

Если база оборвала запрос по времени, код 422, error_details: query took too long, request fewer links. Повторять тот же запрос не надо. Попроси меньше ссылок в linkIDs или более короткий период.

13. get_subscribers

Список людей, у которых последнее вступление попало в период. Pro не требуется. В списке и те, кто уже вышел.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/get_subscribers
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/get_subscribers

{
  "channel": "-1001234567890",
  "from": "2026-10-22 00:00:00 +03:00",
  "to": "2026-10-23 00:00:00 +03:00"
}

Обязателен channel. from и to можно не передавать: без from берётся 0, без to — текущее время. Период — полуинтервал: from входит, to нет. Ограничения по длине периода нет. from и to — unix-секунды числом или строка гггг-мм-дд чч:мм:сс ±чч:мм. Без смещения строка не принимается. limit — сколько строк вернуть, целое от 1 до 200. Без поля возвращается 200.

Успех, поле data:

{
  "from": 1761080400,
  "to": 1761166800,
  "truncated": false,
  "subscribers": [
    {
      "userID": "123456789",
      "firstName": "Иван",
      "lastName": "Петров",
      "username": "ivan",
      "joinedAt": 1761100000
    }
  ]
}

Строки отсортированы по последнему вступлению, сначала самые новые. truncated равен true, если за период вступлений больше limit: в ответе самые новые, остальных нет. userID — id человека в мессенджере, строка. username — пустая строка, если его нет: в Telegram так бывает часто, в MAX его нет. joinedAt — unix последнего вступления.

Имени в запрос нет. Совпадение по имени и юзернейму ищет агент по этому списку.

14. send_reach_goal_in_chat

Отправляет дополнительную цель в рекламную систему, откуда человек пришёл в этот канал. Канал в теле, потому что персональный ключ к чату не привязан. Чат-метод send_reach_goal этим ключом не вызывать.

POST

Telegram: https://bot-api.tgtrack.ru/v1/<ключ>/send_reach_goal_in_chat
MAX: https://max.tgtrack.ru/API/bot-api/v1/<ключ>/send_reach_goal_in_chat

{
  "channel": "-1001234567890",
  "user_id": "123456789",
  "target": "leadQualified"
}

Обязательны channel, user_id, target. user_id — userID из get_subscribers, строка из цифр. target — имя цели в рекламной системе. value необязателен, число: ценность конверсии.

Цель в Метрике метод не создаёт. Нет Pro — код 403, error_details: PRO version of service required. Человек пришёл не по трекинг-ссылке с интеграцией — 422, цель отправить некуда. Успех — пустой data. Тот же запрос повторит конверсию ещё раз.

15. Порядок работы агента

Перед задачей открой https://bot-api.tgtrack.ru/personal-api.md и сверь «Версия инструкции» и «Дата инструкции» с навыком. Если они отличаются, обнови навык и работай уже по новой версии.
Ключа нет — остановись и попроси его по шагам из раздела «Для ИИ-агента». Запросы без ключа не отправляй. Ключ ставь в путь, как в адресах методов. Заголовки авторизации не передавай. Полный URL с ключом в логи и в ответ человеку не пиши.
Методы только эти: get_channels, get_payment_link, create_yandex_integration, get_yandex_integrations, create_vk_integration, get_vk_integrations, set_integration_settings, create_tracking_link, get_tracking_links, get_subscriber_stats, get_subscribers, send_reach_goal_in_chat.
Квалификация лида: найди канал через get_channels, вызови get_subscribers. Период не назван — передай только channel: вернутся 200 последних. Свой размер списка — limit от 1 до 200. «Сегодня» считай по timeShift канала. Совпадение ищи сам: имя и фамилия без учёта регистра, в Telegram ещё username, если он не пустой. Ноль совпадений — скажи и предложи расширить период. truncated равен true — скажи, что в ответе только запрошенный limit самых новых, и попроси сузить период или поднять limit. Несколько совпадений — покажи имя, юзернейм и joinedAt и спроси, кого брать. Одно совпадение и человек просит цель — send_reach_goal_in_chat с channel, user_id и названным target. Для «квал» без своего имени цели — leadQualified. «Не квал» без отдельного имени цели — ничего не отправляй. Pro перед этими вызовами не проверяй. 403 от send_reach_goal_in_chat отдай как есть.
Даты из get_channels человеку показывай календарём, не unix. «Сегодня» и «вчера» для статистики считай по timeShift канала.
get_subscriber_stats вызывай только если у канала pro равно true. Если пришёл 403 и error_details равен PRO version required for this channel, запрос не повторяй. Если в этом ответе уже есть paymentUrl, отдай его и get_payment_link не вызывай. Если поля нет, вызови get_payment_link. Ссылку самому не собирай. Если ссылки нет и там, дай команду бота: Telegram /pro_mode, MAX /pro.
Оплату и продление Pro бери через get_payment_link и отдавай человеку paymentUrl. Скажи, за какой канал ссылка и до какой даты Pro, если proUntil есть.
Канал человек называет по имени или присылает ссылку. Если человек называет канал по имени, сначала вызови get_channels, найди name и передай его channelID строкой в поле channel. Ссылку проси только если подходящего канала в списке нет или у закрытого канала нет публичного адреса.
Поля бери только из этой страницы. OAuth Яндекса и внутренние id tgtrack не передавай.
Перед созданием вызови список интеграций или ссылок канала и проверь, что name свободно.
Больше трёх запросов в одну секунду не отправляй и не шли пачку параллельно. Лимит: 3 в секунду, 60 в минуту, 1000 в сутки. На 429 не повторяй сразу. retryAt — дата и время по Москве, retryIn — секунды до повтора. Подожди retryIn секунд и вызови метод ещё раз. Если полей нет, остановись и скажи человеку.
403 с текстом user API key required значит, что передан чат-ключ, а не персональный. Попроси персональный ключ.
405 значит, что канал ещё не подключён к боту. Попроси человека добавить его командой из раздела «Для ИИ-агента».
409 значит, что имя занято: возьми другое или используй уже существующий linkID.
Ответ No live Yandex Metrika access... значит, что человек ещё не делал первую интеграцию в боте. Попроси её один раз и объясни зачем.

Что дальше

Готово: агент может создавать яндекс- и VK-интеграции, трекинг-ссылки, менять их настройки, смотреть статистику и вступления и отправлять глубокую цель по вашей задаче обычным языком.

Несколько советов:

Ключ храните только у агента и в боте. Если ключ засветился — перевыпустите его командой /personal_api, кнопка Перевыпустить.
Перед массовым созданием яндекс-интеграций один раз сделайте интеграцию в боте — так агент получит доступ к Метрике.
Как устроена разметка трафика вручную, можно посмотреть в разделе Разметка трафика.

Пробуйте ставить агенту задачи своими словами: чем конкретнее канал и название кампании, тем точнее будет результат.

Как пользоваться навыком​

Шаг 1 — Отправьте агенту ссылку на эту страницу​

Шаг 2 — Напишите, что нужно сделать​

Шаг 3 — Создайте персональный ключ, когда агент попросит​

Для ИИ-агента​

1. Запрос​

2. Лимиты​

3. get_channels​

4. get_payment_link​

5. create_yandex_integration​

6. get_yandex_integrations​

7. create_vk_integration​

8. get_vk_integrations​

9. set_integration_settings​

10. create_tracking_link​

11. get_tracking_links​

12. get_subscriber_stats​

13. get_subscribers​

14. send_reach_goal_in_chat​

15. Порядок работы агента​

Что дальше​

Как пользоваться навыком

Шаг 1 — Отправьте агенту ссылку на эту страницу

Шаг 2 — Напишите, что нужно сделать

Шаг 3 — Создайте персональный ключ, когда агент попросит

Для ИИ-агента

1. Запрос

2. Лимиты

3. get_channels

4. get_payment_link

5. create_yandex_integration

6. get_yandex_integrations

7. create_vk_integration

8. get_vk_integrations

9. set_integration_settings

10. create_tracking_link

11. get_tracking_links

12. get_subscriber_stats

13. get_subscribers

14. send_reach_goal_in_chat

15. Порядок работы агента

Что дальше