Меню /setup: повний посібник з Telegram-інтерфейсу X Bot

Найшвидший спосіб налаштувати X Bot — інтерактивне меню /setup. Воно огортає кожну адмін-команду в клікабельний інтерфейс редагування на місці — жодних slash-команд запам'ятовувати не треба.

Найшвидший шлях: додайте бота у свою групу, введіть /setup, натисніть 🚀 Quick Start і пройдіть чотири кроки. Розклад щоденних звітів на реальному фільтрі запрацює менш ніж за дві хвилини.

Як виглядає /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 ]                                  ║
╚══════════════════════════════════════════════╝

Кожен екран показує ваш поточний стан вгорі, тож ви знаєте, що налаштовано, перш ніж щось змінювати. Кожна зміна зберігається в базі даних миттєво — немає кнопки "зберегти", про яку можна забути.

Майстер Quick Start

Натисніть 🚀 Quick Start для лінійного потоку з чотирьох кроків, який переводить свіжий чат від "нічого не налаштовано" до "перший запланований звіт" з мінімальною кількістю запитів. Skip і Exit завжди доступні — частково пройдений майстер ніколи вас не блокує, налаштування просто залишаються за замовчуванням.

Чотири кроки:

Крок	Запитує	Зберігає в
1	Назва проєкту	Налаштування ProjectName (використовується у звітах, картках лідерборду, адмін-DM)
2	Що відстежувати в X — акаунти, кештеги чи ключові слова	Масиви from, cashtags чи keywords фільтра за замовчуванням
3	Коли публікувати щоденний звіт — 4 пресети або власний HH:MM	Запланована задача, прив'язана до вашого чату
4	Готово — екран підсумку з підказкою /recreate для попереднього перегляду зараз	(немає)

Повне меню

Кожна кнопка верхнього рівня відкриває цільовий екран. Заглиблюйтеся вільно — на кожному екрані є ← Back до попереднього рівня та ✕ Close для закриття.

🎯 Filters

Які пости X отримує бот на кожному запланованому запуску.

Торкніться будь-якої категорії, щоб заглибитися. Excludes — у форматі чекбоксів: одне натискання перемикає "виключити ретвіти / відповіді / цитати".

Named filters (розширено) дозволяє тримати кілька фільтрів одночасно в одному чаті — корисно, коли ви керуєте кількома клієнтами в одній групі. Кожен іменований фільтр має власну кнопку видалення з підтвердженням натисканням. Торкніться ➕ Add named filter, щоб надіслати однорядкове визначення через меню (name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam). Потрібен принаймні один з from / keywords / cashtags / mention.

Екран категорії виглядає так — короткий опис того, що робить категорія, поточне значення та дії Add / Remove / Clear all:

Коли ви торкаєтеся ➕ Add, меню переходить у режим вводу — введіть свою відповідь як звичайне повідомлення, і екран автоматично перемалюється з банером підтвердження ("✓ Added 2 cashtags: $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]

⏰ Schedule

Коли бот запускається і публікує щоденний звіт.

Чотири щоденні пресети покривають більшість спільнот. Наразі активний пресет отримує префікс ✓ у своєму лейблі. Custom time запитує HH:MM. Specific days приймає 14:30 Mon Wed Fri. Cron приймає стандартні cron-вирази (напр., cron(0 12 ? * MON-FRI *)). Бот застосовує мінімальну частоту 12 годин, щоб тримати витрати передбачуваними.

Якщо ви торкнетеся пресета розкладу в чаті без фільтрів, меню відмовить із дружньою помилкою, вказуючи назад на 🎯 Filters — бот не планує чат, якому нічого отримувати.

📊 Reports & Period

📊 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]

Set period обмежує звіти конкретним вікном (напр., змагання тривалістю тиждень). Формат DD/MM/YYYY Ndays або Nweeks. Clear period повертає до стандартного плаваючого 24-годинного вікна. Generate report now запускає ту саму Step Function, що й cron — корисно для миттєвого перегляду. Show last report вказує на /report (яке повторно публікує останнє кешоване зображення без витрати кредитів).

🎨 Customization

Метадані проєкту, що відображаються у звітах і на публічному лідерборді.

🎨 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]

Гілка Leaderboard містить:

Налаштування	Формат
🏆 Points	П'ять чисел через пробіл: likes retweets replies quotes views (напр., 5 1 20 10 0.01)
🎨 Colors	П'ять hex-кольорів у тому ж порядку
🔢 Top count	Ціле число 1..10 — скільки користувачів у лідерборді
📛 Top title	Довільний текст. Опційний суфікс |#hex встановлює власний колір (напр., Top contributors|#FF8800)
🥇 Best-tweet title	Так само
📊 Engagement title	Так само

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

Topic інструктує вас надіслати /set_topic зсередини потрібної форум-теми. Меню не може захопити message_thread_id з callback-кнопки, тому це залишається поверхнею для slash-команди.

👥 Admins & Notifications

Показує чати, чиї користувачі призначені отримувати приватні DM про вичерпання кредитів, помилки отримання даних і попередження "chat-not-found". Додавання адмінів все ще вимагає /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]

💳 Buy Credits & Plan

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

Чат 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 subscription:

💳 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 credits (куплені за ETH):

💳 Buy Credits & Plan

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

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

Кнопка 💰 Buy credits / upgrade публікує картку з варіантами оплати під меню. Опції, які пропонує бот, залежать від поточного тарифу:

• FREE → і 💳 Pay with Credit Card (підписка Stripe), і 🪙 Pay with ETH (пакет кредитів).
• PRO credits → показано обидва варіанти. ETH поповнює наявний баланс; Stripe додає підписку зверху (наявні кредити ETH залишаються і списуються першими при кожному запиті).
• PRO subscription → варіантів покупки немає. Бот відповідає повідомленням "subscription exists" і вказує на 🛠 Manage, щоб перейти в портал Stripe.

Кнопка 🛠 Manage subscription відкриває Клієнтський портал Stripe у вашому браузері — саме там ви оновлюєте картку, скасовуєте підписку чи завантажуєте рахунки. Має сенс лише за наявності активної підписки Stripe.

Підекран 📊 Usage this month розбиває fetched_posts та fetch_attempts за поточний місяць і сьогодні — корисно для виявлення тихих збоїв (багато спроб, нуль постів → ймовірно 402 або порожні запити) та для попереднього перегляду наступного рахунку Stripe, коли ви наближаєтеся до порогу 1000 постів.

Купівля + керування також доступні як застарілі slash-команди /buy і /subscription. Поведінка ідентична; кнопки меню просто заощаджують введення.

📡 X Posts Auto-relay

Пересилає пости обраних акаунтів 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 ]

Кожен relay опитує X API кожні 5 хвилин. Нові пости (з моменту останньої успішної пересилки) публікуються в чат як звичайні URL — Telegram автоматично рендерить превью-картку X, тож тіло поста видно.

Екран керування окремим relay дозволяє оператору налаштувати поведінку:

📡 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 ]

Налаштування	Що воно робить
Cap (1–100/day)	Максимум пересилань на чат за добу UTC — по досягненні relay мовчки припиняє пересилання до півночі UTC. За замовчуванням 10.
Pause / Resume	Вимикає розклад опитування для цього relay; відновлення відразу пересоздає його.
Retweets	Коли ✅, ретвіти relay-акаунта пересилаються. За замовчуванням вимкнено.
Replies	Коли ✅, відповіді іншим користувачам пересилаються. За замовчуванням вимкнено.
Quote tweets	Коли ✅, цитати пересилаються. За замовчуванням увімкнено.
Thread continuations	Коли ✅, самовідповіді (користувач відповідає на власні твіти) пересилаються — покриває треди Twitter. За замовчуванням увімкнено. Вимкніть, якщо потрібна лише голова кожного треду.
Topic	Опційний ID форум-теми Telegram. Коли встановлено, relay публікує лише в цю тему, а не в основну гілку.

Auto-cleanup: якщо Telegram повертає помилку "chat-gone" (бота вигнали/заблокували), relay автоматично видаляє свій розклад опитування та збережене налаштування. Без витоків.

Жорсткий ліміт: 10 relay на чат. За потреби налаштуйте базову константу.

ℹ️ About

ℹ️ About this chat

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

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

Як /setup співвідноситься зі slash-командами

/setup додатковий — кожна наявна slash-команда продовжує працювати точно як раніше. Меню огортає ті самі примітиви (buildQueryFromComponents, saveXBotSetting, createScheduleRule тощо), тому поведінка ідентична між двома інтерфейсами. Досвідчені користувачі можуть і далі вводити /add_keywords DeFi airdrop для швидкості м'язової пам'яті; новачки отримують дружній клікабельний інтерфейс.

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

Команда	Чому залишається
/set_topic [name]	Захоплює message_thread_id теми, в якій було надіслано повідомлення — у кнопки немає контексту теми
/add_admin @user	Покладається на верифіковані сутності згадок Telegram для перевірки адмінства чату
/set_x_filtering	Застаріла slash-команда для додавання іменованого фільтра; те саме робить ⤴ Named filters → ➕ Add named filter у меню

Рецепти налаштування

Часті цілі → точні шляхи в меню. Кожен рецепт — одна-дві хвилини кліків.

"Відстежувати лише оригінальні пости (без ретвітів, без відповідей)"

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

/setup → 🎯 Filters → 🚫 Excludes → торкніться Retweets і Replies, щоб обидва показували ✅. Готово. Майбутні запити надсилатимуть -is:retweet -is:reply до X API, а цитати залишаться.

"Винагороджувати відповіді більше, ніж лайки (розбудова спільноти)"

Бали за замовчуванням: лайки 1×, ретвіти 2×, відповіді 1.5×, цитати 3×, перегляди 0.001. Щоб надати перевагу обговоренню:

/setup → 🎨 Customization → 📈 Leaderboard customization → 🏆 Points → надішліть:

1 1 5 3 0.001

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

"Публікувати звіти двічі на день"

Розклад спрацьовує максимум раз на день за замовчуванням. Щоб отримати звіт наприкінці ЄС і наприкінці США:

/setup → ⏰ Schedule → 🔧 Cron expression → надішліть:

cron(0 14,22 ? * * *)

Два запуски на день о 14:00 + 22:00 UTC. Перевірка мінімальної частоти 12 годин автоматично забезпечує проміжок ≥ 12 год — вужчі вікна відхиляються з чіткою помилкою.

"Відстежувати кілька кампаній одночасно в одній групі"

Три паралельні клієнтські кампанії, одна група Telegram, один звіт на кампанію на запуск.

/setup → 🎯 Filters → ⤴ Named filters → ➕ Add named filter, потім надішліть одне з цього на кожен прохід:

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 Posts Auto-relay → ➕ Add Account → надішліть:

@MyTokenOfficial 5

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

"Обмежити звіти вікном кампанії (напр., 7-денний спурт)"

Не хочете, щоб шум до кампанії забруднював лідерборд.

/setup → 📊 Reports → 📆 Set period → надішліть:

01/05/2026 7days

Тепер звіти отримують пости строго в межах цього вікна. 🗑 Clear period повертає до плаваючого вікна 24 год.

"Публікувати звіти у форум-тему, а не в основну гілку"

Група використовує теми; звіти мають потрапляти в окрему тему Reports.

Відкрийте тему Reports, потім зсередини неї надішліть:

/set_topic Reports

Майбутні звіти маршрутизуються в цю тему. Щоб скасувати: /set_topic clear з будь-якого місця в групі.

"Сповіщати двох конкретних адмінів, коли закінчуються кредити"

Бот DM-ить призначених адмінів про помилки кредитів / запитів / chat-gone. За замовчуванням він відкатується до всіх адмінів чату — звузьте до обраного списку.

/add_admin @alice @bob

Тепер DM надходять лише @alice і @bob. Щоб очистити: /setup → 👥 Admins → 🗑 Clear notification list.

"Приховати чат з публічної вітрини xbot.ninja"

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

Явного перемикача приховування немає — публічний лістинг обмежений порогами метрик. Два способи залишитися приватними:

• Ведіть маленький / тихий чат, що не досягає порогів (top user score < 300, постів < 5/місяць, або активних користувачів < 2).
• Зверніться до підтримки, щоб позначити чат як виняток — публічний дашборд пропускає його незалежно від метрик.

Прямий URL чату (https://xbot.ninja/?chatId=…) залишається доступним у будь-якому разі. Діліться ним лише з тими, хто повинен бачити ці дані.

Часті проблеми

Симптом	Причина	Виправлення
Розклад "відхилено" з FREQUENCY_ERROR	Cron намагається спрацьовувати частіше, ніж раз на 12 год	Перевірка проміжку — оберіть проміжок щонайменше 12 годин. Повідомлення про помилку називає пару годин, що конфліктує.
/setup не з'являється в автозаповненні	Список команд BotFather застарів	Бот приймає /setup незалежно від автозаповнення. Оновіть BotFather → /setcommands, якщо важлива виявність.
Попередній перегляд фільтра показує порожні дужки / дивний запит	Якийсь компонент порожній	/setup → 🎯 Filters показує буквальний запит. Додайте принаймні один з: акаунти / кештеги / ключові слова / згадки.
X Posts Auto-relay пересилає цілий тред одразу	Самовідповіді обходять exclude=replies X API	/setup → 📡 X Posts Auto-relay → @account → вимкніть ☐ Thread continuations. Бот тоді залишає лише голову треду.
Денний ліміт досягнуто, а потрібно більше	Досягнуто MAX_POSTS_PER_DAY для relay	Торкніться ✏️ Cap і підвищіть. Кожен пересланий пост рахується як один кредит.
Власний заголовок / колір відкотився за ніч	Оновлення налаштувань спрацювало, але оновлення UPDATED_AT інвалідувало кеш рендеру; наступний запит покаже нове значення	Зачекайте один цикл звіту. Кеш рендеру перебудовується на наступному запиті.
У звіті скрізь "0 постів"	Жоден пост не відповідав фільтру в налаштованому періоді	Приберіть період (плаваючі 24 год толерантніші), або розширте фільтри. Часто це помилка в кештегу.
Бот "онлайн", але звіти перестали приходити	Бота розжалувано з адмінів / вигнано мовчки	Перевірте Telegram → адміни групи. Повторно призначте, якщо відсутній. Бот самовимикається при помилках chat-gone.

Готово

Останній екран майстра підсумовує все збережене і вказує на /setup → 📊 Reports → ⚡ Generate report now для миттєвого перегляду:

Це весь огляд. Введіть /setup у своїй групі, щоб почати.

Виникла проблема з налаштуванням пункту меню? Дивіться Усунення несправностей для матриць "симптом → рішення" щодо фільтрів, розкладів і рахунків.