Полное руководство по меню /setup: интерфейс X Bot в Telegram

Самый быстрый способ настроить X Bot — интерактивное меню /setup. Оно оборачивает каждую административную команду в кликабельный интерфейс с редактированием на месте — слэш-команды запоминать не нужно.

Самый быстрый путь: добавьте бота в свою группу, введите /setup, нажмите 🚀 Быстрый старт и пройдите четыре шага. Через две минуты у вас будет расписание ежедневных отчётов, работающее на реальном фильтре.

Как выглядит /setup

╔══════════════════════════════════════════════╗
║ ⚙️  Bot Setup                                ║
║                                              ║
║ Pick a section. Settings save instantly.     ║
║                                              ║
║ Current state                                ║
║ ─ Project:  MyToken                          ║
║ ─ Filter:   3 keywords · 2 cashtags          ║
║ ─ Schedule: daily 18:00 UTC                  ║
║ ─ Plan:     FREE — 47/100 credits left       ║
╠══════════════════════════════════════════════╣
║ [ 🚀 Quick Start ]                           ║
║ [ 🎯 Filters     ] [ ⏰ Schedule       ]      ║
║ [ 📊 Reports     ] [ 🎨 Customization  ]      ║
║ [ 👥 Admins      ] [ 💳 Buy Credits   ]      ║
║ [ ℹ️  About       ]                          ║
║ [ ✕ Close ]                                  ║
╚══════════════════════════════════════════════╝

Каждый экран показывает ваше текущее состояние вверху, чтобы вы знали, что настроено, прежде чем что-то менять. Каждое изменение сохраняется в базу данных мгновенно — кнопки «сохранить», которую можно забыть нажать, нет.

Мастер быстрого старта

Нажмите 🚀 Быстрый старт для линейного процесса из четырёх шагов, который переводит новый чат из состояния «ничего не настроено» в «первый запланированный отчёт» с минимумом вопросов. Пропуск и Выход всегда доступны — частично пройденный мастер никогда вас не блокирует, настройки просто остаются по умолчанию.

Четыре шага:

Шаг	Спрашивает	Сохраняет в
1	Название проекта	Настройку ProjectName (используется в отчётах, карточках лидерборда, личных сообщениях админам)
2	Что отслеживать в X — аккаунты, кэштеги или ключевые слова	Массив from, cashtags или keywords фильтра по умолчанию
3	Когда публиковать ежедневный отчёт — 4 пресета или своё время ЧЧ:ММ	Запланированная задача, привязанная к вашему чату
4	Готово — экран сводки с подсказкой /recreate для предпросмотра	(ничего)

Полное меню

Каждая кнопка верхнего уровня открывает отдельный экран. Углубляйтесь свободно — на каждом экране есть ← Назад к предыдущему уровню и ✕ Закрыть для выхода.

🎯 Фильтры

Какие посты X бот выбирает при каждом запланированном запуске.

Нажмите на любую категорию, чтобы углубиться. Исключения — в стиле чекбоксов: одно нажатие переключает «исключить ретвиты / ответы / цитаты».

Именованные фильтры (продвинутая функция) позволяют держать несколько фильтров одновременно на одном чате — полезно, если вы управляете несколькими клиентами в одной группе. У каждого именованного фильтра своя кнопка удаления в строке с подтверждением нажатием. Нажмите ➕ Добавить именованный фильтр, чтобы отправить однострочное определение через меню (name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam). Нужен хотя бы один из from / keywords / cashtags / mention.

Экран категории выглядит так — краткое описание того, что делает категория, текущее значение и действия Добавить / Удалить / Очистить всё:

Когда вы нажимаете ➕ Добавить, меню переходит в режим ввода — отправьте ответ как обычное сообщение, и экран автоматически перерисуется с баннером подтверждения («✓ Добавлено 2 кэштега: $BTC, $ETH»).

➕ Add cashtags

Send the cashtags to track, space-separated.
The $ is optional.

Example:  $BTC $ETH SOL

Type your reply as a normal message,
or tap Cancel to go back.

[✕ Cancel]

⏰ Расписание

Когда бот запускается и публикует ежедневный отчёт.

Четыре ежедневных пресета покрывают большинство сообществ. У активного в данный момент пресета в подписи стоит префикс ✓. Своё время запрашивает ЧЧ:ММ. Конкретные дни принимают 14:30 Mon Wed Fri. Cron принимает стандартные cron-выражения (например, cron(0 12 ? * MON-FRI *)). Бот применяет минимальную частоту в 12 часов, чтобы держать расходы предсказуемыми.

Если вы выбираете пресет расписания в чате без фильтров, меню отказывает с дружелюбной ошибкой, указывающей на 🎯 Фильтры — бот не будет планировать чат, которому нечего выбирать.

📊 Отчёты и период

📊 Reports & Period

Period: 01/05/2026 7days
Start:  2026-05-01
End:    2026-05-07

The bot fetches X posts inside this window on
every scheduled run. Without a period
configured, the bot uses a rolling 24-hour
window.

[📆 Set period]   [🗑 Clear period]
[⚡ Generate report now]
[📰 Show last report]

Задать период ограничивает отчёты конкретным окном (например, соревнование длиной в неделю). Формат ДД/ММ/ГГГГ Nдней или Nнедель. Очистить период возвращает к стандартному скользящему окну в 24 часа. Сформировать отчёт сейчас запускает ту же Step Function, что и cron — удобно для мгновенных превью. Показать последний отчёт указывает на /report (повторно публикует последнее кэшированное изображение без списания кредитов).

🎨 Настройка

Метаданные проекта, отображаемые в отчётах и на публичном лидерборде.

🎨 Customization

🏷 Name:        MyToken
✏️ Description: A community-driven DeFi project
📝 Long desc.:  (multi-paragraph project pitch…)
🖼 Logo:        ✓ uploaded
🔗 URLs:        2 URLs
💬 Topic:       Forum topic "Reports"

[🏷 Name]      [✏️ Description]
[📝 Long desc.][🖼 Logo]
[🔗 URLs]      [💬 Topic]
[📈 Leaderboard customization]

Поддерево «Лидерборд» открывает:

Настройка	Формат
🏆 Очки	Пять чисел через пробел: лайки ретвиты ответы цитаты просмотры (например, 5 1 20 10 0.01)
🎨 Цвета	Пять hex-цветов, в том же порядке
🔢 Количество в топе	Целое число от 1 до 10 — сколько пользователей в лидерборде
📛 Заголовок топа	Свободный текст. Опциональный суффикс |#hex задаёт свой цвет (например, Лучшие участники|#FF8800)
🥇 Заголовок лучшего твита	То же
📊 Заголовок вовлечённости	То же

Загрузка логотипа использует существующий обработчик фото бота — нажмите 🖼 Логотип, затем отправьте изображение как фото Telegram (не файл). Бот изменяет размер и загружает на CDN сайта.

Тема предлагает отправить /set_topic изнутри нужной темы форума. Меню не может получить message_thread_id из callback-кнопки, поэтому это остаётся поверхностью для слэш-команды.

👥 Админы и уведомления

Список чатов пользователей, назначенных получать личные сообщения об исчерпании кредитов, ошибках выборки и предупреждениях «чат не найден». Добавление админов по-прежнему требует /add_admin @user1 @user2 из чата — парсер упоминаний Telegram срабатывает только на реальных сообщениях, не на callback.

👥 Admins & Notifications

Currently:
  • Alice (@alice_admin)
  • Bob (@bob_dev)

To add admins, send /add_admin @user1 @user2
in this chat.

[🗑 Clear notification list]

💳 Покупка кредитов и тариф

Отображение тарифа и баланса, плюс кнопки для покупки и управления. Экран отображается по-разному в зависимости от текущего тарифа чата:

Чат FREE:

💳 Buy Credits & Plan

Plan: FREE
Used this month: 47 / 100
Remaining:        53
Resets: 2026-06-01

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

Чат с подпиской PRO:

💳 Buy Credits & Plan

Plan: PRO (subscription) ✓
Unlimited fetching with Stripe metering above 1 000 / month free.

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

Чат с кредитами PRO (куплены за ETH):

💳 Buy Credits & Plan

Plan: PRO (credits)
Credits remaining: 4 152
Total purchased:   5 000

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

Кнопка 💰 Купить кредиты / улучшить тариф публикует карточку с вариантами оплаты под меню. Варианты, которые предлагает бот, зависят от текущего тарифа:

• FREE → оба варианта: 💳 Оплата картой (подписка Stripe) и 🪙 Оплата в ETH (пакет кредитов).
• PRO·кредиты → показаны оба варианта. ETH пополняет существующий баланс; Stripe добавляет подписку поверх (существующие ETH-кредиты сохраняются и тратятся первыми при каждой выборке).
• PRO·подписка → вариантов покупки нет. Бот отвечает сообщением «подписка уже есть» и указывает на 🛠 Управление для перехода в портал Stripe.

Кнопка 🛠 Управление подпиской открывает портал клиентов Stripe в браузере — там вы обновляете карту, отменяете подписку или скачиваете счета. Имеет смысл только при активной подписке Stripe.

Подэкран 📊 Использование за месяц разбивает fetched_posts и fetch_attempts за текущий месяц и за сегодня — полезно для выявления тихих сбоев (много попыток, ноль постов → вероятно, ошибки 402 или пустые запросы) и для предпросмотра следующего счёта Stripe при приближении к порогу в 1 000 постов.

Покупка и управление также доступны как устаревшие слэш-команды /buy и /subscription. Поведение идентично; кнопки меню просто экономят набор текста.

📡 Автотрансляция X-постов

Пересылает посты выбранных аккаунтов X в чат сразу после публикации — отдельно от запланированного отчёта. Полезно, когда проект хочет, чтобы администраторы сообщества видели твиты официального аккаунта в реальном времени без проверки X.

📡 X Posts Auto-relay

Forward posts from X accounts to this chat as soon
as they're published. Posts can take up to 5
minutes to appear here after the original was
posted on X.

3 active relays:
▶️ @MyTokenOfficial    (4/10 today)
▶️ @MyTokenCEO         (1/10 today)
⏸ @MyTokenSupport     (0/10 today)

[ ▶️ @MyTokenOfficial ]
[ ▶️ @MyTokenCEO ]
[ ⏸ @MyTokenSupport ]
[ ➕ Add Account ]

Каждая трансляция опрашивает X API каждые 5 минут. Новые посты (с момента последней успешной пересылки) публикуются в чат как обычные URL — Telegram автоматически рендерит карточку предпросмотра X, так что текст поста виден.

Экран управления отдельной трансляцией позволяет оператору настроить поведение:

📡 X Posts Auto-relay › @MyTokenOfficial

State: ▶️ Active
Today: 4/10 forwarded
Polls every: 5 min

Post types to forward
☐ Retweets
☐ Replies (to other users)
✅ Quote tweets
✅ Thread continuations (self-replies)

Topic: (default — top of chat)

[ ⏸ Pause ] [ ✏️ Cap: 10/day ]
[ ☐ Retweets ] [ ☐ Replies ]
[ ✅ Quote tweets ] [ ✅ Thread ]
[ 💬 Set topic ] [ 🧹 Clear topic ]
[ 🗑 Delete relay ]

Настройка	Что делает
Лимит (1–100/день)	Максимум пересылок в чат за сутки UTC — при достижении трансляция молча прекращает пересылку до полуночи UTC. По умолчанию 10.
Пауза / Возобновить	Отключает расписание опроса для этой трансляции; восстановление создаёт его заново мгновенно.
Ретвиты	При ✅ ретвиты транслируемого аккаунта пересылаются. По умолчанию выключено.
Ответы	При ✅ ответы другим пользователям пересылаются. По умолчанию выключено.
Цитаты	При ✅ цитаты пересылаются. По умолчанию включено.
Продолжения треда	При ✅ ответы на собственные твиты (пользователь отвечает сам себе) пересылаются — покрывает Twitter-треды. По умолчанию включено. Выключите, если нужна только первая часть каждого треда.
Тема	Опциональный ID темы форума Telegram. Если задан, трансляция публикует только в эту тему вместо основного потока.

Автоочистка: если Telegram возвращает ошибку «чат исчез» (бота выгнали / заблокировали), трансляция автоматически удаляет своё расписание опроса и сохранённую конфигурацию. Утечек нет.

Жёсткий лимит: 10 трансляций на чат. При необходимости скорректируйте соответствующую константу.

ℹ️ О чате

ℹ️ About this chat

Chat ID: -1002593612414
Plan: PRO ✓
Schedule: daily 18:00 UTC
Project: MyToken

Диагностическая панель для запросов в поддержку.

Как /setup соотносится со слэш-командами

/setup дополняет — каждая существующая слэш-команда продолжает работать точно так же, как раньше. Меню оборачивает те же примитивы (buildQueryFromComponents, saveXBotSetting, createScheduleRule и т.д.), поэтому поведение идентично на обеих поверхностях. Опытные пользователи могут продолжать набирать /add_keywords DeFi airdrop для скорости по привычке; новички получают дружелюбный кликабельный интерфейс.

Три команды принципиально невозможно перенести в кнопки меню, потому что им нужен обычный текст + контекст сущностей сообщения Telegram, которого нет у callback:

Команда	Почему остаётся
/set_topic [name]	Захватывает message_thread_id темы, в которой отправлено сообщение, — у кнопки нет контекста темы
/add_admin @user	Полагается на проверенные сущности-упоминания Telegram для верификации админа чата
/set_x_filtering	Устаревшая слэш-команда для добавления именованного фильтра; то же самое делает ⤴ Именованные фильтры → ➕ Добавить именованный фильтр в меню

Готовые рецепты настройки

Частые цели → точные пути в меню. Каждый рецепт занимает одну-две минуты кликов.

«Отслеживать только оригинальные посты (без ретвитов, без ответов)»

Большинство сообществ хотят, чтобы лидерборд вознаграждал оригинальный контент, а не репосты.

/setup → 🎯 Фильтры → 🚫 Исключения → нажмите Ретвиты и Ответы, чтобы оба показывали ✅. Готово. Будущие выборки будут отправлять -is:retweet -is:reply в X API, а цитаты останутся.

«Вознаграждать ответы больше, чем лайки (построение сообщества)»

Очки по умолчанию: лайки 1×, ретвиты 2×, ответы 1.5×, цитаты 3×, просмотры 0.001. Чтобы сместить акцент на общение:

/setup → 🎨 Настройка → 📈 Настройка лидерборда → 🏆 Очки → отправьте:

1 1 5 3 0.001

Теперь ответы весят 5× — содержательное обсуждение обгоняет лайки мимоходом.

«Публиковать отчёты дважды в день»

По умолчанию расписание срабатывает не чаще раза в день. Чтобы получить отчёт в конце дня по ЕС и по США:

/setup → ⏰ Расписание → 🔧 Cron-выражение → отправьте:

cron(0 14,22 ? * * *)

Два срабатывания в день, в 14:00 и 22:00 UTC. Проверка минимальной частоты в 12 часов автоматически обеспечивает интервал ≥ 12 ч — более узкие окна отклоняются с понятной ошибкой.

«Отслеживать несколько кампаний одновременно в одной группе»

Три параллельные клиентские кампании, одна Telegram-группа, один отчёт на кампанию за срабатывание.

/setup → 🎯 Фильтры → ⤴ Именованные фильтры → ➕ Добавить именованный фильтр, затем отправьте по одному из следующих за раз:

campaign_a from:@kol1,@kol2 keywords:"#CampaignALaunch"
campaign_b from:@kol3,@kol4,@kol5 cashtags:$CBT
campaign_c from:@kol6 mention:@CampaignC_Official

Каждый срабатывает по тому же расписанию и публикует отдельный отчёт с меткой названия фильтра.

«Пересылать твиты аккаунта в реальном времени, между отчётами»

Важные новости от @MyTokenOfficial не должны ждать отчёта в 22:00 UTC.

/setup → 📡 Автотрансляция X-постов → ➕ Добавить аккаунт → отправьте:

@MyTokenOfficial 5

(Опциональное 5 — суточный лимит; по умолчанию 10.) Бот опрашивает каждые 5 минут, пересылает URL при новом посте, Telegram рендерит карточку предпросмотра.

«Ограничить отчёты окном кампании (например, 7-дневный рывок)»

Не хотите, чтобы шум до кампании засорял лидерборд.

/setup → 📊 Отчёты → 📆 Задать период → отправьте:

01/05/2026 7days

Теперь отчёты выбирают посты строго внутри этого окна. 🗑 Очистить период возвращает к скользящим 24 ч.

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

В группе есть темы; отчёты должны попадать в отдельную тему Отчёты.

Откройте тему Отчёты, затем изнутри неё отправьте:

/set_topic Reports

Будущие отчёты будут направляться в эту тему. Чтобы вернуть: /set_topic clear из любого места в группе.

«Уведомлять только двух конкретных админов при исчерпании кредитов»

Бот отправляет личные сообщения назначенным админам об ошибках кредитов / выборки / исчезновения чата. По умолчанию — всем админам чата; сузьте до выбранного списка.

/add_admin @alice @bob

Теперь сообщения идут только @alice и @bob. Чтобы очистить: /setup → 👥 Админы → 🗑 Очистить список уведомлений.

«Скрыть чат из публичной витрины xbot.ninja»

Портфолио соло-KOL скрываются автоматически (один пользователь не проходит порог ≥ 2 активных пользователя). Для проектов сообщества, которые должны оставаться приватными:

Явного переключателя скрытия нет — публичный листинг определяется порогами метрик. Два способа остаться приватным:

• Ведите небольшой / тихий чат, не достигающий порогов (топ-счёт пользователя < 300, постов < 5/месяц или активных пользователей < 2).
• Обратитесь в поддержку, чтобы отметить чат как исключение — публичный дашборд пропустит его независимо от метрик.

Прямой URL чата (https://xbot.ninja/?chatId=…) остаётся доступным в любом случае. Делитесь им только с теми, кому можно видеть данные.

Частые проблемы

Симптом	Причина	Решение
Расписание «отклонено» с FREQUENCY_ERROR	Cron пытается срабатывать чаще, чем раз в 12 ч	Проверка интервала — выбирайте промежутки не менее 12 часов. Сообщение об ошибке называет конфликтующую пару часов.
/setup не появляется в автодополнении	Список команд BotFather устарел	Бот принимает /setup независимо от автодополнения. Обновите BotFather → /setcommands, если важна обнаруживаемость.
Предпросмотр фильтра показывает пустые скобки / странный запрос	Какой-то компонент пуст	/setup → 🎯 Фильтры показывает буквальный запрос. Добавьте хотя бы один из: аккаунты / кэштеги / ключевые слова / упоминания.
Автотрансляция X-постов пересылает сразу целый тред	Ответы на собственные твиты обходят exclude=replies X API	/setup → 📡 Автотрансляция X-постов → @аккаунт → выключите ☐ Продолжения треда. Тогда бот оставит только начало треда.
Достигнут дневной лимит, а нужно больше	Достигнут MAX_POSTS_PER_DAY для трансляции	Нажмите ✏️ Лимит и увеличьте. Каждый пересланный пост считается одним кредитом.
Свой заголовок / цвет откатились за ночь	Настройка сохранилась, но обновление UPDATED_AT инвалидировало кэш рендера; следующая выборка покажет новое значение	Дождитесь одного цикла отчёта. Кэш рендера пересобирается при следующей выборке.
В отчёте везде «0 постов»	Ни один пост не подошёл под фильтр в настроенном периоде	Уберите период (скользящие 24 ч более щадящие) или расширьте фильтры. Часто это опечатка в кэштеге.
Бот «онлайн», но отчёты перестали приходить	Бота молча понизили из админов / выгнали	Проверьте Telegram → админы группы. Повторно назначьте, если отсутствует. Бот сам отключается при ошибках «чат исчез».

Готово

Финальный экран мастера подытоживает всё сохранённое и указывает на /setup → 📊 Отчёты → ⚡ Сформировать отчёт сейчас для мгновенного предпросмотра:

Это весь обзор. Введите /setup в своей группе, чтобы начать.

Столкнулись с проблемой при настройке пункта меню? Смотрите Устранение неполадок — матрицы «симптом → решение» по фильтрам, расписаниям и биллингу.