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 mesajı + editMessageText
• gruplar/konular: önizleme mesajı + editMessageText

• channels.telegram.streaming, off | partial | block | progress olur (varsayılan: partial)
• progress, araç ilerlemesi için düzenlenebilir tek bir durum taslağı tutar, tamamlandığında bunu temizler ve son yanıtı normal bir mesaj olarak gönderir
• streaming.preview.toolProgress, araç/ilerleme güncellemelerinin aynı düzenlenmiş önizleme mesajını 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/çalıştırma ayrıntısını denetler: raw (varsayılan, yayımlanmış davranışı korur) veya status (yalnızca araç etiketi)
• eski channels.telegram.streamMode ve boolean streaming değerleri algılanır; bunları channels.telegram.streaming.mode değerine 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 mesajını tutar ve son düzenlemeyi yerinde yapar
• birden çok Telegram mesajına bölünen uzun metin son yanıtları, 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 teslimi kullanır
• tamamlanan metin doğrulanmadan önce son düzenleme başarısız olursa OpenClaw normal son teslimi kullanır ve bayat önizlemeyi temizler

• /reasoning stream, oluşturma sırasında akıl yürütmeyi canlı önizlemeye gönderir
• akıl yürütme önizlemesi son teslimden 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

• Markdown benzeri metin, Telegram açısından güvenli HTML’ye işlenir.
• Desteklenen Telegram HTML etiketleri korunur; desteklenmeyen HTML kaçışlanır.
• Telegram ayrıştırılmış HTML’yi reddederse OpenClaw düz metin olarak yeniden dener.

• 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 normalleştirilir (başındaki / kaldırılır, küçük harfe çevrilir)
• geçerli kalıp: a-z, 0-9, _, uzunluk 1..32
• özel komutlar yerel komutları geçersiz kılamaz
• çakışmalar/çoğaltmalar atlanır ve günlüğe kaydedilir

• özel komutlar yalnızca menü girdileridir; davranışı otomatik olarak uygulamazlar
• Plugin/skill komutları, Telegram menüsünde gösterilmese bile yazıldığında çalışmaya devam edebilir

• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, Telegram menüsünün kırpmadan sonra hâlâ taştığı anlamına gelir; Plugin/skill/özel komutları azaltın veya channels.telegram.commands.native ayarını devre dışı bırakın.
• Doğrudan Bot API curl komutları çalışırken deleteWebhook, deleteMyCommands veya setMyCommands işlemlerinin 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 eklenmiş sondaki /bot<TOKEN> bölümünü kaldırır.
• getMe returned 401, Telegram’ın yapılandırılmış bot token’ını reddettiği anlamına gelir. botToken, tokenFile veya TELEGRAM_BOT_TOKEN değerini güncel BotFather token’ı ile güncelleyin; OpenClaw yoklamadan önce durur, bu nedenle bu bir Webhook temizleme hatası olarak bildirilmez.
• Ağ/fetch hatalarıyla setMyCommands failed genellikle api.telegram.org adresine giden DNS/HTTPS’in engellendiği anlamına gelir.

​

Cihaz eşleştirme komutları (device-pair Plugin’i)

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

• sendMessage (to, content, isteğe bağlı mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• 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 eylemi konu ileti dizisini hedefler
• konu yapılandırma yolu: channels.telegram.groups.<chatId>.topics.<threadId>

• mesaj gönderimleri message_thread_id öğesini çıkarır (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
          }
        }
      }
    }
  }
}

​

Ses mesajları

• varsayılan: ses dosyası davranışı
• sesli not gönderimini zorlamak için aracı yanıtında [[audio_as_voice]] etiketi
• gelen sesli not dökümleri, aracı bağlamında makine tarafından üretilmiş, güvenilmeyen metin olarak çerçevelenir; bahsetme algılama yine de ham dökümü kullanır, böylece bahsetme kapılı 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

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

• own, yalnızca bot tarafından gönderilen mesajlara kullanıcı tepkileri anlamına gelir (gönderilen mesaj önbelleği üzerinden en iyi çaba).
• Tepki olayları yine de Telegram erişim kontrollerine uyar (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); yetkisiz gönderenler düşürülür.
• Telegram, tepki güncellemelerinde iş parçacığı 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), OpenClaw bunları tek bir gelen mesaj olarak dağıtmadan önce Telegram albümlerinin/medya gruplarının ne kadar süre arabelleğe alınacağını denetler. 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 (ayarlanmazsa grammY varsayılanı geçerlidir). Bot istemcileri, yapılandırılan değerleri 60 saniyelik giden metin/yazıyor isteği korumasının altına sıkıştırır; böylece grammY, OpenClaw’ın aktarım koruması ve yedeği çalışmadan önce görünür yanıt teslimini iptal etmez. Uzun yoklama yine de 45 saniyelik getUpdates isteği koruması kullanır, böylece boşta yoklamalar süresiz olarak terk edilmez.
• channels.telegram.pollingStallThresholdMs varsayılan olarak 120000 değerindedir; yalnızca yanlış pozitif yoklama-durması 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 kullanır (varsayılan 50); 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 oturum deposunun yanında kalıcı hale getirilir. Telegram güncellemelerde yalnızca tek bir sığ reply_to_message içerir; bu nedenle önbellekten daha eski zincirler Telegram’ın mevcut güncelleme yüküyle sınırlıdır.
• Telegram izin listeleri öncelikle aracıyı kimin tetikleyebileceğini kapılar; tam bir ek bağlam redaksiyon sınırı değildir.
• DM geçmiş 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 ön bağlantı hataları için sınırlı bir güvenli-gönder 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örüntüleri, 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ırakarak Telegram yoklaması oluşturmayı devre dışı bırakır

• channels.telegram.execApprovals.enabled (en az bir onaylayıcı çözümlenebilir olduğunda 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 kaldırıp yeniden ekleyin
• Yapılandırma etiketsiz grup mesajları beklediğinde openclaw channels status 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 "*" dahil edilmelidir)
• 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 ilkesi open olsa bile komut yetkilendirmesi yine de geçerlidir
• BOT_COMMANDS_TOO_MUCH ile setMyCommands failed, yerel menüde çok fazla giriş olduğu anlamına gelir; Plugin/skill/özel komutlarını azaltın veya yerel menüleri devre dışı bırakın
• Başlangıçtaki deleteMyCommands / setMyCommands çağrıları ve sendChatAction yazıyor çağrıları sınırlandırılır ve istek zaman aşımında Telegram’ın aktarım yedeği ü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ılmış bot token’ı için bir Telegram kimlik doğrulama hatasıdır.
• BotFather içinde 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 değerini 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 hatasını yalnızca sonraki API çağrılarına ertelemiş olur.

• Node 22+ + özel fetch/proxy, AbortSignal türleri uyuşmuyorsa anında abort davranışını tetikleyebilir.
• Bazı host’lar api.telegram.org adresini önce IPv6’ya çözer; bozuk IPv6 çıkışı aralıklı Telegram API hatalarına neden olabilir.
• Günlüklerde TypeError: fetch failed veya Network request for 'getUpdates' failed! varsa OpenClaw artık bunları kurtarılabilir ağ hataları olarak yeniden dener.
• Polling başlangıcı sırasında OpenClaw, başarılı başlangıç getMe yoklamasını grammY için yeniden kullanır; böylece runner ilk getUpdates öncesinde ikinci bir getMe çağrısına ihtiyaç duymaz.
• Polling başlangıcı sırasında deleteWebhook geçici bir ağ hatasıyla başarısız olursa OpenClaw başka bir polling öncesi kontrol düzlemi çağrısı yapmak yerine long polling’e devam eder. Hâlâ etkin olan bir webhook, getUpdates çakışması olarak görünür; OpenClaw ardından Telegram aktarımını yeniden oluşturur ve webhook temizliğini yeniden dener.
• Telegram soketleri kısa ve sabit bir aralıkla yenileniyorsa düşük bir channels.telegram.timeoutSeconds değeri olup olmadığını kontrol edin; bot istemcileri, yapılandırılmış değerleri giden istek ve getUpdates istek korumalarının altına düşmeyecek şekilde sınırlar, ancak eski sürümler bu değerler bu korumaların altındayken her polling veya yanıtı abort edebiliyordu.
• Günlüklerde Polling stall detected varsa OpenClaw varsayılan olarak 120 saniye boyunca tamamlanmış long-poll canlılığı olmadan polling’i yeniden başlatır ve Telegram aktarımını yeniden oluşturur.
• openclaw channels status --probe ve openclaw doctor, çalışan bir polling 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ı polling aktarım etkinliği bayatladığında uyarır.
• channels.telegram.pollingStallThresholdMs değerini yalnızca uzun süren getUpdates çağrıları sağlıklıyken ancak host’unuz hâlâ yanlış polling-stall yeniden başlatmaları bildiriyorsa artırın. Kalıcı takılmalar genellikle host ile api.telegram.org arasındaki proxy, DNS, IPv6 veya TLS çıkış sorunlarına işaret eder.
• Telegram ayrıca Bot API aktarımı için HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ve bunların küçük harfli varyantları dahil işlem proxy env değerlerini dikkate alır. NO_PROXY / no_proxy yine de api.telegram.org adresini atlayabilir.
• OpenClaw yönetimli proxy bir hizmet ortamı için OPENCLAW_PROXY_URL üzerinden yapılandırılmışsa ve standart proxy env yoksa Telegram da Bot API aktarımı için bu URL’yi kullanır.
• Kararsız doğrudan çıkış/TLS bulunan VPS host’larında 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, sonra channels.telegram.network.dnsResultOrder, sonra NODE_OPTIONS=--dns-result-order=ipv4first gibi işlem varsayılanını izler; hiçbiri geçerli değilse Node 22+ ipv4first değerine geri döner.
• Host’unuz 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 private/internal/special-use adrese yeniden yazıyorsa yalnızca Telegram için geçerli bypass’a katılabilirsiniz:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Aynı katılım hesap başına channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork altında da kullanılabilir.
• Proxy’niz Telegram medya host’larını 198.18.x.x içine çözüyorsa önce tehlikeli bayrağı kapalı bırakın. Telegram medyası zaten varsayılan olarak RFC 2544 kıyaslama aralığına 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