Telegram

• /setprivacy ile gizlilik modunu devre dışı bırakın veya
• botu grup yöneticisi yapın.

• grup eklemelerine izin vermek/reddetmek için /setjoingroups
• grup görünürlüğü davranışı için /setprivacy

• doğrudan sohbetler: önizleme iletisi + editMessageText
• gruplar/konular: önizleme iletisi + editMessageText

• channels.telegram.streaming, off | partial | block | progress olur (varsayılan: partial)
• kısa ilk yanıt önizlemeleri debounce edilir, ardından çalıştırma hala etkinse sınırlı bir gecikmeden sonra somutlaştırılır
• progress, araç ilerlemesi için düzenlenebilir tek bir durum taslağını tutar, araç ilerlemesinden önce yanıt etkinliği geldiğinde kararlı durum etiketini gösterir, tamamlandığında temizler ve son yanıtı normal ileti olarak gönderir
• streaming.preview.toolProgress, araç/ilerleme güncellemelerinin aynı düzenlenen önizleme iletisini yeniden kullanıp kullanmayacağını denetler (varsayılan: önizleme akışı etkinken true)
• streaming.preview.commandText, bu araç ilerleme satırlarının içindeki komut/exec ayrıntısını denetler: raw (varsayılan, yayımlanmış davranışı korur) veya status (yalnızca araç etiketi)
• streaming.progress.commentary (varsayılan: false), geçici ilerleme taslağında assistant yorum/preamble metnini etkinleştirir
• eski channels.telegram.streamMode, boolean streaming değerleri ve emekli edilmiş yerel taslak önizleme anahtarları algılanır; bunları güncel akış yapılandırmasına taşımak için openclaw doctor --fix çalıştırın

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

• kısa DM/grup/konu önizlemeleri: OpenClaw aynı önizleme iletisini korur ve son düzenlemeyi yerinde yapar
• birden fazla Telegram iletisine bölünen uzun son metinler, mümkün olduğunda mevcut önizlemeyi ilk son parça olarak yeniden kullanır, sonra yalnızca kalan parçaları gönderir
• ilerleme modu son yanıtları durum taslağını temizler ve taslağı yanıta düzenlemek yerine normal son teslimatı kullanır
• tamamlanan metin onaylanmadan önce son düzenleme başarısız olursa OpenClaw normal son teslimatı kullanır ve eski önizlemeyi temizler

• /reasoning stream, desteklenen bir kanalın akıl yürütme önizleme yolunu kullanır; Telegram’da üretim sırasında akıl yürütmeyi canlı önizlemeye akıtır
• akıl yürütme önizlemesi son teslimattan sonra silinir; akıl yürütmenin görünür kalması gerektiğinde /reasoning on kullanın
• son yanıt akıl yürütme metni olmadan gönderilir

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

• Aracıya, bu bot/hesap için Telegram zengin iletilerinin kullanılabilir olduğu söylenir.
• Markdown metni OpenClaw’ın Markdown IR’ı üzerinden işlenir ve Telegram zengin HTML olarak gönderilir.
• Açık zengin HTML yükleri başlıklar, tablolar, ayrıntılar, zengin medya ve formüller gibi desteklenen Bot API 10.1 etiketlerini korur.
• Medya açıklamaları yine Telegram HTML açıklamaları kullanır, çünkü zengin iletiler açıklamaların yerini almaz.

• commands.native: "auto", Telegram için yerel komutları etkinleştirir

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

• adlar normalize edilir (baştaki / kaldırılır, küçük harfe çevrilir)
• geçerli desen: a-z, 0-9, _, uzunluk 1..32
• özel komutlar yerel komutları geçersiz kılamaz
• çakışmalar/yinelenenler atlanır ve günlüğe yazılır

• özel komutlar yalnızca menü girişleridir; davranışı otomatik olarak uygulamazlar
• plugin/skill komutları, Telegram menüsünde gösterilmese bile yazıldığında çalışabilir

• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, Telegram menüsünün kırpmadan sonra hala taştığı anlamına gelir; plugin/skill/özel komutları azaltın veya channels.telegram.commands.native seçeneğini devre dışı bırakın.
• Doğrudan Bot API curl komutları çalışırken deleteWebhook, deleteMyCommands veya setMyCommands işleminin 404: Not Found ile başarısız olması, channels.telegram.apiRoot değerinin tam /bot<TOKEN> uç noktasına ayarlandığı anlamına gelebilir. apiRoot yalnızca Bot API kökü olmalıdır ve openclaw doctor --fix yanlışlıkla eklenen sonda /bot<TOKEN> kısmını kaldırır.
• getMe returned 401, Telegram’ın yapılandırılan bot token’ını reddettiği anlamına gelir. botToken, tokenFile veya TELEGRAM_BOT_TOKEN değerini güncel BotFather token’ıyla güncelleyin; OpenClaw yoklamadan önce durur, bu nedenle bu bir Webhook temizleme hatası olarak raporlanmaz.
• Ağ/fetch hatalarıyla setMyCommands failed genellikle api.telegram.org için giden DNS/HTTPS’nin engellendiği anlamına gelir.

​

Cihaz eşleştirme komutları (device-pair plugin)

1. /pair kurulum kodu üretir
2. kodu iOS uygulamasına yapıştırın
3. /pair pending bekleyen istekleri listeler (rol/kapsamlar dahil)
4. isteği onaylayın:
   • açık onay için /pair approve <requestId>
   • yalnızca bir bekleyen istek olduğunda /pair approve
   • en yeni için /pair approve latest

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

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

• off
• dm
• group
• all
• allowlist (varsayılan)

{
  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, isteğe bağlı mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content veya caption, isteğe bağlı presentation satır içi düğmeleri; yalnızca düğme düzenlemeleri yanıt işaretlemesini günceller)
• createForumTopic (chatId, name, isteğe bağlı iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (varsayılan: devre dışı)

• [[reply_to_current]] tetikleyen mesaja yanıt verir
• [[reply_to:<id>]] belirli bir Telegram mesaj kimliğine yanıt verir

• off (varsayılan)
• first
• all

• konu oturumu anahtarları :topic:<threadId> ekler
• yanıtlar ve yazıyor göstergesi konu iş parçacığını hedefler
• konu yapılandırma yolu: channels.telegram.groups.<chatId>.topics.<threadId>

• mesaj gönderimleri message_thread_id değerini atlar (Telegram sendMessage(...thread_id=1) çağrısını reddeder)
• yazıyor eylemleri yine de message_thread_id içerir

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

​

Sesli mesajlar

• varsayılan: ses dosyası davranışı
• ses notu gönderimini zorlamak için ajan yanıtında [[audio_as_voice]] etiketi
• gelen ses notu transkriptleri ajan bağlamında makine tarafından oluşturulmuş, güvenilmeyen metin olarak çerçevelenir; bahsetme algılama yine de ham transkripti kullanır, böylece bahsetme geçitli sesli mesajlar çalışmaya devam eder.

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

​

Video mesajları

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

​

Çıkartmalar

• statik WEBP: indirilir ve işlenir (yer tutucu <media:sticker>)
• animasyonlu TGS: atlanır
• video WEBM: atlanır

• 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 (varsayılan: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (varsayılan: minimal)

• own, yalnızca bot tarafından gönderilen mesajlara verilen kullanıcı tepkileri anlamına gelir (gönderilmiş mesaj önbelleği üzerinden en iyi çaba).
• Tepki olayları yine de Telegram erişim kontrollerine (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) uyar; yetkisiz gönderenler bırakılır.
• Telegram, tepki güncellemelerinde konu kimlikleri sağlamaz.
  • forum olmayan gruplar grup sohbeti oturumuna yönlendirilir
  • forum grupları, tam kaynak konuya değil, grubun genel konu oturumuna (:topic:1) yönlendirilir

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• aracı kimliği emoji yedeği (agents.list[].identity.emoji, aksi halde ”👀”)

• Telegram unicode emoji bekler (örneğin ”👀”).
• Bir kanal veya hesap için tepkiyi devre dışı bırakmak üzere "" kullanın.

• channels.telegram.groups değerini güncellemek için grup taşıma olayları (migrate_to_chat_id)
• /config set ve /config unset (komut etkinleştirmesi gerektirir)

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

• channels.telegram.textChunkLimit varsayılanı 4000’dir.
• channels.telegram.chunkMode="newline", uzunluğa göre bölmeden önce paragraf sınırlarını (boş satırlar) tercih eder.
• channels.telegram.mediaMaxMb (varsayılan 100), gelen ve giden Telegram medya boyutunu sınırlar.
• channels.telegram.mediaGroupFlushMs (varsayılan 500), Telegram albümlerinin/medya gruplarının OpenClaw tarafından tek bir gelen mesaj olarak gönderilmeden önce ne kadar süre arabelleğe alınacağını kontrol eder. Albüm parçaları geç geliyorsa artırın; albüm yanıt gecikmesini azaltmak için düşürün.
• channels.telegram.timeoutSeconds, Telegram API istemcisi zaman aşımını geçersiz kılar (ayarlanmamışsa grammY varsayılanı uygulanır). Bot istemcileri, yapılandırılan değerleri 60 saniyelik giden metin/yazıyor isteği korumasının altında sınırlayarak grammY’nin OpenClaw’ın taşıma koruması ve geri dönüşü çalışmadan önce görünür yanıt teslimini iptal etmesini önler. Uzun yoklama hâlâ 45 saniyelik bir getUpdates isteği koruması kullanır, böylece boşta kalan yoklamalar süresiz olarak terk edilmez.
• channels.telegram.pollingStallThresholdMs varsayılan olarak 120000 değerindedir; yalnızca yanlış pozitif yoklama takılması yeniden başlatmaları için 30000 ile 600000 arasında ayarlayın.
• grup bağlam geçmişi channels.telegram.historyLimit veya messages.groupChat.historyLimit (varsayılan 50) kullanır; 0 devre dışı bırakır.
• yanıt/alıntı/iletme ek bağlamı, Gateway üst mesajları gözlemlediğinde seçili tek bir konuşma bağlamı penceresine normalleştirilir; gözlemlenen mesaj önbelleği OpenClaw SQLite Plugin durumunda bulunur ve openclaw doctor --fix eski yan dosyaları içe aktarır. Telegram güncellemelerde yalnızca tek bir sığ reply_to_message içerir, bu yüzden önbellekten daha eski zincirler Telegram’ın mevcut güncelleme yüküyle sınırlıdır.
• Telegram izin listeleri öncelikli olarak agent’ı kimin tetikleyebileceğini denetler; tam bir ek bağlam redaksiyon sınırı değildir.
• DM geçmişi denetimleri:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry yapılandırması, kurtarılabilir giden API hataları için Telegram gönderme yardımcılarına (CLI/araçlar/eylemler) uygulanır. Gelen son yanıt teslimi de Telegram bağlantı öncesi hataları için sınırlı güvenli gönderme yeniden denemesi kullanır, ancak görünür mesajları çoğaltabilecek belirsiz gönderim sonrası ağ zarflarını yeniden denemez.

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
• forum konuları için --thread-id (veya bir :topic: hedefi kullanın)

• channels.telegram.capabilities.inlineButtons izin verdiğinde satır içi klavyeler için buttons bloklarıyla --presentation
• bot o sohbette sabitleyebildiğinde sabitlenmiş teslim istemek için --pin veya --delivery '{"pin":true}'
• giden görselleri, GIF’leri ve videoları sıkıştırılmış fotoğraf, animasyonlu medya veya video yüklemeleri yerine belge olarak göndermek için --force-document

• channels.telegram.actions.sendMessage=false, yoklamalar dahil giden Telegram mesajlarını devre dışı bırakır
• channels.telegram.actions.poll=false, normal gönderimleri etkin bırakırken Telegram yoklaması oluşturmayı devre dışı bırakır

• channels.telegram.execApprovals.enabled (en az bir onaylayıcı çözümlenebildiğinde otomatik etkinleşir)
• channels.telegram.execApprovals.approvers (commands.ownerAllowFrom içindeki sayısal sahip kimliklerine geri döner)
• channels.telegram.execApprovals.target: dm (varsayılan) | channel | both
• agentFilter, sessionFilter

• requireMention=false ise Telegram gizlilik modu tam görünürlüğe izin vermelidir.
  • BotFather: /setprivacy -> Devre dışı bırak
  • ardından botu gruptan çıkarıp yeniden ekleyin
• openclaw channels status, yapılandırma bahsedilmeyen grup mesajları beklediğinde uyarır.
• openclaw channels status --probe açık sayısal grup kimliklerini denetleyebilir; joker karakter "*" için üyelik yoklaması yapılamaz.
• hızlı oturum testi: /activation always.

• channels.telegram.groups varsa grup listelenmelidir (veya "*" içermelidir)
• botun gruptaki üyeliğini doğrulayın
• atlama nedenleri için günlükleri inceleyin: openclaw logs --follow

• gönderen kimliğinizi yetkilendirin (eşleştirme ve/veya sayısal allowFrom)
• grup politikası open olsa bile komut yetkilendirmesi hâlâ uygulanır
• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, yerel menüde çok fazla giriş olduğu anlamına gelir; Plugin/skill/özel komutları azaltın veya yerel menüleri devre dışı bırakın
• deleteMyCommands / setMyCommands başlangıç çağrıları ve sendChatAction yazıyor çağrıları sınırlıdır ve istek zaman aşımında Telegram’ın taşıma geri dönüşü üzerinden bir kez yeniden denenir. Kalıcı ağ/fetch hataları genellikle api.telegram.org için DNS/HTTPS erişilebilirliği sorunlarını gösterir

• getMe returned 401, yapılandırılan bot token’ı için bir Telegram kimlik doğrulama hatasıdır.
• BotFather’da bot token’ını yeniden kopyalayın veya yeniden oluşturun, ardından varsayılan hesap için channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken veya TELEGRAM_BOT_TOKEN öğesini güncelleyin.
• Başlangıç sırasında deleteWebhook 401 Unauthorized da bir kimlik doğrulama hatasıdır; bunu “webhook yok” olarak ele almak, aynı hatalı token sorununu yalnızca sonraki API çağrılarına ertelemiş olur.

• Node 22+ ve özel fetch/proxy, AbortSignal türleri uyuşmazsa anında iptal davranışını tetikleyebilir.
• Bazı ana makineler api.telegram.org adresini önce IPv6’ya çözümler; bozuk IPv6 çıkışı aralıklı Telegram API hatalarına neden olabilir.
• Günlükler TypeError: fetch failed veya Network request for 'getUpdates' failed! içeriyorsa, OpenClaw artık bunları kurtarılabilir ağ hataları olarak yeniden dener.
• Yoklama başlangıcı sırasında OpenClaw, grammY için başarılı başlangıç getMe yoklamasını yeniden kullanır, böylece çalıştırıcının ilk getUpdates öncesinde ikinci bir getMe çağrısına ihtiyacı olmaz.
• Yoklama başlangıcı sırasında deleteWebhook geçici bir ağ hatasıyla başarısız olursa OpenClaw başka bir yoklama öncesi denetim düzlemi çağrısı yapmak yerine uzun yoklamaya devam eder. Hâlâ etkin olan bir webhook getUpdates çakışması olarak görünür; ardından OpenClaw Telegram taşımasını yeniden oluşturur ve webhook temizliğini yeniden dener.
• Telegram soketleri kısa ve sabit bir ritimde yeniden oluşturuluyorsa düşük bir channels.telegram.timeoutSeconds olup olmadığını denetleyin; bot istemcileri yapılandırılmış değerleri giden ve getUpdates isteği korumalarının altında sınırlar, ancak eski sürümler bu değer korumaların altına ayarlandığında her yoklamayı veya yanıtı iptal edebiliyordu.
• Günlükler Polling stall detected içeriyorsa OpenClaw, varsayılan olarak tamamlanmış uzun yoklama canlılığı olmadan geçen 120 saniyeden sonra yoklamayı yeniden başlatır ve Telegram taşımasını yeniden oluşturur.
• openclaw channels status --probe ve openclaw doctor, çalışan bir yoklama hesabı başlangıç toleransından sonra getUpdates tamamlamadığında, çalışan bir webhook hesabı başlangıç toleransından sonra setWebhook tamamlamadığında veya son başarılı yoklama taşıma etkinliği bayatladığında uyarır.
• channels.telegram.pollingStallThresholdMs değerini yalnızca uzun süre çalışan getUpdates çağrıları sağlıklı olduğu halde ana makineniz hâlâ yanlış yoklama takılması yeniden başlatmaları bildiriyorsa artırın. Kalıcı takılmalar genellikle ana makine ile api.telegram.org arasındaki proxy, DNS, IPv6 veya TLS çıkış sorunlarına işaret eder.
• Telegram ayrıca Bot API taşıması için HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ve bunların küçük harfli varyantları dahil süreç proxy ortam değişkenlerini dikkate alır. NO_PROXY / no_proxy yine de api.telegram.org için proxy’yi atlayabilir.
• OpenClaw yönetimli proxy bir hizmet ortamı için OPENCLAW_PROXY_URL üzerinden yapılandırılmışsa ve standart proxy ortam değişkeni yoksa Telegram da Bot API taşıması için bu URL’yi kullanır.
• Kararsız doğrudan çıkış/TLS olan VPS ana makinelerinde Telegram API çağrılarını channels.telegram.proxy üzerinden yönlendirin:

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

• Node 22+ varsayılan olarak autoSelectFamily=true kullanır (WSL2 hariç). Telegram DNS sonuç sırası önce OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, ardından channels.telegram.network.dnsResultOrder, ardından NODE_OPTIONS=--dns-result-order=ipv4first gibi süreç varsayılanını izler; hiçbiri geçerli değilse Node 22+ ipv4first değerine geri döner.
• Ana makineniz WSL2 ise veya açıkça yalnızca IPv4 davranışıyla daha iyi çalışıyorsa, aile seçimini zorlayın:

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544 kıyaslama aralığı yanıtlarına (198.18.0.0/15) Telegram medya indirmeleri için varsayılan olarak zaten izin verilir. Güvenilir bir fake-IP veya saydam proxy, medya indirmeleri sırasında api.telegram.org adresini başka bir özel/dahili/özel kullanımlı adrese yeniden yazıyorsa, yalnızca Telegram’a özgü bypass’ı etkinleştirebilirsiniz:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Aynı etkinleştirme, hesap başına channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork konumunda da kullanılabilir.
• Proxy’niz Telegram medya ana makinelerini 198.18.x.x adreslerine çözümlüyorsa, önce tehlikeli bayrağı kapalı bırakın. Telegram medyası RFC 2544 kıyaslama aralığına varsayılan olarak zaten izin verir.

• Ortam geçersiz kılmaları (geçici):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• DNS yanıtlarını doğrulayın:

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