Telegram

• nonaktifkan mode privasi melalui /setprivacy, atau
• jadikan bot sebagai admin grup.

• /setjoingroups untuk mengizinkan/menolak penambahan grup
• /setprivacy untuk perilaku visibilitas grup

• chat langsung: pesan pratinjau + editMessageText
• grup/topik: pesan pratinjau + editMessageText

• channels.telegram.streaming adalah off | partial | block | progress (default: partial)
• pratinjau jawaban awal yang pendek di-debounce, lalu diwujudkan setelah jeda terbatas jika run masih aktif
• progress mempertahankan satu draf status yang dapat diedit untuk progres tool, menampilkan label status stabil ketika aktivitas jawaban tiba sebelum progres tool, membersihkannya saat selesai, dan mengirim jawaban final sebagai pesan normal
• streaming.preview.toolProgress mengontrol apakah pembaruan tool/progres menggunakan ulang pesan pratinjau yang sama yang diedit (default: true ketika streaming pratinjau aktif)
• streaming.preview.commandText mengontrol detail perintah/eksekusi di dalam baris progres tool tersebut: raw (default, mempertahankan perilaku rilis) atau status (hanya label tool)
• streaming.progress.commentary (default: false) memilih ikut menyertakan teks komentar/preambule asisten di draf progres sementara
• legacy channels.telegram.streamMode, nilai boolean streaming, dan key pratinjau draf native yang sudah dihentikan terdeteksi; jalankan openclaw doctor --fix untuk memigrasikannya ke config streaming saat ini

{
  "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"
        }
      }
    }
  }
}

• pratinjau DM/grup/topik pendek: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempat
• final teks panjang yang dipecah menjadi beberapa pesan Telegram menggunakan ulang pratinjau yang ada sebagai chunk final pertama jika memungkinkan, lalu hanya mengirim chunk yang tersisa
• final mode progres membersihkan draf status dan menggunakan pengiriman final normal alih-alih mengedit draf menjadi jawaban
• jika edit final gagal sebelum teks selesai dikonfirmasi, OpenClaw menggunakan pengiriman final normal dan membersihkan pratinjau yang sudah stale

• /reasoning stream menggunakan jalur pratinjau penalaran channel yang didukung; di Telegram, ini melakukan stream penalaran ke pratinjau langsung saat menghasilkan
• pratinjau penalaran dihapus setelah pengiriman final; gunakan /reasoning on ketika penalaran harus tetap terlihat
• jawaban final dikirim tanpa teks penalaran

{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}

• Agent diberi tahu bahwa pesan kaya Telegram tersedia untuk bot/akun ini.
• Teks Markdown dirender melalui Markdown IR OpenClaw dan dikirim sebagai HTML kaya Telegram.
• Payload HTML kaya eksplisit mempertahankan tag Bot API 10.1 yang didukung seperti heading, tabel, detail, media kaya, dan formula.
• Caption media tetap menggunakan caption HTML Telegram karena pesan kaya tidak menggantikan caption.

• commands.native: "auto" mengaktifkan perintah native untuk Telegram

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

• nama dinormalisasi (hapus / di awal, huruf kecil)
• pola valid: a-z, 0-9, _, panjang 1..32
• perintah kustom tidak dapat menimpa perintah native
• konflik/duplikat dilewati dan dicatat

• perintah kustom hanya berupa entri menu; perintah tersebut tidak otomatis mengimplementasikan perilaku
• perintah plugin/skill tetap dapat berfungsi ketika diketik meskipun tidak ditampilkan di menu Telegram

• setMyCommands failed dengan BOT_COMMANDS_TOO_MUCH berarti menu Telegram masih meluap setelah dipangkas; kurangi perintah plugin/skill/kustom atau nonaktifkan channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands, atau setMyCommands gagal dengan 404: Not Found sementara perintah curl Bot API langsung berfungsi dapat berarti channels.telegram.apiRoot disetel ke endpoint lengkap /bot<TOKEN>. apiRoot harus hanya berupa root Bot API, dan openclaw doctor --fix menghapus akhiran /bot<TOKEN> yang tidak sengaja.
• getMe returned 401 berarti Telegram menolak token bot yang dikonfigurasi. Perbarui botToken, tokenFile, atau TELEGRAM_BOT_TOKEN dengan token BotFather saat ini; OpenClaw berhenti sebelum polling sehingga ini tidak dilaporkan sebagai kegagalan pembersihan webhook.
• setMyCommands failed dengan error jaringan/fetch biasanya berarti DNS/HTTPS keluar ke api.telegram.org diblokir.

​

Perintah pemasangan perangkat (plugin device-pair)

1. /pair menghasilkan kode setup
2. tempel kode di aplikasi iOS
3. /pair pending mencantumkan permintaan tertunda (termasuk peran/scope)
4. setujui permintaan:
   • /pair approve <requestId> untuk persetujuan eksplisit
   • /pair approve ketika hanya ada satu permintaan tertunda
   • /pair approve latest untuk yang paling baru

{
  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" }],
  ],
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, opsional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content atau caption, opsional tombol inline presentation; edit yang hanya berisi tombol memperbarui markup balasan)
• createForumTopic (chatId, name, opsional iconColor, iconCustomEmojiId)

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

• [[reply_to_current]] membalas pesan pemicu
• [[reply_to:<id>]] membalas ID pesan Telegram tertentu

• off (default)
• first
• all

• kunci sesi topik menambahkan :topic:<threadId>
• balasan dan pengetikan menargetkan thread topik
• jalur config topik: channels.telegram.groups.<chatId>.topics.<threadId>

• pengiriman pesan menghilangkan message_thread_id (Telegram menolak sendMessage(...thread_id=1))
• tindakan pengetikan tetap menyertakan 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
          }
        }
      }
    }
  }
}

​

Pesan audio

• default: perilaku file audio
• tag [[audio_as_voice]] dalam balasan agen untuk memaksa pengiriman catatan suara
• transkrip catatan suara masuk dibingkai sebagai teks yang dibuat mesin, tidak tepercaya dalam konteks agen; deteksi mention tetap menggunakan transkrip mentah sehingga pesan suara dengan gating mention tetap berfungsi.

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

​

Pesan video

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

​

Stiker

• WEBP statis: diunduh dan diproses (placeholder <media:sticker>)
• TGS animasi: dilewati
• WEBM video: dilewati

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

{
  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 berarti reaksi pengguna hanya terhadap pesan yang dikirim bot (upaya terbaik melalui cache pesan terkirim).
• Peristiwa reaksi tetap mematuhi kontrol akses Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); pengirim tidak sah akan dibuang.
• Telegram tidak menyediakan ID utas dalam pembaruan reaksi.
  • grup non-forum diarahkan ke sesi obrolan grup
  • grup forum diarahkan ke sesi topik umum grup (:topic:1), bukan topik asal yang persis

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback emoji identitas agen (agents.list[].identity.emoji, jika tidak ada ”👀”)

• Telegram mengharapkan emoji unicode (misalnya ”👀”).
• Gunakan "" untuk menonaktifkan reaksi bagi channel atau akun.

• peristiwa migrasi grup (migrate_to_chat_id) untuk memperbarui channels.telegram.groups
• /config set dan /config unset (memerlukan pengaktifan perintah)

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

• Default channels.telegram.textChunkLimit adalah 4000.
• channels.telegram.chunkMode="newline" mengutamakan batas paragraf (baris kosong) sebelum pemisahan berdasarkan panjang.
• channels.telegram.mediaMaxMb (default 100) membatasi ukuran media Telegram masuk dan keluar.
• channels.telegram.mediaGroupFlushMs (default 500) mengontrol berapa lama album/grup media Telegram ditampung sebelum OpenClaw mengirimkannya sebagai satu pesan masuk. Tingkatkan jika bagian album datang terlambat; turunkan untuk mengurangi latensi balasan album.
• channels.telegram.timeoutSeconds mengganti batas waktu klien API Telegram (jika tidak diatur, default grammY berlaku). Klien bot membatasi nilai yang dikonfigurasi di bawah penjaga permintaan teks/pengetikan keluar 60 detik agar grammY tidak membatalkan pengiriman balasan yang terlihat sebelum penjaga transport dan cadangan OpenClaw dapat berjalan. Long polling tetap menggunakan penjaga permintaan getUpdates 45 detik agar polling menganggur tidak ditinggalkan tanpa batas.
• channels.telegram.pollingStallThresholdMs default ke 120000; sesuaikan antara 30000 dan 600000 hanya untuk restart polling-stall positif palsu.
• riwayat konteks grup menggunakan channels.telegram.historyLimit atau messages.groupChat.historyLimit (default 50); 0 menonaktifkan.
• konteks tambahan balasan/kutipan/terusan dinormalisasi menjadi satu jendela konteks percakapan terpilih ketika gateway telah mengamati pesan induk; cache pesan yang diamati berada di status Plugin SQLite OpenClaw, dan openclaw doctor --fix mengimpor sidecar lama. Telegram hanya menyertakan satu reply_to_message dangkal dalam pembaruan, jadi rantai yang lebih lama daripada cache dibatasi oleh payload pembaruan Telegram saat ini.
• allowlist Telegram terutama membatasi siapa yang dapat memicu agen, bukan batas penyuntingan konteks tambahan penuh.
• Kontrol riwayat DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• Konfigurasi channels.telegram.retry berlaku untuk helper pengiriman Telegram (CLI/alat/tindakan) untuk error API keluar yang dapat dipulihkan. Pengiriman balasan akhir masuk juga menggunakan percobaan ulang safe-send terbatas untuk kegagalan pra-koneksi Telegram, tetapi tidak mencoba ulang amplop jaringan pasca-kirim yang ambigu yang dapat menggandakan pesan terlihat.

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id untuk topik forum (atau gunakan target :topic:)

• --presentation dengan blok buttons untuk keyboard inline ketika channels.telegram.capabilities.inlineButtons mengizinkannya
• --pin atau --delivery '{"pin":true}' untuk meminta pengiriman yang disematkan ketika bot dapat menyematkan di chat tersebut
• --force-document untuk mengirim gambar, GIF, dan video keluar sebagai dokumen, bukan unggahan foto terkompresi, media animasi, atau video

• channels.telegram.actions.sendMessage=false menonaktifkan pesan Telegram keluar, termasuk poll
• channels.telegram.actions.poll=false menonaktifkan pembuatan poll Telegram sambil tetap mengaktifkan pengiriman biasa

• channels.telegram.execApprovals.enabled (otomatis aktif ketika setidaknya satu pemberi persetujuan dapat diresolusikan)
• channels.telegram.execApprovals.approvers (fallback ke ID pemilik numerik dari commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (default) | channel | both
• agentFilter, sessionFilter

• Jika requireMention=false, mode privasi Telegram harus mengizinkan visibilitas penuh.
  • BotFather: /setprivacy -> Disable
  • lalu hapus + tambahkan kembali bot ke grup
• openclaw channels status memperingatkan ketika konfigurasi mengharapkan pesan grup tanpa mention.
• openclaw channels status --probe dapat memeriksa ID grup numerik eksplisit; wildcard "*" tidak dapat diperiksa keanggotaannya.
• uji sesi cepat: /activation always.

• ketika channels.telegram.groups ada, grup harus dicantumkan (atau menyertakan "*")
• verifikasi keanggotaan bot di grup
• tinjau log: openclaw logs --follow untuk alasan dilewati

• otorisasi identitas pengirim Anda (pairing dan/atau allowFrom numerik)
• otorisasi perintah tetap berlaku bahkan ketika kebijakan grup adalah open
• setMyCommands failed dengan BOT_COMMANDS_TOO_MUCH berarti menu native memiliki terlalu banyak entri; kurangi perintah plugin/skill/kustom atau nonaktifkan menu native
• Panggilan startup deleteMyCommands / setMyCommands dan panggilan pengetikan sendChatAction dibatasi dan dicoba ulang satu kali melalui cadangan transport Telegram saat batas waktu permintaan. Error jaringan/fetch yang persisten biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke api.telegram.org

• getMe returned 401 adalah kegagalan autentikasi Telegram untuk token bot yang dikonfigurasi.
• Salin ulang atau buat ulang token bot di BotFather, lalu perbarui channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken, atau TELEGRAM_BOT_TOKEN untuk akun default.
• deleteWebhook 401 Unauthorized selama startup juga merupakan kegagalan auth; memperlakukannya sebagai “tidak ada webhook” hanya akan menunda kegagalan token buruk yang sama ke panggilan API berikutnya.

• Node 22+ + fetch/proxy kustom dapat memicu perilaku batal seketika jika tipe AbortSignal tidak cocok.
• Beberapa host meresolusikan api.telegram.org ke IPv6 terlebih dahulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram intermiten.
• Jika log menyertakan TypeError: fetch failed atau Network request for 'getUpdates' failed!, OpenClaw sekarang mencoba ulang ini sebagai error jaringan yang dapat dipulihkan.
• Selama startup polling, OpenClaw menggunakan kembali probe startup getMe yang berhasil untuk grammY sehingga runner tidak memerlukan getMe kedua sebelum getUpdates pertama.
• Jika deleteWebhook gagal dengan error jaringan sementara selama startup polling, OpenClaw melanjutkan ke long polling alih-alih membuat panggilan control-plane pra-polling lain. Webhook yang masih aktif muncul sebagai konflik getUpdates; OpenClaw lalu membangun ulang transport Telegram dan mencoba ulang pembersihan webhook.
• Jika soket Telegram didaur ulang pada kadens tetap yang pendek, periksa channels.telegram.timeoutSeconds yang rendah; klien bot membatasi nilai yang dikonfigurasi di bawah penjaga permintaan keluar dan getUpdates, tetapi rilis lama dapat membatalkan setiap polling atau balasan ketika nilai ini diatur di bawah penjaga tersebut.
• Jika log menyertakan Polling stall detected, OpenClaw memulai ulang polling dan membangun ulang transport Telegram setelah 120 detik tanpa liveness long-poll yang selesai secara default.
• openclaw channels status --probe dan openclaw doctor memperingatkan ketika akun polling yang berjalan belum menyelesaikan getUpdates setelah grace startup, ketika akun webhook yang berjalan belum menyelesaikan setWebhook setelah grace startup, atau ketika aktivitas transport polling terakhir yang berhasil sudah basi.
• Tingkatkan channels.telegram.pollingStallThresholdMs hanya ketika panggilan getUpdates yang berjalan lama sehat tetapi host Anda masih melaporkan restart polling-stall positif palsu. Stall persisten biasanya mengarah ke masalah proxy, DNS, IPv6, atau egress TLS antara host dan api.telegram.org.
• Telegram juga menghormati env proxy proses untuk transport Bot API, termasuk HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, dan varian huruf kecilnya. NO_PROXY / no_proxy tetap dapat melewati api.telegram.org.
• Jika proxy terkelola OpenClaw dikonfigurasi melalui OPENCLAW_PROXY_URL untuk lingkungan layanan dan tidak ada env proxy standar, Telegram juga menggunakan URL tersebut untuk transport Bot API.
• Pada host VPS dengan egress/TLS langsung yang tidak stabil, rutekan panggilan API Telegram melalui channels.telegram.proxy:

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

• Node 22+ default ke autoSelectFamily=true (kecuali WSL2). Urutan hasil DNS Telegram mengikuti OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, lalu channels.telegram.network.dnsResultOrder, lalu default proses seperti NODE_OPTIONS=--dns-result-order=ipv4first; jika tidak ada yang berlaku, Node 22+ beralih ke ipv4first.
• Jika host Anda adalah WSL2 atau secara eksplisit bekerja lebih baik dengan perilaku khusus IPv4, paksa pemilihan family:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Jawaban rentang benchmark RFC 2544 (198.18.0.0/15) sudah diizinkan untuk unduhan media Telegram secara default. Jika fake-IP tepercaya atau proksi transparan menulis ulang api.telegram.org ke alamat privat/internal/penggunaan-khusus lain selama unduhan media, Anda dapat ikut serta dalam bypass khusus Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Opt-in yang sama tersedia per akun di channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Jika proksi Anda me-resolve host media Telegram menjadi 198.18.x.x, biarkan flag berbahaya tetap nonaktif terlebih dahulu. Media Telegram sudah mengizinkan rentang benchmark RFC 2544 secara default.

• Override lingkungan (sementara):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Validasi jawaban DNS:

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