Инструменты
Агенту доступны тридцать шесть инструментов. Двадцать три только читают. Тринадцать меняют данные: создают, правят и удаляют дашборды и рассылки, а рассылки ещё готовят, планируют, запускают и отзывают.
metriox_filter_catalog, metriox_filter_values, metriox_get_bot_activity,
metriox_get_bot_profile, metriox_list_segments и metriox_query_sessions существуют и доступны агенту, но карточек для них
пока нет. Все шесть только читают.
Обычно агент выбирает инструмент сам, и знать эти имена не нужно. Список полезен, чтобы понимать границы возможностей и формулировать запросы точнее.
Проект определяется токеном, а не параметром. Передать «чужой» проект в вызове нельзя — идентификатора проекта среди параметров просто нет.
Фильтр
Семь инструментов ниже принимают необязательный параметр filter — одну строку с условием. Без него
считаются все события бота за интервал.
event.name = "purchase" and user.tg.is_premium = "true"
Слева от оператора — что именно спрашиваем:
| Начало | О чём условие |
|---|---|
event.name, event.type, event.origin, event.text, event.user_id, event.source.channel | Поля самого события |
event.tg.<ключ>, event.source.<ключ>, event.lookup.<ключ>, event.web.<ключ>, event.sender.<ключ> | Системные свойства события |
event.props.<ключ> | Свойства, которые отправляет ваш бот |
user.tg.<ключ>, user.meta.<ключ>, user.props.<ключ> | Профиль человека на сейчас, а не на момент события |
user.events(<условие на события>, last: 30d).count | Что человек делал: count, active_days, unique_events, sum(event.props.<ключ>, channel: "telegram_bot_api"), busiest_day.count |
Операторы: =, !=, <, <=, >, >=, contains, startswith, in ["a", "b"], not in, а также
and, or, not и скобки. Текст в кавычках, числа, true/false и даты (2026-09-01) — без кавычек.
Кавычки решают, как сравнивается значение: event.tg.chat_id = 100 — сравнение чисел,
event.tg.chat_id = "100" — сравнение текста.
Имена свойств у каждого бота свои: их показывает metriox_filter_catalog, причём сразу в том виде, в
каком их писать в фильтре (filterName). Это не формальность: перепутанный префикс —
event.props.country вместо event.lookup.country — не ошибка, а пустой ответ, потому что свойства с
таким именем бот просто никогда не присылал.
Ответ повторяет фильтр. Когда filter передан, в ответе появляются filterApplied — та же строка в
каноническом виде — и filterWarnings. Это страховка от «правильно разобранного, но не того» условия:
по filterApplied видно, на какой вопрос на самом деле ответили цифры.
Ошибка в строке — это отказ, а не пустой ответ. Агент получает код ошибки и номера символов, запрос при этом не выполняется:
The filter was not accepted:
- value_type_mismatch (characters 13-14): event.name takes a quoted string.
Nothing was queried. Fix the expression and call again.
user.events()без условия внутри считает все события, включая исходящие сообщения самого бота — на это приходит предупреждение.event.user_idв группах — это идентификатор чата, а не человека. Считать людей надёжнее метрикойUsers.user.events(...)безlast:,before:илиfrom:считает за тот же интервал, что и сам запрос.
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 | нет | Курсор из предыдущего вызова, для следующей страницы |
filter | нет | Условие на события и людей — см. «Фильтр» выше |
За один вызов возвращается не больше 100 событий. Если событий больше, в ответе будет курсор, и агент запросит следующую страницу сам.
Это инструмент для разбора конкретных случаев — «покажи события с ошибкой оплаты за вчера». Для
подсчётов используйте metriox_query_kpi: он считает на стороне сервера и не тратит контекст
агента на перебор событий.
metriox_query_kpi
Одно число по одному боту за интервал времени.
| Параметр | Обязательный | Описание |
|---|---|---|
botId | да | Бот из metriox_list_bots |
fromUtc | да | Начало интервала, включительно, ISO-8601 UTC |
toUtc | да | Конец интервала, не включительно, ISO-8601 UTC |
metric | нет | Что считать — см. ниже |
filter | нет | Условие на события и людей — см. «Фильтр» выше |
Значения 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 |
filter | нет | Условие на события и людей — см. «Фильтр» выше |
Это инструмент для вопросов «как менялось» и для сравнения периодов. 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 | нет | Вернуть ещё и сумму по всем значениям, а не только по возвращённым строкам. Стоит второго прохода, поэтому по умолчанию выключено |
filter | нет | Условие на события и людей — см. «Фильтр» выше |
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 |
filter | нет | Условие на события и людей — см. «Фильтр» выше. Применяется ко всем событиям воронки и сужает выборку; шаг им не задаётся |
Шаг задаётся именем события. Более сложные условия шага через 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 |
filter | нет | Условие на события и людей — см. «Фильтр» выше. Применяется ко всем событиям, из которых строятся когорты: и к попаданию в когорту, и к возвращению |
В ответе для каждой когорты приходят два ряда, и выбор не того даёт неверную кривую без каких-либо признаков ошибки:
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 | нет | Курсор из предыдущего вызова |
filter | нет | Условие на события и людей — см. «Фильтр» выше |
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, Scheduled, Preparing, Prepared, Sending, Completed, Cancelling, Cancelled или Skipped |
limit | нет | Рассылок на страницу, 1-50. По умолчанию 25 |
afterCreatedAtUtc | нет | Курсор из предыдущего ответа, в паре с afterId |
afterId | нет | Курсор из предыдущего ответа, в паре с afterCreatedAtUtc |
seriesId | нет | Повторяющаяся рассылка: вместо рассылок проекта вернуть её отправки |
Отправки повторяющейся рассылки в обычный список не попадают, как и в панели: каждая из них отдельная
рассылка со своими счётчиками, и найти их можно только через seriesId. Отправка в статусе Skipped не
ушла; причина в поле scheduleFailureCode.
metriox_get_campaign
Одна рассылка целиком: статус, бот, описание аудитории, текст сообщения и счётчики.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
metriox_get_campaign_progress
Как далеко продвинулась отправка: сколько получателей ожидает, в работе, отправлено, не доставлено или пропущено.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
Возвращает текущие цифры сразу. Чтобы следить за отправкой, агент вызывает инструмент повторно: он не ждёт изменений внутри одного вызова.
metriox_get_campaign_results
Что рассылка дала: сколько человек её получили, ответили, заблокировали бота и какие кнопки нажимали. Каждого получателя считают в его собственном окне после доставки. Конверсия возвращается, только если у рассылки сохранена цель.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка из metriox_list_campaigns |
windowDays | нет | Сколько дней после доставки считать каждого получателя, 1-30. Без него: окно, сохранённое с рассылкой, или 3 |
Цель параметром не передаётся: она сохраняется с рассылкой, чтобы отчёт показывал одно и то же число всем. Цель, переданную в вызове, никто другой воспроизвести не смог бы.
Сначала читайте unavailable. У рассылки, которая ещё не отправлена (NotStarted), и у той, чей список
получателей удалён по сроку хранения (RecipientsPurged), все числа нулевые и ничего не значат.
Ещё два поля меняют смысл цифр: blockTracking со значением NotCaptured означает, что бот не пишет
события участия, поэтому ноль блокировок — это отсутствие данных, а не факт; accruing означает, что у
части получателей окно ещё не закрылось и числа вырастут.
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 | нет | Доставить без звука |
excludeRecentlyMessagedDays | нет | Частотное ограничение, 1-90: не писать тем, кому этот бот уже писал в другой рассылке за последние N дней. Проверяется при отправке, поэтому число получателей при подготовке их ещё включает; пропущенные получают статус Skipped |
Аудиторию нужно задать ровно одним способом из трёх. Медиа, текстовые сущности и многоколоночные клавиатуры через 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_schedule_campaign
Поставить черновик на отправку в будущем: один раз или по повторяющемуся правилу. Требует прав администратора. Аудитория собирается и лимиты проверяются в момент отправки, а не сейчас, поэтому сегодняшнее число получателей только оценка.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Рассылка в статусе Draft |
etag | да | Поле etag из metriox_get_campaign, прочитанное прямо перед вызовом |
kind | да | Once, Daily, Weekly или Monthly |
runAtUtc | для Once | Момент отправки, ISO 8601. Не раньше чем через минуту и не позже чем через год |
localTime | для повторяющихся | Время суток HH:mm в поясе timeZoneId |
timeZoneId | для повторяющихся | Часовой пояс IANA, например Europe/Moscow |
weekdays | для Weekly | Дни недели по-английски: ["Monday", "Thursday"]. Те же названия возвращает metriox_get_campaign |
monthDay | для Monthly | День месяца, 1-31. В коротком месяце отправка уходит в его последний день |
endsOnLocalDate | нет | Последний день серии, yyyy-MM-dd в поясе timeZoneId |
Подтвердите у человека время, правило и текст до вызова. Пока рассылка запланирована, её нельзя редактировать: сначала снимите расписание.
Номера дней недели вместо названий отклоняются: в разных системах неделя нумеруется по-разному, и
ошибка сдвинула бы каждую отправку на день. Почему отправка не состоялась, показывает поле
scheduleFailureCode у рассылки, подробнее в разделе
Отложенная и повторяющаяся отправка.
metriox_unschedule_campaign
Снять расписание: рассылка снова становится редактируемым черновиком. Ничего не отправляется и ничего не отзывается. Достаточно прав на запись.
| Параметр | Обязательный | Описание |
|---|---|---|
campaignId | да | Запланированная рассылка из metriox_list_campaigns |
У повторяющейся рассылки уже сделанные отправки остаются: снимается только правило.
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 пока недоступны:
- когорты, гистограммы и тепловые карты;
- профили пользователей и распределения по их свойствам;
- управление ботами, участниками проекта и тарифом.
Часть этих возможностей появится в следующих версиях; управление ботами, участниками и биллингом недоступно принципиально — см. границы прав.