X Bot

Appearance

Support ​

Most issues fix themselves with a single /setup action. The first half of this page walks you through the self-diagnosis flow; the second half is a FAQ. If neither resolves it, the contact form at the bottom routes directly to the BWS developer support channel.

First — self-diagnosis flow ​

Open /setup → ℹ️ About in your chat.
└─ Copy that text. It's everything support needs to triage.

Then ask yourself, in order:

  1. Does the bot reply to /setup at all?
     ├─ No  → bot was kicked or demoted from admin → re-promote and retry
     └─ Yes → continue.

  2. Did /setup → 📊 Reports → ⚡ Generate report now produce something
     within 3 minutes?
     ├─ No DM, no post → check next question.
     ├─ DM "no posts found"  → filter too narrow or no on-topic posts;
                                /setup → 🎯 Filters to see
                                the literal X API query.
     ├─ DM "credit exhausted" → /setup → 💳 Buy Credits → 💰 Buy.
     ├─ Post landed but image looks wrong → re-fire; if persistent,
                                contact support with the chat ID.
     └─ Post landed correctly → you're fine.

  3. Are scheduled reports arriving?
     ├─ No  → /setup top screen shows the cron. Compare to actual UTC time.
              The bot's first scheduled fire happens AFTER the next cron tick,
              not immediately after setup.
     └─ Yes → all good.

If none of those land you on a fix, scroll past the FAQ to the contact link.

FAQ ​

Setup & install ​

Q. The bot doesn't reply when I add it. Confirm it's promoted to admin, not just "member". Telegram → group settings → Administrators. Re-promotion is instant; the bot doesn't need re-install.

Q. Can I move the bot to a different group? Yes — add it to the new group, run /setup there. The two chats are independent (different chat IDs = different settings, schedules, scores). There's no data migration between chats.

Q. The bot reports in the main thread, but my group has topics — can I redirect? From inside the desired forum topic, send:

/set_topic Reports

Future reports route to that topic. Reset with /set_topic clear.

Q. How do I uninstall?

  • Stop reports first: /setup → ⏰ Schedule → ✕ Disable schedule.
  • Remove the bot: Telegram → group → admins → kick @BWS_X_Bot.
  • Settings stay in the database. Re-adding the bot to the same chat ID resumes everything. Ask support for hard delete.

Reports & filtering ​

Q. Why are my numbers different from third-party trackers? X Bot pulls directly from the official X API. Most third-party trackers scrape or extrapolate — we've measured discrepancies of 20–50%. The X API number is the source of truth.

Q. The leaderboard shows users I didn't expect to track. Filters are additive. If a chat tracks $YOUR_TOKEN cashtag, anyone tweeting that cashtag gets ranked, not just the accounts you listed. To require both an account and a cashtag, use the from:@x cashtags:$YOUR_TOKEN form via /set_x_filtering (the AND-of-everything semantic of named filters).

Q. The report says "0 posts" — what now? Three possibilities, in order of likelihood:

  1. Filter too narrow — /setup → 🎯 Filters shows the literal X API query. Common typo: $BTC (trailing space) vs $BTC.
  2. Period too narrow — if you set a custom period, posts outside that window don't count. /setup → 📊 Reports → 🗑 Clear period reverts to rolling 24 h.
  3. The accounts you track really posted nothing on-topic in 24 h — extend with cashtags or keywords for fallback signal.

Q. Can I track a private/protected X account? No — the X API only returns public posts.

Q. Can I exclude specific users from a chat's leaderboard (e.g. spam bots)? Yes: /setup → 🎯 Filters → 🙈 Ignore → ➕ Add. Listed handles are dropped from results post-fetch.

Q. Why does my chat have multiple report fires per day? Either you set a multi-fire cron (cron(0 14,22 ? * * *)) or you have multiple named filters running on the same schedule. Each named filter produces its own report.

Q. The "Best Tweet" pick seems weird. The AI selector picks the highest-engagement post that wasn't picked recently. If results consistently feel off, contact support — the prompt is tunable.

X Posts Auto-relay ​

Q. The relay forwarded a thread of 6 posts at once. I only wanted the first. That's the X API's exclude=replies only filtering replies to other users; self-replies (thread continuations) bypass it. /setup → 📡 X Posts Auto-relay → @account → toggle ☐ Thread continuations off. The bot then keeps only the head of each thread.

Q. The relay stopped forwarding mid-day. Check the per-relay screen — if Today: 10/10 forwarded, you hit the daily cap. Tap ✏️ Cap to raise. Cap auto-resets at midnight UTC.

Q. The relay shows ⏸ Paused but I never paused it. The bot auto-pauses on Telegram chat-gone errors (kicked / blocked / chat upgraded) and stops the polling schedule. /setup → 📡 X Posts Auto-relay shows the row in case you re-add the bot.

Billing & credits ​

Q. What's a "credit" exactly? One credit = one post returned by the X API. FREE chats get 100 free credits/month; PRO chats are billed via Stripe (subscription) or ETH (credit pack).

Q. Where do I see my credits balance?/setup → 💳 Buy Credits. Shows used / remaining / reset date.

Q. I just paid but my balance / plan didn't update.

  • Stripe path (card subscription): the webhook usually activates PRO within seconds. If 5+ minutes later you don't see PRO ✓ in /setup → 💳 Buy Credits, contact support with your Stripe receipt and chat ID.
  • ETH path (credit pack): the on-chain confirmation can take 1–3 minutes. If after 10 minutes credits don't show, contact support with the transaction hash and chat ID.

Q. Can I have both a Stripe subscription AND ETH credits on the same chat? Yes — they layer. A PRO·credits chat that subscribes keeps its existing ETH balance, and per-fetch billing drains ETH credits first before the subscription's monthly grant kicks in. Practical effect: if you have 5 000 ETH credits and subscribe, the first 5 000 fetches don't touch Stripe at all; subsequent fetches use the sub's 1 000/mo grant; anything beyond is $0.02/post metered overage. The ETH balance never expires.

The one constraint: a chat already on PRO·sub can't add a fresh ETH pack from the same buy flow today (the buy command blocks it). Cancel the subscription first if you want to switch back to credits-only.

Q. What happens when my PRO·credits balance hits zero? The license is automatically downgraded to FREE. The bot keeps fetching under the 100/month FREE cap until that's exhausted too. The next /setup → 💳 → 💰 Buy then offers both paths again.

Q. Is the credits balance per-chat or per-user? Per-chat. Each Telegram group has its own credits and license.

Public dashboard ​

Q. My project doesn't show on xbot.ninja. Three thresholds must all be met in the current month:

  • Top user score ≥ 300
  • Tracked posts ≥ 5
  • Active users ≥ 2

The first month is usually the bottleneck. Direct URL https://xbot.ninja/?chatId=<your-id> works regardless.

Q. How do I find my chat ID?/setup → ℹ️ About. The negative-prefixed long integer.

Q. Can I customise the public xbot.ninja card?/setup → 🎨 Customization. Set Name, Description, Logo, URLs. The card refreshes on the next report cycle.

X API quirks ​

Q. Why are some posts older than expected counted? The bot uses tweets/search/all (full-archive endpoint). When you set a period, the bot can fetch posts from any time inside it. The default is rolling 24 h, but a custom period can be backdated.

Q. Sometimes a post takes 5+ minutes to appear in a relay. X Posts Auto-relay polls every 5 minutes. Latency is up to one polling interval (~2.5 min average / ~5 min worst case). Plus brief X API + Telegram delivery latency.

Q. The X API returned an error — what does the operator see? Internal error counters tick up; designated admins receive a private DM (/setup → 👥 Admins to configure who). Common 4xx codes: 401/403 (operator-side credentials), 402 (credits depleted), 429 (rate-limited — bot retries with backoff).

What to include in a support request ​

Copy and paste this template:

Project: <your project name>
Chat ID: <from /setup → ℹ️ About>
Plan: FREE / PRO·credits / PRO·sub
What's wrong: <1–2 sentences>
What you tried: </setup → … → … steps you ran>
When it broke: <approx UTC time>
Recent change: <any new filter / schedule / payment in the last 24 h>

The chat ID alone gives support 80% of triage information — please always include it.

Expected response times ​

  • Critical: bot offline platform-wide, billing failures → response within 1 business hour during EU+US business overlap
  • High: report not delivering for a single chat → same business day
  • Normal: feature questions, configuration help → 1–2 business days

X Bot Documentation

Copyright © 2026 bws.ninja. All rights reserved.