| name | telegram-channel |
| description | Use the OpenClaw Telegram channel safely for polling or webhook setup, group routing, mention gating, and runtime diagnosis. |
| user-invocable | false |
Telegram Channel
Use this skill when the user asks an agent to configure, diagnose, or operate the bundled Telegram plugin.
Operating rules
- Keep bot tokens in config, env, or secret files. Do not print tokens.
- Default to long polling unless the user explicitly wants webhook mode.
- In groups, separate group ids from user ids: negative
-100... chat ids belong under channels.telegram.groups, while user ids belong in allowFrom or groupAllowFrom.
- Keep
requireMention explicit for group behavior. Plain group messages are expected to stay quiet when mention gating is enabled.
Normal proof path
- Inspect current status with
openclaw channels status telegram.
- For webhook mode, verify
getWebhookInfo, the configured path, and the webhook secret header.
- Verify bot credentials with
openclaw channels status --channel telegram --probe --json
or Telegram getMe. Report the bot identity only after redacting token
material.
- For a live roundtrip, require a real chat id. Do not reuse a group id as a
user allowlist entry, and do not invent a chat id. If no target is present,
ask the operator to send one message to the bot and inspect the resulting
update metadata locally.
- For code changes, prefer focused tests first:
node scripts/run-vitest.mjs run --config test/vitest/vitest.extension-telegram.config.ts extensions/telegram/src/bot-message-context.require-mention.test.ts extensions/telegram/src/webhook-status.test.ts
- For startup or polling behavior, add the smallest matching file under
extensions/telegram/src.
Target and roundtrip handling
- Treat Telegram chat ids and user ids as private routing identifiers in shared
logs. Report presence, shape, and success state unless the user explicitly
needs the raw id.
- Direct messages use the user chat id. Supergroups usually use negative
-100... chat ids under group config.
- In groups,
requireMention controls whether plain messages are ignored. A
quiet plain message can be the expected secure behavior.
- A complete live proof is credential probe plus one inbound update plus one
outbound send or reply to the same chat id.
Common tasks
- Mention gating and group text: inspect
extensions/telegram/src/bot-message-context.body.ts and extensions/telegram/src/group-policy.ts.
- Webhook ingress: inspect
extensions/telegram/src/webhook.ts and extensions/telegram/src/monitor.ts.
- Polling conflicts: inspect
extensions/telegram/src/polling-session.ts, extensions/telegram/src/polling-lease.ts, and extensions/telegram/src/polling-liveness.ts.
- Delivery and reply threading: inspect
extensions/telegram/src/bot/delivery.ts and extensions/telegram/src/bot/reply-threading.ts.
Troubleshooting
- Bot is silent in a group: check privacy mode, bot admin status, group allowlist, sender allowlist, and
requireMention.
- Webhook is healthy but no messages arrive: confirm Telegram is delivering updates and that
pending_update_count is not the only signal being checked.
getUpdates reports 409: another poller or gateway owns the same token.- Startup reports 401: fix the token first; do not treat auth errors as harmless webhook cleanup failures.
- Live proof is blocked: confirm a real chat id or inbound update exists before
treating the channel as unverified.
