​

Telegram (Bot API)

​

Quick setup

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "<bot-token-from-botfather>",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

openclaw gateway run
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

​

Telegram side settings

​

Access control and activation

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

{
  channels: {
    telegram: {
      groups: {
        "<telegram-group-id>": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

​

Runtime behavior

• Telegram is owned by the gateway process.
• Routing is deterministic: Telegram inbound replies back to Telegram (the model does not pick channels).
• Inbound messages normalize into the shared channel envelope with reply metadata and media placeholders.
• Group sessions are isolated by group ID. Forum topics append :topic:<threadId> to keep topics isolated.
• DM messages can carry message_thread_id; OpenClaw routes them with thread-aware session keys and preserves thread ID for replies.
• Long polling uses grammY runner with per-chat/per-thread sequencing. Overall runner sink concurrency uses agents.defaults.maxConcurrent.
• Telegram Bot API has no read-receipt support (sendReadReceipts does not apply).

​

If Telegram replies stop or repeat network errors

Telegram network error: Network request for 'getUpdates' failed!; retrying in 2.21s.

wednesdayai doctor
wednesdayai doctor --fix

• below 30 seconds: remove the override so the 30 second default applies;
• above 50 seconds: rewrite the override to 50 seconds.

​

Multi-bot fleet

{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      accounts: {
        alerts: {
          enabled: true,
          botToken: "<alerts-bot-token>",
          groups: {
            "<telegram-group-id>": { requireMention: true },
          },
        },
        support: {
          enabled: true,
          tokenFile: "/run/secrets/wednesdayai/telegram-support-token",
          webhookUrl: "https://gateway.example.invalid/telegram/support",
          webhookSecret: "<support-webhook-secret>",
          webhookPath: "/telegram/support",
        },
      },
    },
  },
}

​

Polling, webhook, and ownership

• polling: default long-polling mode using getUpdates.
• webhook: enabled when the account has webhookUrl.
• disabled: account is configured but not started.

• another local account in the same gateway resolved the same bot token;
• another gateway process is polling the same bot;
• Telegram still has a webhook owner while this account is trying to poll;
• the webhook endpoint is reachable but rejecting or timing out.

​

Channels UI health

• mode, state, reason, and previousState show the account lifecycle.
• configured, running, gatewayInstanceId, owner, and ownerStartedAt show ownership.
• retryAt marks recoverable backoff or flood-wait recovery windows.
• poll.lastPollAt, poll.lastConflictAt, and poll.lastOffset describe long-polling health.
• webhook.configured, webhook.urlHash, webhook.path, webhook.secretPresent, webhook.pendingUpdateCount, and webhook request counters describe webhook health without showing the raw URL secret or request body.
• delivery.queueDepth, delivery.lastDeliveryStatus, delivery.retryAfterMs, delivery.nextRetryAt, and delivery.lastDestinationHash describe outbound send health.
• lastApiRequests, lastUpdates, and lastDeliveries retain recent events with hashed Telegram identifiers only.

​

OTel and Langfuse export

• openclaw.channel = "telegram"
• telegram.account.hash
• telegram.bot.hash
• telegram.chat.hash
• telegram.user.hash
• telegram.thread.hash
• telegram.update.id
• telegram.mode
• telegram.account.state
• telegram.api.method
• telegram.retry_after_ms
• langfuse.session.id
• langfuse.user.id

• Bot tokens, raw chat IDs, raw user IDs, raw thread IDs, raw message IDs, webhook secrets, raw webhook URLs, and message content are not exported.
• Telegram tool input/output capture is replaced with a fixed redaction marker on Telegram-correlated spans.
• Telegram-shaped OTLP log records redact the body and drop aggregate argument fields when they contain Telegram IDs or message content.

​

Feature reference

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

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

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

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

{
  action: "send",
  channel: "telegram",
  to: "<telegram-chat-id>",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

{
  action: "send",
  channel: "telegram",
  to: "<telegram-chat-id>",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

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

{
  action: "sticker",
  channel: "telegram",
  to: "<telegram-chat-id>",
  fileId: "CAACAgIAAxkBAAI...",
}

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

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

openclaw message send --channel telegram --target <telegram-chat-id> --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

​

Troubleshooting

channels:
  telegram:
    proxy: socks5://user:pass@proxy-host:1080

channels:
  telegram:
    network:
      autoSelectFamily: false

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

​

Telegram config reference pointers

• channels.telegram.enabled: enable/disable channel startup.
• channels.telegram.botToken: bot token (BotFather).
• channels.telegram.tokenFile: read token from file path.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• channels.telegram.allowFrom: DM allowlist (numeric Telegram user IDs). allowlist requires at least one sender ID. open requires "*". openclaw doctor --fix can resolve legacy @username entries to IDs and can recover allowlist entries from pairing-store files in allowlist migration flows.
• channels.telegram.defaultTo: default Telegram target used by CLI --deliver when no explicit --reply-to is provided.
• channels.telegram.groupPolicy: open | allowlist | disabled (default: allowlist).
• channels.telegram.groupAllowFrom: group sender allowlist (numeric Telegram user IDs). openclaw doctor --fix can resolve legacy @username entries to IDs. Non-numeric entries are ignored at auth time. Group auth does not use DM pairing-store fallback (2026.2.25+).
• Multi-account precedence:
  • channels.telegram.accounts.default.allowFrom and channels.telegram.accounts.default.groupAllowFrom apply only to the default account.
  • Named accounts inherit channels.telegram.allowFrom and channels.telegram.groupAllowFrom when account-level values are unset.
  • Named accounts do not inherit channels.telegram.accounts.default.allowFrom / groupAllowFrom.
• channels.telegram.groups: per-group defaults + allowlist (use "*" for global defaults).
  • channels.telegram.groups.<id>.groupPolicy: per-group override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: mention gating default.
  • channels.telegram.groups.<id>.skills: skill filter (omit = all skills, empty = none).
  • channels.telegram.groups.<id>.allowFrom: per-group sender allowlist override.
  • channels.telegram.groups.<id>.systemPrompt: extra system prompt for the group.
  • channels.telegram.groups.<id>.enabled: disable the group when false.
  • channels.telegram.groups.<id>.disableAudioPreflight: skip automatic voice-note transcription for mention detection in this group.
  • channels.telegram.groups.<id>.topics.<threadId>.*: per-topic overrides (same fields as group).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: per-topic override for groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: per-topic mention gating override.
  • channels.telegram.groups.<id>.topics.<threadId>.disableAudioPreflight: per-topic voice-note transcription skip.
• channels.telegram.direct: per-DM configuration keyed by chat ID.
  • channels.telegram.direct.<chatId>.dmPolicy: per-DM override (open | disabled | allowlist).
  • channels.telegram.direct.<chatId>.tools: per-DM tool policy overrides.
  • channels.telegram.direct.<chatId>.skills: per-DM skill filter.
  • channels.telegram.direct.<chatId>.allowFrom: per-DM sender allowlist override.
  • channels.telegram.direct.<chatId>.systemPrompt: extra system prompt for the DM.
  • channels.telegram.direct.<chatId>.enabled: disable the DM when false.
  • channels.telegram.direct.<chatId>.requireTopic: require messages to be from a topic when topics are enabled.
  • channels.telegram.direct.<chatId>.topics.<threadId>.*: per-DM topic overrides (same fields as group topics).
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (default: allowlist).
• channels.telegram.accounts.<account>.capabilities.inlineButtons: per-account override.
• channels.telegram.commands.nativeSkills: enable/disable Telegram native skills commands.
• channels.telegram.replyToMode: off | first | all (default: off).
• channels.telegram.textChunkLimit: outbound chunk size (chars).
• channels.telegram.chunkMode: length (default) or newline to pack paragraph blocks up to textChunkLimit per message; oversized blocks fall back to length splitting.
• channels.telegram.chunkNewlinePacking: packing mode for newline chunking (default: true). Set to false to restore one message per paragraph.
• channels.telegram.linkPreview: toggle link previews for outbound messages (default: true).
• channels.telegram.streaming: off | partial | block | progress (live stream preview; default: partial; progress maps to partial; block is legacy preview mode compatibility). In DMs, partial uses native sendMessageDraft when available. Per-account configs inherit this value — set it once at the channel level to apply to all bots. To override for a single account, set channels.telegram.accounts.<id>.streaming.
• channels.telegram.mediaMaxMb: inbound Telegram media download/processing cap (MB).
• channels.telegram.retry: retry policy for Telegram send helpers (CLI/tools/actions) on recoverable outbound API errors (attempts, minDelayMs, maxDelayMs, jitter).
• channels.telegram.timeoutSeconds: Telegram long-poll (getUpdates) window in seconds. Safe range is 30-50; unset applies 30. The bot’s HTTP client abort timeout is derived as this value plus 10 seconds. Per-account values under channels.telegram.accounts.<id>.timeoutSeconds take precedence.
• channels.telegram.network.autoSelectFamily: override Node autoSelectFamily (true=enable, false=disable). Defaults to enabled on Node 22+, with WSL2 defaulting to disabled.
• channels.telegram.network.dnsResultOrder: override DNS result order (ipv4first or verbatim). Defaults to ipv4first on Node 22+.
• channels.telegram.proxy: proxy URL for Bot API calls (SOCKS/HTTP).
• channels.telegram.webhookUrl: enable webhook mode (requires channels.telegram.webhookSecret).
• channels.telegram.webhookSecret: webhook secret (required when webhookUrl is set).
• channels.telegram.webhookPath: local webhook path (default /telegram-webhook).
• channels.telegram.webhookHost: local webhook bind host (default 127.0.0.1).
• channels.telegram.webhookPort: local webhook bind port (default 8787).
• channels.telegram.actions.reactions: gate Telegram tool reactions.
• channels.telegram.actions.sendMessage: gate Telegram tool message sends.
• channels.telegram.actions.deleteMessage: gate Telegram tool message deletes.
• channels.telegram.actions.editMessage: gate Telegram tool message edits (default: true).
• channels.telegram.actions.sticker: gate Telegram sticker actions — send and search (default: false).
• channels.telegram.actions.createForumTopic: gate Telegram forum topic creation (default: true).
• channels.telegram.reactionNotifications: off | own | all — control which reactions trigger system events (default: own when not set).
• channels.telegram.reactionLevel: off | ack | minimal | extensive — control agent’s reaction capability (default: minimal when not set).
• channels.telegram.configWrites: allow channel-initiated config writes from Telegram events/commands (default: true).
• channels.telegram.ackReaction: per-channel ack reaction emoji override (unicode emoji, e.g. ”👀”). Use "" to disable.
• channels.telegram.responsePrefix: per-channel outbound response prefix override. Use "auto" to derive [{identity.name}] from the routed agent.
• channels.telegram.heartbeat: per-channel heartbeat visibility settings.
• channels.telegram.markdown: markdown formatting overrides (tables).
• channels.telegram.defaultAccount: default account id when multiple accounts are configured.
• channels.telegram.groups.<id>.tools: per-group tool policy overrides.
• channels.telegram.groups.<id>.toolsBySender: per-group tool policy by sender.
• Configuration reference - Telegram

• startup/auth: enabled, botToken, tokenFile, accounts.*
• access control: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, direct
• delivery target: defaultTo
• command/menu: commands.native, commands.nativeSkills, customCommands
• threading/replies: replyToMode
• streaming: streaming (preview), blockStreaming
• formatting/delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
• media/network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• webhook: webhookUrl, webhookSecret, webhookPath, webhookHost
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• reactions: reactionNotifications, reactionLevel
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

​

Related

• Pairing
• Channel routing
• Multi-agent routing
• Troubleshooting