#21757: Docs/telegram inbound troubleshooting

## Summary Describe the problem and fix in 2–5 bullets: - Problem: Telegram messages can reach the Bot API (`getUpdates` / `getWebhookInfo`) but never make it to the Agent, especially after an update. - Why it matters: From the user’s point of view the bot looks “alive” (status OK, outbound replies work), but inbound messages silently fail, breaking Telegram as a primary channel. - What changed: Added a troubleshooting accordion to the upstream Telegram channel docs describing this scenario, with concrete checks (logs, webhook state, channel status) and what information to include when reporting it in OpenClaw. - What did NOT change (scope boundary): No runtime behavior, channel logic, or gateway code was modified—this PR is documentation only. ## Change Type (select all) - [ ] Bug fix - [ ] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [ ] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [x] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes # - Related # (If there is a GitHub issue describing this exact scenario, reference it here. Otherwise you can leave these blank or add “Related” once an issue exists.) ## User-visible / Behavior Changes List user-visible changes (including defaults/config). If none, write None. - New troubleshooting accordion in `docs/channels/telegram.md` for the “messages stuck at Telegram API” scenario. - No behavior change to the Telegram integration itself; this is documentation only. ## Security Impact (required) - New permissions/capabilities? (Yes/No) No. - Secrets/tokens handling changed? (Yes/No) No. - New/changed network calls? (Yes/No) No. - Command/tool execution surface changed? (Yes/No) No. - Data access scope changed? (Yes/No) No. If any Yes, explain risk + mitigation: N/A ## Repro + Verification ### Environment - OS: N/A (docs-only change) - Runtime/container: N/A - Model/provider: N/A - Integration/channel (if any): Telegram - Relevant config (redacted): N/A ### Steps 1. Open `docs/channels/telegram.md` in the rendered docs. 2. Scroll to the **Troubleshooting** section. 3. Expand the accordion titled “Messages reach Telegram API but never reach the Agent”. ### Expected - The new troubleshooting section clearly describes the “stuck at API” scenario, with concrete checks (`logs`, `getWebhookInfo`, `channels status`) and hints on what to include when reporting a regression. ### Actual - Matches the expected behavior above. ## Evidence Attach at least one: - [x] Doc diff showing the new troubleshooting accordion - [ ] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) ## Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: - Rendered the updated `docs/channels/telegram.md` locally to confirm the new accordion appears under the Troubleshooting section and renders correctly as markdown/HTML. - Edge cases checked: - Verified that the new section does not alter existing headings, anchors, or config reference content. - What you did not verify: - Did not reproduce or fix the underlying runtime regression; this PR only documents how to detect and report it. ## Compatibility / Migration - Backward compatible? (Yes/No) Yes. - Config/env changes? (Yes/No) No. - Migration needed? (Yes/No) No. If yes, exact upgrade steps: N/A ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: Revert this PR or remove the new accordion block from `docs/channels/telegram.md`. - Files/config to restore: `docs/channels/telegram.md` - Known bad symptoms reviewers should watch for: Broken markdown rendering or malformed HTML in the Telegram docs Troubleshooting section. ## Risks and Mitigations List only real risks for this PR. Add/remove entries as needed. If none, write None. - Risk: Minor risk of duplicated or slightly overlapping troubleshooting guidance if future docs add similar content. - Mitigation: Keep this section focused on the “messages stuck at API, not reaching Agent” scenario and update it if the main troubleshooting page is refactored. <!-- greptile_comment --> <h3>Greptile Summary</h3> Adds a new troubleshooting accordion to `docs/channels/telegram.md` addressing a specific scenario where Telegram messages reach the Bot API but never make it to the OpenClaw Agent. The addition provides clear symptoms, diagnostic steps, and instructions for gathering information when reporting issues. - New accordion titled "Messages reach Telegram API but never reach the Agent" added to the Troubleshooting section - Covers both long polling and webhook delivery modes with concrete debugging commands - Includes checklist for capturing diagnostic information (`openclaw --version`, channel status, API state) - Documentation-only change with no behavioral modifications to the Telegram integration - Follows project documentation conventions: proper code block formatting, backtick-wrapped commands, generic placeholders <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with no risk - Documentation-only change that adds helpful troubleshooting content. No code changes, no runtime behavior modifications, no security implications. The new accordion follows existing documentation patterns and provides clear, actionable guidance for a known issue scenario. - No files require special attention _{Last reviewed commit: 5f68bda} <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->