Инструменты
Агенту доступен тридцать один инструмент. Двадцать только читают. Одиннадцать меняют данные: их
названия начинаются с create, update и delete.
metriox_filter_catalog, metriox_filter_values, metriox_get_bot_activity и
metriox_get_bot_profile существуют и доступны агенту, но карточек для них пока нет. Все четыре
только читают.
Обычно агент выбирает инструмент сам, и знать эти имена не нужно. Список полезен, чтобы понимать границы возможностей и формулировать запросы точнее.
Проект определяется токеном, а не параметром. Передать «чужой» проект в вызове нельзя — идентификатора проекта среди параметров просто нет.
metriox_list_bots
Список ботов проекта.
Параметров нет. Возвращает идентификатор и название каждого бота.
С этого инструмента начинается почти любая работа: остальным инструментам нужен botId, и только
боты из этого списка доступны токену.
metriox_get_project_overview
Квота и расход событий за текущий расчётный период: лимит, сколько событий и байт израсходовано, сколько осталось, границы периода.
Параметров нет.
Отвечает на вопросы вида «мы не выходим за лимит?» и «сколько ещё событий доступно до конца периода».
metriox_search_events
Постраничный просмотр «сырых» событий одного бота за интервал времени, от новых к старым.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC — например 2026-09-01T00:00:00Z |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
limit | нет | Событий на страницу, 1–100. По умолчанию 50 |
cursor | нет | Курсор из предыдущего вызова, для следующей страницы |
За один вызов возвращается не больше 100 событий. Если событий больше, в ответе будет курсор, и агент запросит следующую страницу сам.
Это инструмент для разбора конкретных случаев — «покажи события с ошибкой оплаты за вчера». Для
подсчётов используйте metriox_query_kpi: он считает на стороне сервера и не тратит контекст
агента на перебор событий.
metriox_query_kpi
Одно число по одному боту за интервал времени.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
metric | нет | Что считать — см. ниже |
Значения metric:
Events— все события за интервалUsers— уникальные пользователи, активные в интервалеEventsPerUser— отношение первого ко второмуNewUsers— пользователи, у которых первое в истории событие попало в интервал
metriox_query_series
Метрика во времени по одному боту, с группировкой по часам, дням, неделям или месяцам.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
metric | нет | Events, Users, EventsPerUser или NewUsers. По умолчанию Events |
granularity | нет | Auto, Hour, Day, Week или Month. По умолчанию Auto |
splitBy | нет | Разбить на линии по измерению: event_name, source, event_origin или event_type |
seriesLimit | нет | Сколько линий оставить при splitBy, по величине. По умолчанию 10 |
Это инструмент для вопросов «как менялось» и для сравнения периодов. Auto почти всегда подбирает
подходящий шаг сам.
metriox_query_top
Самые крупные значения измерения за интервал: какие события происходят чаще всего, какие источники приводят больше всего трафика, какое значение произвольного свойства встречается чаще.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
metric | нет | Events, Users, EventsPerUser или NewUsers. По умолчанию Events |
groupBy | нет | event_name, source, event_origin или event_type. По умолчанию event_name |
detailKey | нет | Группировать по произвольному свойству события вместо встроенного измерения, например по $tg.callback_data. Имеет приоритет над groupBy |
limit | нет | Сколько строк вернуть, 1-100. По умолчанию 20 |
includeTotal | нет | Вернуть ещё и сумму по всем значениям, а не только по возвращённым строкам. Стоит второго прохода, поэтому по умолчанию выключено |
metriox_query_funnel
Конверсия по упорядоченной последовательности событий: сколько людей дошло до каждого шага и где они отваливаются.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
steps | да | Имена событий по порядку, от 2 до 10. Найти имена можно через metriox_query_top с группировкой по event_name |
mode | нет | UniqueUsers считает всех, кто сделал каждый шаг когда-либо внутри интервала; Ordered требует, чтобы шаги шли последовательно. По умолчанию UniqueUsers |
Шаг задаётся именем события. Более сложные условия шага через MCP пока недоступны.
metriox_query_retention
Возвращаемость: из людей, впервые появившихся в каждом периоде, сколько вернулось позже.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала формирования когорт, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала когорт, не включительно, ISO-8601 UTC |
granularity | нет | Размер когорты и корзины: Day, Week или Month. По умолчанию Day |
windowUnits | нет | Сколько корзин отслеживать, 1-90, в единицах granularity. По умолчанию 30 |
В ответе для каждой когорты приходят два ряда, и выбор не того даёт неверную кривую без каких-либо признаков ошибки:
returnedRateByBucket— за период: доля вернувшихся именно в этой корзине.cumulativeReturnedRateByBucket— в пределах N: доля вернувшихся хотя бы раз к этой корзине.
Просуммировать первый ряд и получить второй нельзя: каждое значение считается по уникальным пользователям, поэтому активные в нескольких периодах посчитались бы дважды. Корзина 0 — сам период когорты, она всегда равна всей когорте.
Фильтры по событиям начала и возврата через MCP пока недоступны: инструмент считает возвращаемость по любым событиям.
metriox_list_users
Постраничный список людей, пользовавшихся ботом за интервал: сколько у каждого событий, когда его увидели впервые и последний раз.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
search | нет | Подстрока без учёта регистра по идентификатору пользователя и по его username, имени и фамилии в Telegram. Так можно найти конкретного человека |
sortBy | нет | UserId, EventsCount, FirstSeen или LastSeen. Без него используется порядок по умолчанию, самый дешёвый для глубокой постраничной выборки |
sortDirection | нет | Asc или Desc при заданном sortBy. По умолчанию Desc |
limit | нет | Пользователей на страницу, 1-100. По умолчанию 50 |
cursor | нет | Курсор из предыдущего вызова |
metriox_get_conversation
Переписка бота с одним пользователем, от новых сообщений к старым: что человек отправил, что бот ответил, какие кнопки предлагались и какие нажимались.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
platformUserId | да | Числовой идентификатор пользователя в Telegram, не @username. Взять из metriox_list_users или metriox_search_events |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
limit | нет | Элементов на страницу, 1-100. По умолчанию 50 |
cursor | нет | Курсор из предыдущего вызова, для более старой истории |
Это основной инструмент для разбора жалоб: он показывает, что на самом деле произошло у конкретного человека.
metriox_get_dashboard
Содержимое одного дашборда: сохранённая раскладка виджетов.
| Параметр | Обязательный | Описание |
|---|---|---|
dashboardId | да | Дашборд из metriox_list_dashboards |
Форма поля data задаётся фронтендом, а не сервером, и на сервере пока не проверяется по схеме, так
что полагаться на её стабильность не стоит.
metriox_list_campaigns
Список рассылок проекта, от новых к старым, со статусом и счётчиками.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | нет | Только рассылки этого бота. Без него: все боты проекта |
status | нет | Draft, Preparing, Prepared, Sending, Completed, Cancelling или Cancelled |
limit | нет | Рассылок на страницу, 1-50. По умолчанию 25 |
afterCreatedAtUtc | нет | Курсор из предыдущего ответа, в паре с afterId |
afterId | нет | Курсор из предыдущего ответа, в паре с afterCreatedAtUtc |
metriox_get_campaign
Одна рассылка целиком: статус, бот, описание аудитории, текст сообщения и счётчики.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
metriox_get_campaign_progress
Как далеко продвинулась отправка: сколько получателей ожидает, в работе, отправлено, не доставлено или пропущено.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
Возвращает текущие цифры сразу. Чтобы следить за отправкой, агент вызывает инструмент повторно: он не ждёт изменений внутри одного вызова.
metriox_list_campaign_recipients
Отдельные получатели рассылки и что произошло с каждым. Основной инструмент для вопроса «кому не дошло и почему».
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
status | нет | Только получатели в этом статусе. Без него: все |
limit | нет | Получателей на страницу, 1-200. По умолчанию 50 |
afterChatId | нет | Курсор: chatId последней строки предыдущей страницы. Только в паре с afterIsTest |
afterIsTest | нет | Курсор: признак isTest последней строки. По умолчанию false. Нужен потому, что chatId внутри рассылки не уникален |
metriox_create_campaign
Создать рассылку как черновик. Ничего не отправляется: черновик нужно подготовить, а затем запустить.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот, от имени которого пойдёт рассылка |
name | да | Внутреннее название, получателям не видно |
text | да | Текст сообщения |
lastDays | нет | Только активные за последние N дней. Взаимоисключающе с allTime и с парой fromUtc/toUtc |
allTime | нет | Всем, кого бот когда-либо видел |
fromUtc / toUtc | нет | Абсолютные границы аудитории, только вместе |
parseMode | нет | HTML или MarkdownV2. Без него текст без разметки |
buttons | нет | Кнопки, по одной в строке: "подпись|url" для ссылки или "подпись|cb:значение" для callback |
disableWebPagePreview | нет | Убрать превью ссылки |
disableNotification | нет | Доставить без звука |
Аудиторию нужно задать ровно одним способом из трёх. Медиа, текстовые сущности и многоколоночные клавиатуры через MCP пока недоступны.
metriox_update_campaign
Отредактировать рассылку, пока она в статусе Draft. После подготовки payload заморожен, и правка
отклоняется.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
name | нет | Новое внутреннее название |
text | нет | Новый текст. Заменяет сообщение целиком, поэтому кнопки нужно передать заново |
parseMode, buttons, disableWebPagePreview, disableNotification | нет | Как при создании |
Аудиторию этот инструмент не меняет: кому уйдёт рассылка, решается при создании. Чтобы изменить аудиторию, создайте рассылку заново.
metriox_delete_campaign
Удалить рассылку в статусе Draft. Отправленная рассылка — это запись, она не удаляется.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
metriox_prepare_campaign
Заморозить сообщение черновика и собрать список получателей. Отправки всё ещё не происходит. Повторный вызов продолжает, а не начинает заново.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
Отклоняется, если фильтр не нашёл никого: рассылка с нулём получателей завершилась бы мгновенно и в панели прогресса выглядела бы как идеально доставленная.
metriox_unprepare_campaign
Вернуть подготовленную рассылку в черновик и отбросить список получателей. Только из статуса Prepared.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
Повторная подготовка собирает аудиторию заново, поэтому состав получателей может отличаться.
metriox_test_send_campaign
Отправить сообщение рассылки в один чат тем же путём, которым идёт реальная отправка.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
chatId | да | Числовой id чата, не @username |
Указывайте чат, который контролируете. Бот должен уже иметь с ним переписку: начать её первым Telegram не позволяет. Статус рассылки при этом не меняется.
metriox_start_campaign
Запустить рассылку. Сообщение уходит всем подготовленным получателям. Требует прав администратора.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка в статусе Prepared |
etag | да | Поле etag из metriox_get_campaign, прочитанное прямо перед запуском |
etag — это защита от отправки по устаревшим цифрам: если рассылка изменилась после того, как агент её
прочитал, запуск отклоняется. Просите подтверждение у человека до вызова.
metriox_cancel_campaign
Отозвать рассылку: остановить отправку и удалить то, что уже ушло. Требует прав администратора. Работает и на завершённой рассылке, не только на идущей. Telegram разрешает боту удалять собственное сообщение только 48 часов, и этот срок считается для каждого сообщения отдельно — см. Рассылки.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
metriox_list_dashboards
Список дашбордов проекта, доступных пользователю токена: названия, идентификаторы и автор каждого.
Параметров нет.
Возвращает только перечень — не содержимое дашбордов и не структуру виджетов.
metriox_create_dashboard
Создаёт дашборд из списка карточек.
| Параметр | Обязательный | Описание |
|---|---|---|
name | да | Название, до 120 символов |
cards | да | Карточки по порядку: от 1 до 200. У каждой type, опционально w, h, id |
availability | нет | Everyone или DashboardCreator. По умолчанию Everyone |
Поля карточки: type — тип виджета (например kpi, series); w — ширина в 12-колоночных единицах,
1-12; h — высота в строках, 1-60; id — свой идентификатор, иначе сгенерируется.
Если w или h не указать, карточка займёт максимум по этой оси. Слишком большие значения
обрезаются до максимума.
Набор типов виджетов задаётся веб-приложением, а не сервером, поэтому список типов через MCP получить
нельзя: посмотрите metriox_get_dashboard на существующем дашборде, чтобы увидеть используемые типы.
metriox_update_dashboard
Меняет название, видимость или карточки. Изменяется только то, что передали.
| Параметр | Обязательный | Описание |
|---|---|---|
dashboardId | да | Дашборд из metriox_list_dashboards |
name | нет | Новое название |
cards | нет | Полный новый список карточек |
availability | нет | Новая видимость |
cards заменяет весь список, а не добавляет к нему. Сначала прочитайте дашборд через
metriox_get_dashboard и отправьте полный набор, который хотите получить.
Сервер не сравнивает версии и не отдаёт ошибку конфликта: если в это же время кто-то правит тот же дашборд в браузере, победит тот, кто записал последним, и чужая правка потеряется.
metriox_delete_dashboard
Удаляет дашборд. Отменить нельзя.
| Параметр | Обязательный | Описание |
|---|---|---|
dashboardId | да | Дашборд из metriox_list_dashboards |
Чего в списке нет
Через MCP пока недоступны:
- когорты, гистограммы и тепловые карты;
- профили пользователей и распределения по их свойствам;
- управление ботами, участниками проекта и тарифом.
Часть этих возможностей появится в следующих версиях; управление ботами, участниками и биллингом недоступно принципиально — см. границы прав.