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

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

Навык (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

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

примечание

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

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

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

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

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

Если ключа ещё нет, 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	нет доступа к каналу, либо ключ не того типа
405	канал не подключён к боту
409	такое имя в канале уже есть
422	поля не прошли проверку, нет доступа к Метрике, Яндекс отказал
429	слишком много запросов

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

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

2. Лимиты

Только персональный ключ: не больше 1 запроса в секунду и не больше 1000 запросов в сутки. При превышении код 429.

Между вызовами держите паузу не меньше одной секунды. Пачку созданий не отправляйте параллельно.

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"
    }
  ]
}

channelID в Telegram — id чата, в MAX — id чата MAX. username пустой, если у канала нет публичного адреса. Закрытый канал без публичной ссылки и без уже сохранённой пригласительной в channel по id не создаётся: передайте пригласительную ссылку.

4. 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-токен Яндекса в запрос не передаётся.

5. 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>"
    }
  ]
}

6. 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..."
}

url — ссылка вне мессенджера. urlMessenger — ссылка для размещения внутри Telegram или MAX.

7. 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..."
    }
  ]
}

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

Перед задачей открой https://bot-api.tgtrack.ru/personal-api.md. Если инструкция отличается от навыка, обнови навык и работай уже по новой версии.
Ключа нет — остановись и попроси его по шагам из раздела «Для ИИ-агента». Запросы без ключа не отправляй. Ключ ставь в путь, как в адресах методов. Заголовки авторизации не передавай. Полный URL с ключом в логи и в ответ человеку не пиши.
Методы только эти: get_channels, create_yandex_integration, get_yandex_integrations, create_tracking_link, get_tracking_links.
Канал человек называет по имени или присылает ссылку. Если человек называет канал по имени, сначала вызови get_channels, найди name и передай его channelID строкой в поле channel. Ссылку проси только если подходящего канала в списке нет или у закрытого канала нет публичного адреса.
Поля бери только из этой страницы. OAuth Яндекса и внутренние id tgtrack не передавай.
Перед созданием вызови список интеграций или ссылок канала и проверь, что name свободно.
Между запросами пауза не меньше 1 секунды. Лимит 1000 запросов в сутки.
403 с текстом user API key required значит, что передан чат-ключ, а не персональный. Попроси персональный ключ.
405 значит, что канал ещё не подключён к боту. Попроси человека добавить его командой из раздела «Для ИИ-агента».
409 значит, что имя занято: возьми другое или используй уже существующий linkID.
Ответ No live Yandex Metrika access... значит, что человек ещё не делал первую интеграцию в боте. Попроси её один раз и объясни зачем.

Что дальше

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

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

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

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

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

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

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

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

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

1. Запрос​

2. Лимиты​

3. get_channels​

4. create_yandex_integration​

5. get_yandex_integrations​

6. create_tracking_link​

7. get_tracking_links​

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

Что дальше​

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

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

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

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

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

1. Запрос

2. Лимиты

3. get_channels

4. create_yandex_integration

5. get_yandex_integrations

6. create_tracking_link

7. get_tracking_links

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

Что дальше