Telegram

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

• /setjoingroups to allow/deny group adds
• /setprivacy for group visibility behavior

• direct chats: preview message + editMessageText
• groups/topics: preview message + editMessageText

• channels.telegram.streaming is off | partial | block | progress (default: partial)
• progress maps to partial on Telegram (compat with cross-channel naming)
• streaming.preview.toolProgress controls whether tool/progress updates reuse the same edited preview message (default: true when preview streaming is active)
• legacy channels.telegram.streamMode and boolean streaming values are detected; run openclaw doctor --fix to migrate them to channels.telegram.streaming.mode

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

• short DM/group/topic previews: OpenClaw keeps the same preview message and performs a final edit in place
• previews older than about one minute: OpenClaw sends the completed reply as a fresh final message and then cleans up the preview, so Telegram’s visible timestamp reflects completion time instead of the preview creation time

• /reasoning stream sends reasoning to the live preview while generating
• final answer is sent without reasoning text

• Markdown-ish text is rendered to Telegram-safe HTML.
• Raw model HTML is escaped to reduce Telegram parse failures.
• If Telegram rejects parsed HTML, OpenClaw retries as plain text.

• commands.native: "auto" enables native commands for Telegram

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

• names are normalized (strip leading /, lowercase)
• valid pattern: a-z, 0-9, _, length 1..32
• custom commands cannot override native commands
• conflicts/duplicates are skipped and logged

• custom commands are menu entries only; they do not auto-implement behavior
• plugin/skill commands can still work when typed even if not shown in Telegram menu

• setMyCommands failed with BOT_COMMANDS_TOO_MUCH means the Telegram menu still overflowed after trimming; 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 can mean channels.telegram.apiRoot was set to the full /bot<TOKEN> endpoint. apiRoot must be only the Bot API root, and 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 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 setup code
2. paste code in iOS app
3. /pair pending lists pending requests (including role/scopes)
4. approve the request:
   • /pair approve <requestId> for explicit approval
   • /pair approve when there is only one pending request
   • /pair approve latest for most recent

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

• off
• dm
• group
• all
• allowlist (default)

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

• sendMessage (to, content, optional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, optional iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (default: disabled)

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

• off (default)
• first
• all

• topic session keys append :topic:<threadId>
• replies and typing target the topic thread
• topic config path: channels.telegram.groups.<chatId>.topics.<threadId>

• message sends omit message_thread_id (Telegram rejects sendMessage(...thread_id=1))
• typing actions still include message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

Audio messages

• default: audio file behavior
• tag [[audio_as_voice]] in agent reply to force voice-note send
• inbound voice-note transcripts are framed as machine-generated, untrusted text in the agent context; mention detection still uses the raw transcript so mention-gated voice messages continue to work.

{
  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

• static WEBP: downloaded and processed (placeholder <media:sticker>)
• animated TGS: skipped
• video WEBM: skipped

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

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

• own means user reactions to bot-sent messages only (best-effort via sent-message cache).
• Reaction events still respect Telegram access controls (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); unauthorized senders are dropped.
• Telegram does not provide thread IDs in reaction updates.
  • non-forum groups route to group chat session
  • forum groups route to the group general-topic session (:topic:1), not the exact originating topic

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

• Telegram expects unicode emoji (for example ”👀”).
• Use "" to disable the reaction for a channel or account.

• group migration events (migrate_to_chat_id) to update channels.telegram.groups
• /config set and /config unset (requires command enablement)

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

• channels.telegram.textChunkLimit default is 4000.
• channels.telegram.chunkMode="newline" prefers paragraph boundaries (blank lines) before length splitting.
• channels.telegram.mediaMaxMb (default 100) caps inbound and outbound Telegram media size.
• channels.telegram.timeoutSeconds overrides Telegram API client timeout (if unset, grammY default applies).
• 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 is currently passed as received.
• Telegram allowlists primarily gate who can trigger the agent, not a full supplemental-context redaction boundary.
• DM history controls:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry config applies to Telegram send helpers (CLI/tools/actions) for recoverable outbound API errors.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id for forum topics (or use a :topic: target)

• --presentation with buttons blocks for inline keyboards when channels.telegram.capabilities.inlineButtons allows it
• --pin or --delivery '{"pin":true}' to request pinned delivery when the bot can pin in that chat
• --force-document to send outbound images and GIFs as documents instead of compressed photo or animated-media uploads

• channels.telegram.actions.sendMessage=false disables outbound Telegram messages, including polls
• channels.telegram.actions.poll=false disables Telegram poll creation while leaving regular sends enabled

• 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 bot to group
• openclaw channels status warns when config expects unmentioned group messages.
• openclaw channels status --probe can check explicit numeric group IDs; wildcard "*" cannot be membership-probed.
• quick session test: /activation always.

• when channels.telegram.groups exists, group must be listed (or include "*")
• verify bot membership in group
• review logs: 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
• setMyCommands failed with network/fetch errors usually indicates DNS/HTTPS reachability issues to api.telegram.org

• getMe returned 401 is a Telegram authentication failure for the configured bot token.
• Re-copy or regenerate the bot token in BotFather, then update channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken, or TELEGRAM_BOT_TOKEN for the 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 later API calls.

• Node 22+ + custom fetch/proxy can trigger immediate abort behavior if AbortSignal types mismatch.
• Some hosts resolve api.telegram.org to IPv6 first; broken IPv6 egress can cause intermittent Telegram API failures.
• If logs include TypeError: fetch failed or Network request for 'getUpdates' failed!, OpenClaw now retries these as recoverable network errors.
• If logs include Polling stall detected, OpenClaw restarts polling and rebuilds the Telegram transport after 120 seconds without completed long-poll liveness by default.
• Increase 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 between the host and api.telegram.org.
• On VPS hosts with unstable direct egress/TLS, route Telegram API calls through channels.telegram.proxy:

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

• Node 22+ defaults to autoSelectFamily=true (except WSL2) and dnsResultOrder=ipv4first.
• If your host is WSL2 or explicitly works better with IPv4-only behavior, 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, you can 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. Telegram media already allows the RFC 2544 benchmark range by default.

• Environment overrides (temporary):
  • 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