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

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

• channels.telegram.streamMode is not "off" (default: "partial")

• off: no live preview
• partial: frequent preview updates from partial text
• block: chunked preview updates using channels.telegram.draftChunk

• minChars: 200
• maxChars: 800
• breakPreference: "paragraph"

• /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 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 approve approves latest pending request

{
  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)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.editMessage
• 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

• MessageThreadId
• IsForum

• private chats with message_thread_id keep DM routing but use thread-aware session keys/reply targets.

​

Audio messages

• default: audio file behavior
• tag [[audio_as_voice]] in agent reply to force voice-note send

{
  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).
• 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,
    },
  },
}

• set channels.telegram.webhookUrl
• set channels.telegram.webhookSecret (required when webhook URL is set)
• optional channels.telegram.webhookPath (default /telegram-webhook)
• optional channels.telegram.webhookHost (default 127.0.0.1)

• channels.telegram.textChunkLimit default is 4000.
• channels.telegram.chunkMode="newline" prefers paragraph boundaries (blank lines) before length splitting.
• channels.telegram.mediaMaxMb (default 5) caps inbound Telegram media download/processing size.
• channels.telegram.timeoutSeconds overrides Telegram API client timeout (if unset, grammY default applies).
• group context history uses channels.telegram.historyLimit or messages.groupChat.historyLimit (default 50); 0 disables.
• DM history controls:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• outbound Telegram API retries are configurable via channels.telegram.retry.

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

• 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 usually indicates DNS/HTTPS reachability issues to api.telegram.org

• 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.
• Validate DNS answers:

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