Telegram

• disable privacy mode via /setprivacy, or
• make the bot a group admin.

• /setjoingroups — allow/deny group adds
• /setprivacy — group visibility behavior

• channels.telegram.streaming is off | partial | block | progress (default: partial)
• short initial answer previews are debounced, then materialized after a bounded delay if the run is still active
• progress keeps one editable status draft for tool progress, shows the stable status label when answer activity arrives before tool progress, clears it at completion, and sends the final answer as a normal message
• streaming.preview.toolProgress controls whether tool/progress updates reuse the same edited preview message (default: true when preview streaming is active)
• streaming.preview.commandText controls command/exec detail inside those lines: raw (default) or status (tool label only)
• streaming.progress.commentary (default: false) opts into assistant commentary/preamble text in the temporary progress draft
• legacy channels.telegram.streamMode, boolean streaming values, and retired native draft preview keys are detected; run openclaw doctor --fix to migrate them

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": { "toolProgress": false }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": { "commandText": "status" }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

• setMyCommands failed with BOT_COMMANDS_TOO_MUCH after a trim retry means the menu still overflows; reduce plugin/skill/custom commands or disable channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands, or setMyCommands failing with 404: Not Found while direct Bot API curl commands work usually means channels.telegram.apiRoot was set to the full /bot<TOKEN> endpoint. apiRoot must be the Bot API root only; openclaw doctor --fix removes an accidental trailing /bot<TOKEN>.
• getMe returned 401 means Telegram rejected the configured bot token. Update botToken, tokenFile, or TELEGRAM_BOT_TOKEN (default account) with the current BotFather token; OpenClaw stops before polling so this is not reported as a webhook cleanup failure.
• setMyCommands failed with network/fetch errors usually means outbound DNS/HTTPS to api.telegram.org is blocked.

​

Device pairing commands (device-pair plugin)

1. /pair generates a setup code
2. paste the code in the iOS app
3. /pair pending lists pending requests (including role/scopes)
4. approve: /pair approve <requestId>, /pair approve (only pending request), or /pair approve latest

• sendMessage (to, content, optional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content or caption, optional presentation inline buttons; button-only edits update reply markup)
• createForumTopic (chatId, name, optional iconColor, iconCustomEmojiId)

• [[reply_to_current]] — replies to the triggering message
• [[reply_to:<id>]] — replies to a specific message ID

​

Audio messages

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

​

Video messages

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

​

Stickers

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

• channels.telegram.reactionNotifications: off | own | all (default: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (default: minimal)

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• agent identity emoji fallback (agents.list[].identity.emoji, else ”👀”)

• channels.telegram.textChunkLimit default 4000; chunkMode="newline" prefers paragraph boundaries (blank lines) before length splitting.
• channels.telegram.mediaMaxMb (default 100) caps inbound and outbound media size.
• channels.telegram.mediaGroupFlushMs (default 500, range 10-60000) controls how long albums/media groups are buffered before OpenClaw dispatches them as one inbound message. Increase it if album parts arrive late; decrease it to reduce album reply latency.
• channels.telegram.timeoutSeconds overrides the API client timeout (grammY default applies if unset). Bot clients clamp configured values below the 60-second outbound text/typing request guard so grammY does not abort visible reply delivery before OpenClaw’s transport guard and fallback can run. Long polling still uses a 45-second getUpdates request guard so idle polls are not abandoned indefinitely.
• channels.telegram.pollingStallThresholdMs defaults to 120000; tune between 30000 and 600000 only for false-positive polling-stall restarts.
• group context history uses channels.telegram.historyLimit or messages.groupChat.historyLimit (default 50); 0 disables.
• reply/quote/forward supplemental context normalizes into one selected conversation context window when the gateway has observed the parent messages; the observed-message cache lives in OpenClaw SQLite plugin state, and openclaw doctor --fix imports legacy sidecars. Telegram only includes one shallow reply_to_message per update, so chains older than the cache are limited to that payload.
• Telegram allowlists primarily gate who can trigger the agent, not a full supplemental-context redaction boundary.
• DM history: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry applies to Telegram send helpers (CLI/tools/actions) for recoverable outbound API errors. Inbound final-reply delivery uses a bounded safe-send retry for pre-connect failures, but does not retry ambiguous post-send network envelopes that could duplicate visible messages.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• channels.telegram.execApprovals.enabled ("auto" enables when at least one approver is resolvable)
• channels.telegram.execApprovals.approvers (falls back to numeric owner IDs from commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (default) | channel | both
• agentFilter, sessionFilter

• If requireMention=false, Telegram privacy mode must allow full visibility: BotFather /setprivacy -> Disable, then remove + re-add the bot to the group.
• openclaw channels status warns when config expects unmentioned group messages.
• openclaw channels status --probe checks explicit numeric group IDs; wildcard "*" cannot be membership-probed.
• Quick session test: /activation always.

• When channels.telegram.groups exists, the group must be listed (or include "*").
• Verify bot membership in the group.
• Review openclaw logs --follow for skip reasons.

• Authorize your sender identity (pairing and/or numeric allowFrom); command authorization still applies even when group policy is open.
• setMyCommands failed with BOT_COMMANDS_TOO_MUCH means the native menu has too many entries; reduce plugin/skill/custom commands or disable native menus.
• deleteMyCommands / setMyCommands startup calls and sendChatAction typing calls are bounded and retry once through Telegram’s transport fallback on request timeout. Persistent network/fetch errors usually mean DNS/HTTPS to api.telegram.org is unreachable.

• getMe returned 401 is a Telegram auth failure for the configured bot token. Re-copy or regenerate the token in BotFather, then update channels.telegram.botToken, tokenFile, accounts.<id>.botToken, or TELEGRAM_BOT_TOKEN (default account).
• deleteWebhook 401 Unauthorized during startup is also an auth failure; treating it as “no webhook exists” would only defer the same bad-token failure to a later API call.

• Node 22+ with a custom fetch/proxy can trigger immediate abort behavior if AbortSignal types mismatch.
• Some hosts resolve api.telegram.org to IPv6 first; broken IPv6 egress causes intermittent API failures.
• Logs with TypeError: fetch failed or Network request for 'getUpdates' failed! are retried as recoverable network errors.
• During polling startup, OpenClaw reuses the successful startup getMe probe for grammY so the runner does not need a second getMe before the first getUpdates.
• If deleteWebhook fails with a transient network error during polling startup, OpenClaw continues into long polling instead of making another pre-poll control-plane call. A still-active webhook then surfaces as a getUpdates conflict; OpenClaw rebuilds the transport and retries webhook cleanup.
• If Telegram sockets recycle on a short fixed cadence, check for a low channels.telegram.timeoutSeconds — bot clients clamp configured values below the outbound and getUpdates request guards, but older releases could abort every poll or reply when this was set below those guards.
• Polling stall detected in logs means OpenClaw restarts polling and rebuilds the transport after 120 seconds without completed long-poll liveness by default.
• openclaw channels status --probe and openclaw doctor warn when a running polling account has not completed getUpdates after startup grace, a running webhook account has not completed setWebhook after startup grace, or the last successful polling transport activity is stale.
• Raise channels.telegram.pollingStallThresholdMs only when long-running getUpdates calls are healthy but your host still reports false polling-stall restarts. Persistent stalls usually point to proxy, DNS, IPv6, or TLS egress issues to api.telegram.org.
• Telegram honors process proxy env for Bot API transport: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and lowercase variants. NO_PROXY / no_proxy can still bypass api.telegram.org.
• If OPENCLAW_PROXY_URL is set for a service environment and no standard proxy env is present, Telegram uses that URL for Bot API transport too.
• On VPS hosts with unstable direct egress/TLS, route Telegram API calls through a proxy:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ defaults to autoSelectFamily=true (except WSL2). Telegram DNS result order honors OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, then channels.telegram.network.dnsResultOrder, then the process default (for example NODE_OPTIONS=--dns-result-order=ipv4first), falling back to ipv4first on Node 22+ if none applies.
• On WSL2, or when IPv4-only behavior works better, force family selection:

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544 benchmark-range answers (198.18.0.0/15) are already allowed for Telegram media downloads by default. If a trusted fake-IP or transparent proxy rewrites api.telegram.org to some other private/internal/special-use address during media downloads, opt in to the Telegram-only bypass:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• The same opt-in is available per account at channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• If your proxy resolves Telegram media hosts into 198.18.x.x, leave the dangerous flag off first — that range is already allowed by default.

• Temporary environment overrides: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Validate DNS answers:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA