🤖 Telegram Bot — System Map & Navigation

Full operator guide & troubleshooting for the DM Support Bot

🤖 What Does This Bot Do?
#FunctionDescription
1DM Support COREReceives user DMs and forwards them to an operator group as threaded conversations
2Feedback Logging TRACKRecords WORKS / FAILS feedback from users for daily reports
3Admin Ops ADMINReply to users, check profiles, broadcast — all from the group
4Unreplied Tracking MONITORTracks messages that haven't been answered yet so nothing gets missed
🔀 Message Flow
User → Operator Group
USER (DM to bot) │ │ 1. User sends a message to the bot in private chat │ ▼ BOT ENGINE │ │ 2. Bot creates / finds the user's thread in the DM group │ → Each user gets their own thread (not mixed in one timeline) │ → Anchor message = user profile (name, username, ID) │ │ 3. Bot forwards user's message into that thread │ → Tracks message in unreplied_tracking.json │ → Saves user info in known_users.jsonl │ ▼ DM OPERATOR GROUP │ │ 4. Admins see the message in the user's dedicated thread │ → Ready to reply
Admin → User (Reply)
DM OPERATOR GROUP │ │ 1. Admin replies to a user's message in the thread │ ▼ BOT ENGINE │ │ 2. Bot detects the reply → resolves user_id from thread map │ 3. Bot sends admin's message to the user's DM │ 4. Marks all pending messages from that user as replied │ ▼ USER (DM) │ │ User receives the reply directly from the bot
Edit & Delete Sync (Bidirectional)
ActionDirectionResult
User edits DMUser → GroupMessage in thread auto-updates
Admin edits reply in groupGroup → UserMessage in user's DM auto-updates
Admin deletes reply in groupGroup → UserMessage in user's DM auto-deleted
Edit sync fails—Bot posts "✏️ User edited message" notification in thread
User changes profileAuto-detectThread anchor updated + "🔄 Profile changed..." notification
Admin reacts to messageGroupAuto-marks user's message as replied
💬 Operator Groups
#GroupPurpose
1DM Operator Group MAINUser messages land here as threads. Admins reply from here.
2Log Group LOGCompact feedback logs (WORKS/FAILS). Not for replying to users.
📁 Data Storage
storage/ │ ├── sent_messages.jsonl → Log of set messages sent ├── feedback_events.jsonl → WORKS / FAILS feedback log ├── daily_reports.jsonl → Sent daily report history ├── known_users.jsonl → All detected users (id, name, username, last seen) ├── dm_threads.json → user_id → thread anchor map (persists across restarts) └── unreplied_tracking.json → Pending messages awaiting admin reply reports/ → Daily CSV report files
⌨️ Bot Commands
User Commands
/start PUBLIC
Starts the bot interaction. Bot sends a welcome message prompting the user to describe their problem. User can then chat freely with the bot.
Bot: "Hello! Please explain to us your problem, and prepare your anydesk. Just talk to me!"
Admin Commands ADMIN ONLY

Only the configured REPORT_USER_ID can use these. Non-admins get rejected.

/reportnow REPORT
Force-send the daily report immediately instead of waiting for the scheduled time.
/users [count] LOOKUP
List known users with their user_id, username, name, and last seen time. Default shows recent users.
/users /users 50
/whois <user_id> LOOKUP
Live profile lookup from Telegram API. Shows username, first/last name, bot/verified/scam/fake flags, and profile link. Can also be used by replying to a user's message in the thread.
/whois 7956767415
/dm <user_id> <message> MESSAGE
Send a direct personal message to a specific user without using the thread system.
/dm 7956767415 Halo, ini admin ya. Mau bantu follow up.
/broadcast <message> MASS
Send a message to all known users (except admin). Can also reply to any message and type /broadcast to use that message as content. Cannot be undone.
/broadcast Halo semuanya, ada update penting hari ini.
/unreplied [count] MONITOR
Show list of unanswered user messages (max 72h). Each entry includes a direct link to the message in the DM group. Ordered from oldest waiting. Default: 30 results.
/unreplied /unreplied 50
/mark_replied TRACK
Must reply to a user's message in the DM group thread. Marks that message (and all other pending messages from the same user) as replied.
/clear_replied CLEANUP
Remove all tracking entries that are already marked as replied. Cleans up accumulated data.
/purge_old [hours] CLEANUP
Delete tracking entries older than N hours (default: 72h).
/purge_old /purge_old 48
📋 How-To Guides
Reply to a User (Easiest Method)
💬 Reply via DM Group Thread
  1. Open the DM operator group
  2. Find the user's thread (each user has a dedicated thread)
  3. Click Reply on the user's message in that thread
  4. Type your response and Send
  5. Done! Bot delivers it to the user's DM automatically
Tips: No need to copy-paste user_id when replying from the thread. You can also give a reaction (emoji) to mark a message as handled without replying. Editing your reply in the group also updates it in the user's DM.
Contact a User Manually (Without Thread)
📨 Direct DM via Command
  1. Get user_id — run /users or /whois from a thread reply
  2. Send DM — /dm <user_id> <your message>
/users → found user ID: 7956767415 /dm 7956767415 Halo, saya dari tim support. Ada yang bisa dibantu?
Broadcast (Safe Procedure)
📡 Mass Message to All Users
  1. Write your draft message
  2. Test first — send to 1 user via /dm to check formatting
  3. If OK — run /broadcast <message>
  4. Check the summary: total targets, sent count, fail count
⚠️ Warning: Broadcast cannot be undone. Always test with /dm first to prevent typos going to all users.
📅 Daily Routine
🌅 Morning / Afternoon
  • Run /unreplied to check pending messages
  • Monitor the DM operator group for new threads
  • Reply to user threads as they come in
🌆 Evening
  • Check feedback log in the log group
  • Run /unreplied again for a double-check
🌙 End of Day
  • Wait for the automatic daily report, or run /reportnow
  • Run /clear_replied to clean up tracking data
🔧 Troubleshooting

Click any problem to expand the solution.

🚫 Admin replied in group but user didn't receive it ▶
  1. Check reply target — Make sure you replied to the correct message in the user's thread (not a random message)
  2. Not blank — Message must have content (not empty)
  3. User blocked bot? — If user blocked the bot, delivery will fail silently
  4. Bot console — Check error logs for delivery failures
📨 Can't send /dm to a specific user ▶
  1. User blocked bot — Bot can't DM users who blocked it
  2. Never started — User must have pressed /start at least once
  3. Deactivated account — Telegram account may be deleted or deactivated
  4. Wrong user_id — Double-check with /whois
🔄 Username / name changed — will it break? ▶
  1. No breakage — Bot uses user_id (numeric), not username
  2. Auto-update — Thread anchor is automatically updated with new name
  3. Notification — Bot sends "🔄 Profile changed..." in the thread
❌ Admin sent wrong reply to user ▶
  1. Delete the message in the DM group → it auto-deletes in user's DM
  2. Edit the message in the DM group → it auto-edits in user's DM
  3. Both operations are synced bidirectionally
📋 Too many unreplied messages piling up ▶
  1. Run /unreplied to see the full list with direct links
  2. Click links to jump directly to each pending message
  3. After handling, reply in thread or use /mark_replied
  4. React with emoji to bulk-acknowledge messages as handled
  5. Run /clear_replied to clean up resolved entries
  6. Run /purge_old 48 to remove stale entries (>48h)
📊 Daily report not being sent ▶
  1. Bot running? — Verify the bot process is active
  2. Manual trigger — Use /reportnow to force-send
  3. Check logs — Look at daily_reports.jsonl for last sent timestamp
  4. REPORT_USER_ID — Ensure the admin ID is correctly configured
🔇 Feedback not logging ▶
  1. Button callback — Check if ✅ / ❌ buttons are properly set up
  2. Log group — Verify bot has permission to post in the log group
  3. Storage — Check feedback_events.jsonl is writable
⚡ Quick Reference Cheat Sheet

If you forget everything else, remember this table.

I want to...Do this
Reply to a userReply to their message in the DM group thread
Check who someone is/whois <user_id>
DM someone directly/dm <user_id> <message>
Mass message everyone/broadcast <message>
See all known users/users
See unanswered messages/unreplied
Mark message as handled/mark_replied (reply to msg) or give a reaction
Clean up tracking/clear_replied
Remove old entries/purge_old or /purge_old 48
Fix a wrong replyEdit or Delete message in group → syncs to user
Force daily report/reportnow
📌 Team Rules (Prevent Chaos)
  1. Always reply via thread in the DM group — never DM users outside the bot
  2. Never broadcast without testing on 1 user via /dm first
  3. Use /whois when unsure about a user's identity
  4. Use /users to track active users
  5. Check /unreplied at least 2x daily (morning & evening)
  6. Give a reaction if a message is handled but doesn't need a text reply

🔒 Enter Password