Bots Page Error Recovery Playbook

Summary

Use this playbook when connection or management actions fail during live operations and you need predictable recovery steps. For operators, this page should be used as a decision surface, not only as a UI form. Always pair page actions with downstream validation in the relevant live workflow.

What this page is for

• Speed up operator incident handling.
• Reduce trial-and-error during bot outages.
• Keep bot operations stable under pressure.

Before you start

• Capture exact error text before retrying.
• Confirm workspace and bot identity.
• Avoid multiple simultaneous edits from different operators.

Step-by-step workflow

1. Identify failing action (connect, toggle, rename, delete).
2. Capture displayed toast/message text.
3. Apply targeted fix for that failure category.
4. Retry once with clean state (refresh if needed).
5. Validate outcome in UI and downstream page.
6. Escalate only with exact error evidence.

Key states and error handling

• Connect: 'Unable to connect bot'.
• Toggle: 'Unable to update bot'.
• Delete: 'Unable to delete bot'.

Best practices

• Keep a shared internal error log with timestamp and bot id.
• Retry once after fix; avoid rapid repeated clicks.
• Verify downstream modules after bot changes.

Troubleshooting

• Persistent connect failures: rotate token and retry.
• Persistent toggle failures: check billing/plan gates.
• Persistent delete failures: re-open page and validate permissions.
• If issue persists after one clean retry, capture exact toast/banner text, selected bot, and timestamp before escalation.

UI reference (what each control does)

• Bot name is a workspace label used by operators; token validity is handled by backend verification.
• Connect action creates the bot record and triggers availability in other modules.
• AI toggle is constrained by plan, wallet, and business connection prerequisites.
• Rename is inline and should be committed only after checking bot identity.
• Delete is permanent and should be treated as irreversible operational cleanup.
• Wallet readiness for non-admin paths is tied to funded state and minimum thresholds.
• Business connection health directly impacts downstream Fan Inbox usage.
• Toast messages are the fastest failure classifier during onboarding incidents.

Operator checklist (before shipping changes)

• Validate token source before connect (BotFather-issued token only).
• Send /start in Telegram immediately after connection to complete handshake.
• Set an unambiguous bot display name for multi-bot workspaces.
• Check business connection and plan status before enabling AI.
• Do not delete a bot still used by active scripts or welcome flows.
• Record high-impact bot lifecycle changes in your internal changelog.

Real-world scenario

A bot appears connected but AI cannot be enabled. The operator checks wallet readiness, confirms plan state, and validates business connection. After prerequisites are fixed, AI toggle succeeds and inbox behavior normalizes.

1. Identify the exact scope (bot, period, module) before any change.
2. Apply one targeted correction based on observed UI state and messages.
3. Validate outcome in the live operational flow linked to this page.
4. Document the final state so future incidents can be solved faster.