Telegram message behavior

• channels.telegram.streaming is off | partial | block | progress (default: progress); set mode: "partial" to stream answer text into the preview instead of a status draft
• short initial answer previews are debounced, then materialized after a bounded delay if the run is still active
• progress keeps one editable status draft, 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. By default the draft is quiet: status headline, commentary, plan milestones, and approval requests. Intermediate tool failures and nonzero command exits are hidden; terminal task errors still use normal error delivery. streaming.progress.toolProgress: true adds the rolling tool log, including tool failures.
• streaming.preview.toolProgress controls whether tool/progress updates reuse the same edited preview message in partial and block modes (default: true when preview streaming is active)
• streaming.preview.commandText controls command/exec detail inside those lines: status (default, tool label only) or raw (explicit command text)
• completed assistant preambles update the status headline by default; a new preamble keeps the previous readable status until it finishes
• streaming.progress.commentary (default: false) shows those preambles as interleaved commentary rows instead of a headline; commentary remains visible beside plan steps
• successful background-process polls and internal waits stay out of the progress log; failures still follow the selected tool-progress policy, and /verbose retains diagnostic summaries
• 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

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

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

• channels.telegram.historyLimit or messages.groupChat.historyLimit caps the automatic window (default 50). 0 disables automatic history injection, not recording or explicit reads.
• Automatic context examines a bounded recent slice before applying topic and sender permissions. A busy group can supply fewer than the configured number of messages when other topics or excluded senders dominate that slice. The agent can page farther back with explicit history reads.
• History reads stay within the authorized account, chat, and topic. They use Telegram message IDs for references and paging; omitting a topic must not expand a topic-scoped read to the whole group.
• Agent reads default to 50 messages per page, up to 100. Use before with the returned oldestMessageId to read older messages, after to read newer messages, or messageId for an exact reference. These reads require the agent’s authenticated current group/topic; they do not fetch Telegram server history.
• /new and /reset reset automatic session context, not the retained conversation. Explicit history reads can retrieve permitted earlier discussion.
• The existing SQLite plugin-state table owns retained group messages. Successfully persisted records survive Gateway restarts and are not evicted by message count. Direct-message cache behavior remains bounded.
• On first use, existing group-cache records move atomically into retained storage. Legacy records without history-admission provenance, including embedded reply ancestors, remain available as explicit reply context within the existing depth and visibility limits; they are not treated as a verified conversation archive.
• History contains only messages OpenClaw received and was permitted to record. It cannot recover messages evicted before this feature, messages Telegram did not deliver, or messages from before the bot joined. Media references do not guarantee that attachment bytes remain available indefinitely.

• channels.telegram.textChunkLimit default 4000; streaming.chunkMode="newline" prefers paragraph boundaries (blank lines) before length splitting.
• channels.telegram.mediaMaxMb (default 100) caps inbound and outbound media size.
• When an inbound attachment cannot be downloaded and the message proceeds to the agent, its body includes a [media unavailable: ...] notice. Oversize notices include the effective size limit; partial albums include the failed and total attachment counts. This also applies to admitted channel posts, even when their separate chat warning is suppressed.
• automatic group context uses channels.telegram.historyLimit or messages.groupChat.historyLimit (default 50); 0 disables the automatic window, not retained history.
• 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.

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