Ang /setup Menu: Buong Gabay sa Telegram UI ng X Bot

Ang pinakamabilis na paraan para i-configure ang X Bot ay ang interactive na /setup menu. Binabalot nito ang bawat admin command sa likod ng isang clickable, edit-in-place na interface — walang slash command na kailangang isaulo.

Pinakamabilis na paraan: idagdag ang bot sa iyong grupo, i-type ang /setup, i-tap ang 🚀 Quick Start, at sundan ang apat na prompt. Magkakaroon ka ng tumatakbong daily-report schedule sa isang totoong filter sa loob ng mas mababa sa dalawang minuto.

Ang hitsura ng /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 ]                                  ║
╚══════════════════════════════════════════════╝

Ipinapakita ng bawat screen ang iyong kasalukuyang estado sa itaas para malaman mo kung ano ang naka-configure bago ka magbago ng anuman. Instant na nase-save ang bawat pagbabago sa database — walang "save" button na dapat kalimutan.

Quick Start wizard

I-tap ang 🚀 Quick Start para sa isang apat-na-hakbang na linear flow na dinadala ang bagong chat mula sa "walang naka-configure" hanggang sa "unang naka-schedule na report" gamit ang pinakakaunting prompt. Laging available ang Skip at Exit — hindi ka babarahin ng isang wizard na hindi natapos, mananatili lang ang mga setting sa kanilang default.

Ang apat na hakbang:

Hakbang	Tanong	Nase-save sa
1	Pangalan ng proyekto	Setting na ProjectName (ginagamit sa mga report, leaderboard card, admin DM)
2	Ano ang susubaybayan sa X — accounts, cashtags, o keywords	Ang from, cashtags, o keywords array ng default na filter
3	Kailan ipo-post ang daily report — 4 na preset na oras o custom na HH:MM	Isang scheduled job na naka-key sa iyong chat
4	Tapos na — screen ng buod na may /recreate hint para mag-preview ngayon	(wala)

Ang buong menu

Ang bawat top-level button ay nagbubukas ng isang focused na screen. Mag-drill down nang malaya — bawat screen ay may ← Back pabalik sa nakaraang level at ✕ Close para i-dismiss.

🎯 Filters

Anong mga X post ang kinukuha ng bot sa bawat naka-schedule na takbo.

I-tap ang anumang kategorya para mag-drill down. Ang Excludes ay checkbox-style — isang tap lang para i-toggle ang "exclude retweets / replies / quote tweets".

Ang Named filters (advanced) ay nagpapahintulot sa iyong magpatakbo ng maraming filter sa parehong chat — kapaki-pakinabang kapag namamahala ka ng ilang client sa isang grupo. Bawat named filter ay may sariling per-row delete button na may confirmation tap. I-tap ang ➕ Add named filter para magpadala ng isang single-line na definition sa pamamagitan ng menu (name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam). Kailangan ng kahit isa sa from / keywords / cashtags / mention.

Ganito ang hitsura ng isang category screen — maikling deskripsyon kung ano ang ginagawa ng kategorya, ang kasalukuyang value, at mga aksyon na Add / Remove / Clear all:

Kapag tinap mo ang ➕ Add, papasok ang menu sa input mode — i-type ang iyong reply bilang normal na mensahe, at awtomatikong nag-re-redraw ang screen na may confirmation banner ("✓ 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

Kailan tumatakbo ang bot at nagpo-post ng daily report.

Apat na daily preset ang sumasaklaw sa karamihan ng komunidad. Ang kasalukuyang aktibong preset ay may ✓ prefix sa label nito. Ang Custom time ay humihingi ng HH:MM. Ang Specific days ay tumatanggap ng 14:30 Mon Wed Fri. Ang Cron ay tumatanggap ng standard cron expression (hal. cron(0 12 ? * MON-FRI *)). Ipinapatupad ng bot ang isang 12-oras na minimum frequency para mapanatiling predictable ang gastos.

Kung mag-tap ka ng schedule preset sa isang chat na walang filter, tatanggihan ng menu na may friendly error na tumuturo pabalik sa 🎯 Filters — hindi mag-i-schedule ang bot ng chat na walang kukunin.

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

Nililimitahan ng Set period ang mga report sa isang partikular na window (hal. isang kompetisyong tumatagal ng isang linggo). Format na DD/MM/YYYY Ndays o Nweeks. Ibinabalik ng Clear period sa default na rolling 24h. Ang Generate report now ay nagpapasimula ng parehong Step Function na ginagamit ng cron — kapaki-pakinabang para sa instant na preview. Ang Show last report ay tumuturo sa /report (na muling nagpo-post ng pinakahuling cached image nang zero credit cost).

🎨 Customization

Metadata ng proyekto na lumalabas sa mga report at sa pampublikong leaderboard.

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

Ang Leaderboard sub-tree ay naglalantad ng:

Setting	Format
🏆 Points	Limang numero, paghiwa-hiwalay ng space: likes retweets replies quotes views (hal. 5 1 20 10 0.01)
🎨 Colors	Limang hex color, parehong pagkakasunod-sunod
🔢 Top count	Buong numero 1..10 — ilang user ang nasa leaderboard
📛 Top title	Malayang text. Opsyonal na |#hex suffix para magtakda ng custom na kulay (hal. Top contributors|#FF8800)
🥇 Best-tweet title	Pareho
📊 Engagement title	Pareho

Ginagamit ng Logo upload ang existing photo handler ng bot — i-tap ang 🖼 Logo, pagkatapos ipadala ang imahe bilang Telegram photo (hindi file). Nire-resize at ino-upload ito ng bot sa website CDN.

Ang Topic ay nagtuturo sa iyong magpadala ng /set_topic mula sa loob ng gustong forum topic. Hindi makuha ng menu ang message_thread_id mula sa isang callback button, kaya nananatili itong slash-command surface.

👥 Admins & Notifications

Nililista ang mga user na tinalaga na tumanggap ng private DM tungkol sa pagkaubos ng credit, mga error sa fetch, at mga babala na hindi mahanap ang chat. Ang pagdaragdag ng admin ay nangangailangan pa rin ng /add_admin @user1 @user2 mula sa chat — ang mention parser ng Telegram ay tumatakbo lang sa totoong mensahe, hindi sa mga 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

Display ng plano + balance, kasama ang mga button na nagpapatakbo sa buy at manage flow. Iba ang pag-render ng screen depende sa kasalukuyang plano ng chat:

FREE na chat:

💳 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 na chat:

💳 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 na chat (binili sa ETH):

💳 Buy Credits & Plan

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

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

Ang button na 💰 Buy credits / upgrade ay nagpo-post ng payment-options card sa ilalim ng menu. Ang mga opsyong iniaalok ng bot ay depende sa kasalukuyang plano:

• FREE → parehong 💳 Pay with Credit Card (Stripe subscription) at 🪙 Pay with ETH (credit pack).
• PRO credits → parehong opsyon ay ipinapakita. Ang ETH ay nagdaragdag sa umiiral na balance; ang Stripe ay naglalagay ng subscription sa ibabaw (nananatili ang umiiral na ETH credits at ito muna ang nagagastos kada fetch).
• PRO subscription → walang buy option. Sasagot ang bot ng mensaheng "subscription exists" at ituturo ang 🛠 Manage patungo sa Stripe portal.

Binubuksan ng button na 🛠 Manage subscription ang Stripe Customer Portal sa iyong browser — doon mo ina-update ang iyong card, kanselahin, o i-download ang mga invoice. Makabuluhan lang ito kung mayroon kang aktibong Stripe subscription.

Ang sub-screen na 📊 Usage this month ay nagbubukod ng fetched_posts at fetch_attempts para sa kasalukuyang buwan at ngayong araw — kapaki-pakinabang para matukoy ang mga tahimik na kabiguan (mataas na attempts, zero posts → malamang na 402s o walang lamang query) at para ma-preview ang susunod mong Stripe invoice kapag palapit ka na sa 1 000-post na threshold.

Ang buy + manage ay maaabot din bilang legacy slash command na /buy at /subscription. Magkatulad ang behavior; ang mga button lang ng menu ang nagpepera sa iyo ng pag-type.

📡 X Posts Auto-relay

Pinapasa ang mga post mula sa mga piniling X account papunta sa chat sa sandaling na-publish ang mga ito — hiwalay sa naka-schedule na report. Kapaki-pakinabang kapag gusto ng isang proyekto na makita ng mga community admin ang mga opisyal-account na tweet nang real-time nang hindi kailangang tingnan ang 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 ]

Ang bawat relay ay nag-po-poll kada 5 minuto sa pamamagitan ng X API. Ang mga bagong post (mula noong huling matagumpay na forward) ay itinutulak papasok sa chat bilang plain na URL — awtomatikong ino-render ng Telegram ang X preview card kaya nakikita ang post body.

Per-relay na manage screen ay nagpapahintulot sa operator na i-tune ang behavior:

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

Setting	Ano ang ginagawa nito
Cap (1–100/araw)	Maximum na forward kada chat kada UTC na araw — kapag naabot, tahimik na hihinto ang relay na mag-forward hanggang hatinggabi UTC. Default 10.
Pause / Resume	Dine-disable ang polling schedule para sa relay na ito; ang pagpapanumbalik ay agad na gumagawa nito ulit.
Retweets	Kapag ✅, ipinapasa ang mga retweet ng na-relay na account. Naka-off bilang default.
Replies	Kapag ✅, ipinapasa ang mga reply sa ibang user. Naka-off bilang default.
Quote tweets	Kapag ✅, ipinapasa ang mga quote tweet. Naka-on bilang default.
Thread continuations	Kapag ✅, ipinapasa ang mga self-reply (isang user na sumasagot sa sariling tweet) — sinasaklaw nito ang mga Twitter thread. Naka-on bilang default. I-off ito kung gusto mo lang ng ulo ng bawat thread.
Topic	Opsyonal na Telegram forum-topic id. Kapag naka-set, nagpo-post lang ang relay sa topic na iyon sa halip na sa main thread.

Auto-cleanup: kung magbalik ang Telegram ng "chat-gone" na error (na-kick o na-block ang bot), awtomatikong aalisin ng relay ang polling schedule at naka-imbak na configuration nito. Walang leak.

Hard limit: 10 relay kada chat. I-adjust ang underlying constant kung kailangan mo ng higit pa.

ℹ️ About

ℹ️ About this chat

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

Isang diagnostics panel para sa mga support request.

Paano nauugnay ang /setup sa mga slash command

Ang /setup ay additive — nagpapatuloy pa ring gumana ang bawat umiiral na slash command tulad ng dati. Binabalot ng menu ang parehong primitives (buildQueryFromComponents, saveXBotSetting, createScheduleRule, atbp.), kaya magkatulad ang behavior sa pagitan ng dalawang surface. Puwedeng magpatuloy ang mga power user sa pag-type ng /add_keywords DeFi airdrop para sa bilis ng muscle-memory; nakakakuha naman ang mga bago ng friendly na clickable na surface.

Tatlong command ang talagang hindi puwedeng ilipat sa mga menu button dahil kailangan nila ng plain-text + Telegram message-entity context na wala sa mga callback:

Command	Bakit nananatili ito
/set_topic [name]	Kinukuha ang message_thread_id ng topic kung saan ipinadala ang mensahe — walang thread context ang isang button
/add_admin @user	Umaasa sa verified mention entities ng Telegram para sa chat-admin verification
/set_x_filtering	Legacy slash command para magdagdag ng named filter; ginagawa rin ito ng ⤴ Named filters → ➕ Add named filter ng menu

Mga configuration recipe

Karaniwang layunin → eksaktong menu path. Isa o dalawang minuto lang ng pag-click ang bawat recipe.

"Subaybayan lang ang mga orihinal na post (walang retweet, walang reply)"

Gusto ng karamihan ng komunidad na gantimpalaan ng leaderboard ang orihinal na content, hindi ang mga re-share.

/setup → 🎯 Filters → 🚫 Excludes → i-tap ang Retweets at Replies para parehong magpakita ng ✅. Tapos na. Ang mga susunod na fetch ay magpapadala ng -is:retweet -is:reply sa X API at mananatili ang mga quote tweet.

"Bigyan ng mas malaking gantimpala ang replies kaysa sa likes (community building)"

Default na points: likes 1×, retweets 2×, replies 1.5×, quotes 3×, views 0.001. Para paboran ang usapan:

/setup → 🎨 Customization → 📈 Leaderboard customization → 🏆 Points → ipadala:

1 1 5 3 0.001

Tumitimbang na ngayon ang replies nang 5× — nalalagpasan ng malalim na diskusyon ang mga drive-by na likes.

"Magpatakbo ng report dalawang beses sa isang araw"

Isang beses lang kada araw ang default na fire ng schedule. Para makakuha ng end-of-EU at end-of-US na report:

/setup → ⏰ Schedule → 🔧 Cron expression → ipadala:

cron(0 14,22 ? * * *)

Dalawang fire/araw sa 14:00 + 22:00 UTC. Awtomatikong ipinapatupad ng 12-oras na minimum frequency check ang ≥ 12h na espasyo — awtomatikong tinatanggihan ang mas makikitid na window na may malinaw na error.

"Subaybayan ang maraming campaign nang sabay-sabay sa isang grupo"

Tatlong sabay-sabay na campaign ng client, isang Telegram group, isang report kada campaign kada fire.

/setup → 🎯 Filters → ⤴ Named filters → ➕ Add named filter, pagkatapos ipadala ang isa sa mga ito sa bawat pass:

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

Bawat isa ay nagpapaputok sa parehong schedule at nagpo-post ng hiwalay na report na naka-tag sa pangalan ng filter.

"I-forward ang mga tweet ng isang account nang real-time, sa pagitan ng mga report"

Hindi dapat maghintay ang malaking balita mula sa @MyTokenOfficial para sa 22:00 UTC na report.

/setup → 📡 X Posts Auto-relay → ➕ Add Account → ipadala:

@MyTokenOfficial 5

(Opsyonal na 5 ay ang daily cap; default 10.) Nag-po-poll ang bot kada 5 minuto, ini-forward ang URL sa isang bagong post, ino-render ng Telegram ang preview card.

"Limitahan ang mga report sa isang campaign window (hal. 7-araw na push)"

Ayaw mong makahalo ang ingay bago ang campaign sa leaderboard.

/setup → 📊 Reports → 📆 Set period → ipadala:

01/05/2026 7days

Kukunin na ngayon ng mga report ang mga post nang mahigpit sa loob ng window na iyon. Ang 🗑 Clear period ay babalik sa rolling 24 h.

"Gawing mag-post ang mga report sa isang forum topic, hindi sa main thread"

Gumagamit ng topics ang grupo; dapat dumating ang mga report sa isang dedikadong Reports na topic.

Buksan ang Reports na topic, pagkatapos mula sa loob nito ipadala:

/set_topic Reports

Ang mga susunod na report ay ruruta sa topic na iyon. Para i-revert: /set_topic clear mula kahit saan sa grupo.

"Abisuhan ang dalawang partikular na admin kapag naubos na ang credits"

Nagpapadala ang bot ng DM sa mga tinalagang admin sa mga error sa credit / fetch / chat-gone. Bilang default, bumabalik ito sa lahat ng chat admin — paliitin sa isang curated na listahan.

/add_admin @alice @bob

Sa @alice at @bob na lang ngayon pupunta ang mga DM. Para i-clear: /setup → 👥 Admins → 🗑 Clear notification list.

"Itago ang chat mula sa pampublikong showcase ng xbot.ninja"

Awtomatikong nakatago ang mga solo-KOL portfolio (isang user lang, bumabagsak sa ≥ 2 aktibong user na threshold). Para sa mga community project na dapat manatiling private:

Walang explicit na hide toggle — ang pampublikong listing ay batay sa metric thresholds. Dalawang paraan para manatiling private:

• Magpatakbo ng maliit / tahimik na chat na hindi natutugunan ang mga threshold (top user score < 300, posts < 5/buwan, o active users < 2).
• Makipag-ugnayan sa support para itakda ang chat bilang exempt — laktawan ito ng pampublikong dashboard anuman ang metrics.

Ang direktang URL ng chat (https://xbot.ninja/?chatId=…) ay nananatiling accessible anuman ang mangyari. I-share lang ito sa mga taong dapat makakita ng data.

Mga karaniwang gotcha

Sintomas	Dahilan	Ayos
Schedule "rejected" na may FREQUENCY_ERROR	Sinusubukan ng cron na mag-fire nang mas madalas kaysa kada 12 h	Spacing check — pumili ng kahit ≥ 12-oras na agwat. Pinapangalanan ng error message ang nagkasalang pares ng oras.
Hindi lumalabas ang /setup sa autocomplete	Luma na ang BotFather command list	Tinatanggap ng bot ang /setup anuman ang autocomplete. I-update ang BotFather → /setcommands kung mahalaga ang discoverability.
Empty na parens o kakaibang query sa filter preview	May empty na component	Ipinapakita ng /setup → 🎯 Filters ang literal na query. Magdagdag ng kahit isa sa accounts / cashtags / keywords / mentions.
Nagfo-forward ang X Posts Auto-relay ng buong laman ng isang thread nang sabay-sabay	Naiiwasan ng self-replies ang exclude=replies ng X API	/setup → 📡 X Posts Auto-relay → @account → i-toggle na off ang ☐ Thread continuations. Pananatilihin na lang ng bot ang ulo ng thread.
Naabot na ang daily cap pero gusto ko ng mas marami	Naabot ang MAX_POSTS_PER_DAY para sa relay	I-tap ang ✏️ Cap at itaas. Bawat na-forward na post ay isang credit.
Nabalik ang custom title / kulay kinabukasan	Gumana ang pag-update ng setting pero ang bump ng UPDATED_AT ay nag-invalidate ng render cache; ipapakita ang bagong value sa susunod na fetch	Hintayin ang isang report cycle. Nire-rebuild ang render cache sa susunod na fetch.
"0 posts" ang report sa lahat ng dako	Walang post na tumugma sa filter sa naka-configure na panahon	Alisin ang period (mas mapagbigay ang rolling 24 h), o palawakin ang mga filter. Madalas ay typo lang sa isang cashtag.
"Online" ang bot pero tumigil ang mga report	Na-demote o na-kick ang bot mula sa admin	Tingnan ang Telegram → group admins. I-promote ulit kung kulang. Awtomatikong nagsa-self-disable ang bot sa mga chat-gone na error.

Tapos na

Bubuod sa huling screen ng wizard ang lahat ng na-save at ituturo ang /setup → 📊 Reports → ⚡ Generate report now para sa agarang preview:

Iyon na ang buong tour. I-type ang /setup sa iyong grupo para magsimula.

May isyu sa pag-configure ng isang menu item? Tingnan ang Troubleshooting para sa mga symptom-to-fix matrix na sumasaklaw sa filters, schedules, at billing.