• вимкніть режим приватності через /setprivacy, або
• зробіть бота адміністратором групи.

• /setjoingroups, щоб дозволити/заборонити додавання до груп
• /setprivacy для поведінки видимості в групах

• прямі чати: повідомлення попереднього перегляду + editMessageText
• групи/теми: повідомлення попереднього перегляду + editMessageText

• channels.telegram.streaming має значення off | partial | block | progress (типово: partial)
• progress у Telegram відображається як partial (сумісність із міжканальним найменуванням)
• застарілі значення channels.telegram.streamMode і boolean-значення streaming автоматично зіставляються

• DM: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)
• група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду і виконує фінальне редагування на місці (без другого повідомлення)

• /reasoning stream надсилає reasoning у live preview під час генерації
• фінальна відповідь надсилається без тексту reasoning

• Текст у стилі Markdown рендериться у безпечний для Telegram HTML.
• Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу в Telegram.
• Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.

• commands.native: "auto" вмикає нативні команди для Telegram

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

• назви нормалізуються (знімається початковий /, переводяться в нижній регістр)
• допустимий шаблон: a-z, 0-9, _, довжина 1..32
• кастомні команди не можуть перевизначати нативні команди
• конфлікти/дублікати пропускаються та логуються

• кастомні команди — це лише записи меню; вони не реалізують поведінку автоматично
• команди plugin/Skills можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram

• setMyCommands failed з BOT_COMMANDS_TOO_MUCH означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд plugin/Skills/кастомних або вимкніть channels.telegram.commands.native.
• setMyCommands failed з помилками network/fetch зазвичай означає, що заблоковано вихідний DNS/HTTPS до api.telegram.org.

​

Команди pairing пристрою (device-pair plugin)

1. /pair генерує код налаштування
2. вставте код у застосунок iOS
3. /pair pending показує запити, що очікують підтвердження (включно з role/scopes)
4. схваліть запит:
   • /pair approve <requestId> для явного схвалення
   • /pair approve, коли є лише один запит, що очікує
   • /pair approve latest для найновішого

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

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

• off
• dm
• group
• all
• allowlist (типово)

{
  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, необов’язково mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, необов’язково iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (типово: вимкнено)

• [[reply_to_current]] відповідає на повідомлення, яке викликало дію
• [[reply_to:<id>]] відповідає на конкретний ID повідомлення Telegram

• off (типово)
• first
• all

• до ключів сесії теми додається :topic:<threadId>
• відповіді й індикатор набору спрямовуються в thread теми
• шлях конфігурації теми: channels.telegram.groups.<chatId>.topics.<threadId>

• надсилання повідомлень пропускає message_thread_id (Telegram відхиляє sendMessage(...thread_id=1))
• дії набору тексту все одно включають message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Загальна тема → агент main
            "3": { agentId: "zu" },        // Тема dev → агент zu
            "5": { agentId: "coder" }      // Code review → агент coder
          }
        }
      }
    }
  }
}

• bindings[] з type: "acp" і match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto може прив’язати поточну тему Telegram до нової сесії ACP.
• Подальші повідомлення в темі маршрутизуються безпосередньо до прив’язаної сесії ACP (без потреби в /acp steer).
• Після успішної прив’язки OpenClaw закріплює в темі повідомлення-підтвердження запуску.
• Потрібно channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• приватні чати з message_thread_id зберігають маршрутизацію DM, але використовують session key і цілі відповіді з урахуванням thread.

​

Аудіоповідомлення

• типово: поведінка аудіофайлу
• тег [[audio_as_voice]] у відповіді агента примусово надсилає як voice note

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

​

Відеоповідомлення

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

​

Стикери

• статичний WEBP: завантажується й обробляється (placeholder <media:sticker>)
• анімований TGS: пропускається
• відео WEBM: пропускається

• 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 (типово: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (типово: minimal)

• own означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
• Події реакцій усе одно враховують механізми доступу Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); неавторизовані відправники відкидаються.
• Telegram не надає ID thread в оновленнях реакцій.
  • у нефорумних групах маршрут іде до сесії групового чату
  • у форумних групах маршрут іде до сесії загальної теми групи (:topic:1), а не до точного початкового thread

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• резервне значення з emoji identity агента (agents.list[].identity.emoji, інакше "👀")

• Telegram очікує emoji Unicode (наприклад, "👀").
• Використовуйте "", щоб вимкнути реакцію для каналу або облікового запису.

• події міграції груп (migrate_to_chat_id) для оновлення channels.telegram.groups
• /config set і /config unset (потрібне ввімкнення команд)

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

• задайте channels.telegram.webhookUrl
• задайте channels.telegram.webhookSecret (обов’язково, коли задано webhook URL)
• необов’язково channels.telegram.webhookPath (типово /telegram-webhook)
• необов’язково channels.telegram.webhookHost (типово 127.0.0.1)
• необов’язково channels.telegram.webhookPort (типово 8787)

• Типове значення channels.telegram.textChunkLimit — 4000.
• channels.telegram.chunkMode="newline" надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
• channels.telegram.mediaMaxMb (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
• channels.telegram.timeoutSeconds перевизначає timeout клієнта Telegram API (якщо не задано, використовується типове значення grammY).
• історія групового контексту використовує channels.telegram.historyLimit або messages.groupChat.historyLimit (типово 50); 0 вимикає.
• додатковий контекст reply/quote/forward наразі передається як отриманий.
• Telegram allowlist передусім обмежують, хто може активувати агента, а не є повною межею редагування додаткового контексту.
• керування історією DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• конфігурація channels.telegram.retry застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.

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 для тем форуму (або використовуйте ціль :topic:)

• --buttons для вбудованих клавіатур, коли це дозволяє channels.telegram.capabilities.inlineButtons
• --force-document, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа

• channels.telegram.actions.sendMessage=false вимикає вихідні повідомлення Telegram, включно з polls
• channels.telegram.actions.poll=false вимикає створення Telegram poll, залишаючи звичайні надсилання ввімкненими

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (необов’язково; використовує резервне значення числових ID власників, визначених із allowFrom і прямого defaultTo, коли це можливо)
• channels.telegram.execApprovals.target (dm | channel | both, типово: dm)
• agentFilter, sessionFilter

• target: "dm" надсилає запити на погодження лише в DM визначеним погоджувачам
• target: "channel" надсилає запит назад у початковий чат/тему Telegram
• target: "both" надсилає в DM погоджувачів і в початковий чат/тему

• ID з префіксом plugin: завжди визначаються через погодження plugin.
• Інші ID спочатку пробують exec.approval.resolve.
• Якщо Telegram також авторизовано для погоджень plugin і gateway повідомляє, що погодження exec невідоме/прострочене, Telegram один раз повторює спробу через plugin.approval.resolve.
• Справжні відмови/помилки погодження exec не переходять мовчки до визначення погодження plugin.

• Якщо requireMention=false, режим приватності Telegram має дозволяти повну видимість.
  • BotFather: /setprivacy -> Disable
  • потім видаліть бота з групи й додайте знову
• openclaw channels status попереджає, коли конфігурація очікує повідомлення групи без згадувань.
• openclaw channels status --probe може перевіряти явні числові ID груп; wildcard "*" не можна перевірити на членство.
• швидкий тест сесії: /activation always.

• коли існує channels.telegram.groups, група має бути вказана там (або має бути "*")
• перевірте, що бот є учасником групи
• перегляньте логи: openclaw logs --follow для причин пропуску

• авторизуйте свою ідентичність відправника (pairing та/або числовий allowFrom)
• авторизація команд застосовується навіть тоді, коли групова політика має значення open
• setMyCommands failed з BOT_COMMANDS_TOO_MUCH означає, що нативне меню має забагато записів; зменште кількість команд plugin/Skills/кастомних або вимкніть нативні меню
• setMyCommands failed з помилками network/fetch зазвичай вказує на проблеми досяжності DNS/HTTPS до api.telegram.org

• Node 22+ + кастомний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
• На деяких хостах api.telegram.org спочатку визначається в IPv6; зламаний вихідний IPv6 може спричиняти періодичні збої Telegram API.
• Якщо логи містять TypeError: fetch failed або Network request for 'getUpdates' failed!, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
• На VPS-хостах з нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через channels.telegram.proxy:

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

• Node 22+ типово використовує autoSelectFamily=true (окрім WSL2) і dnsResultOrder=ipv4first.
• Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір family:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Відповіді з benchmark-діапазону RFC 2544 (198.18.0.0/15) уже типово дозволені для завантажень медіа Telegram. Якщо довірений fake-IP або transparent proxy переписує api.telegram.org на якусь іншу приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете явно ввімкнути цей обхід лише для Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Те саме явне ввімкнення доступне для окремого облікового запису за шляхом channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Якщо ваш proxy визначає медіахости Telegram у 198.18.x.x, спочатку залиште небезпечний прапорець вимкненим. Telegram media уже типово дозволяє benchmark-діапазон RFC 2544.

• Тимчасові перевизначення через змінні середовища:
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Перевірка DNS-відповідей:

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