Troubleshooting
Channels Troubleshooting
Fix Telegram, WhatsApp, Discord, and other channel problems.
Channels belong to the active engine.
If you configure Telegram on a VPS, the VPS engine is the process that receives Telegram messages and sends replies. The local xCloud app is only the control surface.
Telegram Does Not Reply
Check these in order:
- The active engine is the one where Telegram was configured.
- The BotFather token is pasted under the correct agent.
- Telegram shows Live or passes Check live status.
- The DM policy allows the sender.
- If policy is
pairing, the user sent the bot a message and you approved the pairing code. - The same bot token is not running in another engine.
Telegram can reject polling if the same token is active in two places. In that case, stop the other engine or use a different bot token.
Pairing
Pairing is the recommended DM policy.
Flow:
- User messages the Telegram bot.
- The bot replies with a pairing code.
- Admin pastes the code in xCloud.
- xCloud approves that sender.
- Future messages from that sender route to the agent.
WhatsApp links through a QR flow.
Important:
- Scan from WhatsApp Linked Devices, not the phone camera app.
- Keep the engine running.
- If it stops responding, relink the QR.
Common Problems
| Problem | Fix |
|---|---|
| UI says connected but bot does not reply | Run Check live status and confirm active engine |
| No pairing code arrives | Check token, DM policy, and whether another engine owns the token |
| Pairing approve fails | Use the latest code and correct channel |
| WhatsApp QR expires | Generate a new QR |
| Discord bot joins but does not respond | Check token, permissions, and channel routing |