Telegram

• désactiver le mode de confidentialité via /setprivacy, soit
• faire du bot un administrateur du groupe.

• /setjoingroups pour autoriser/refuser les ajouts à des groupes
• /setprivacy pour le comportement de visibilité dans les groupes

• discussions directes : message d’aperçu + editMessageText
• groupes/sujets : message d’aperçu + editMessageText

• channels.telegram.streaming vaut off | partial | block | progress (par défaut : partial)
• progress conserve un brouillon de statut modifiable pour la progression des outils, l’efface à la fin, puis envoie la réponse finale comme un message normal
• streaming.preview.toolProgress contrôle si les mises à jour d’outil/de progression réutilisent le même message d’aperçu modifié (par défaut : true lorsque le streaming d’aperçu est actif)
• streaming.preview.commandText contrôle le détail des commandes/exécutions dans ces lignes de progression d’outil : raw (par défaut, préserve le comportement publié) ou status (libellé d’outil uniquement)
• les anciens channels.telegram.streamMode et valeurs booléennes streaming sont détectés ; exécutez openclaw doctor --fix pour les migrer vers channels.telegram.streaming.mode

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

• aperçus courts en DM/groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue la modification finale sur place
• les finales de texte longues qui se divisent en plusieurs messages Telegram réutilisent l’aperçu existant comme premier bloc final lorsque c’est possible, puis n’envoient que les blocs restants
• les finales en mode progression effacent le brouillon de statut et utilisent la livraison finale normale au lieu de modifier le brouillon pour en faire la réponse
• si la modification finale échoue avant que le texte terminé soit confirmé, OpenClaw utilise la livraison finale normale et nettoie l’aperçu obsolète

• /reasoning stream envoie le raisonnement à l’aperçu en direct pendant la génération
• l’aperçu de raisonnement est supprimé après la livraison finale ; utilisez /reasoning on lorsque le raisonnement doit rester visible
• la réponse finale est envoyée sans texte de raisonnement

• Le texte de type Markdown est rendu en HTML compatible Telegram.
• Les balises HTML prises en charge par Telegram sont préservées ; le HTML non pris en charge est échappé.
• Si Telegram rejette le HTML analysé, OpenClaw réessaie en texte brut.

• commands.native: "auto" active les commandes natives pour Telegram

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

• les noms sont normalisés (suppression du / initial, minuscules)
• motif valide : a-z, 0-9, _, longueur 1..32
• les commandes personnalisées ne peuvent pas remplacer les commandes natives
• les conflits/doublons sont ignorés et journalisés

• les commandes personnalisées sont uniquement des entrées de menu ; elles n’implémentent pas automatiquement un comportement
• les commandes de Plugin/Skills peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne s’affichent pas dans le menu Telegram

• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu Telegram dépassait encore la limite après réduction ; réduisez les commandes de Plugin/Skills/personnalisées ou désactivez channels.telegram.commands.native.
• L’échec de deleteWebhook, deleteMyCommands ou setMyCommands avec 404: Not Found alors que les commandes curl directes de l’API Bot fonctionnent peut signifier que channels.telegram.apiRoot a été défini sur le point de terminaison complet /bot<TOKEN>. apiRoot doit être uniquement la racine de l’API Bot, et openclaw doctor --fix supprime un suffixe /bot<TOKEN> accidentel.
• getMe returned 401 signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour botToken, tokenFile ou TELEGRAM_BOT_TOKEN avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation, ce qui évite que cela soit signalé comme un échec de nettoyage de Webhook.
• setMyCommands failed avec des erreurs réseau/fetch signifie généralement que le DNS/HTTPS sortant vers api.telegram.org est bloqué.

​

Commandes d’appairage d’appareil (Plugin device-pair)

1. /pair génère un code de configuration
2. collez le code dans l’application iOS
3. /pair pending liste les demandes en attente (y compris rôle/portées)
4. approuvez la demande :
   • /pair approve <requestId> pour une approbation explicite
   • /pair approve lorsqu’il n’y a qu’une seule demande en attente
   • /pair approve latest pour la plus récente

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

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

• off
• dm
• group
• all
• allowlist (par défaut)

{
  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, optionnel mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, optionnel iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (par défaut : désactivé)

• [[reply_to_current]] répond au message déclencheur
• [[reply_to:<id>]] répond à un ID de message Telegram spécifique

• off (par défaut)
• first
• all

• les clés de session de sujet ajoutent :topic:<threadId>
• les réponses et l’indication de saisie ciblent le fil du sujet
• chemin de configuration du sujet : channels.telegram.groups.<chatId>.topics.<threadId>

• les envois de message omettent message_thread_id (Telegram rejette sendMessage(...thread_id=1))
• les actions de saisie incluent toujours 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
          }
        }
      }
    }
  }
}

​

Messages audio

• par défaut : comportement de fichier audio
• balise [[audio_as_voice]] dans la réponse de l’agent pour forcer l’envoi en note vocale
• les transcriptions de notes vocales entrantes sont encadrées comme du texte généré par machine, non fiable, dans le contexte de l’agent ; la détection des mentions utilise toujours la transcription brute afin que les messages vocaux soumis à mention continuent de fonctionner.

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

​

Messages vidéo

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

​

Stickers

• WEBP statique : téléchargé et traité (placeholder <media:sticker>)
• TGS animé : ignoré
• WEBM vidéo : ignoré

• 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 (par défaut : own)
• channels.telegram.reactionLevel : off | ack | minimal | extensive (par défaut : minimal)

• own signifie uniquement les réactions des utilisateurs aux messages envoyés par le bot (au mieux via le cache des messages envoyés).
• Les événements de réaction respectent toujours les contrôles d’accès Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom) ; les expéditeurs non autorisés sont ignorés.
• Telegram ne fournit pas d’ID de fil dans les mises à jour de réaction.
  • les groupes non-forum sont routés vers la session de chat de groupe
  • les groupes de forum sont routés vers la session du sujet général du groupe (:topic:1), et non vers le sujet d’origine exact

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• repli sur l’emoji d’identité de l’agent (agents.list[].identity.emoji, sinon ”👀”)

• Telegram attend un emoji Unicode (par exemple ”👀”).
• Utilisez "" pour désactiver la réaction pour un canal ou un compte.

• les événements de migration de groupe (migrate_to_chat_id) pour mettre à jour channels.telegram.groups
• /config set et /config unset (nécessite l’activation des commandes)

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

• La valeur par défaut de channels.telegram.textChunkLimit est 4000.
• channels.telegram.chunkMode="newline" privilégie les limites de paragraphes (lignes vides) avant le découpage par longueur.
• channels.telegram.mediaMaxMb (par défaut 100) plafonne la taille des médias Telegram entrants et sortants.
• channels.telegram.mediaGroupFlushMs (par défaut 500) contrôle la durée pendant laquelle les albums/groupes de médias Telegram sont mis en mémoire tampon avant qu’OpenClaw les distribue comme un seul message entrant. Augmentez-la si des parties d’album arrivent tard ; diminuez-la pour réduire la latence de réponse aux albums.
• channels.telegram.timeoutSeconds remplace le délai d’expiration du client API Telegram (s’il n’est pas défini, la valeur par défaut de grammY s’applique). Les clients bot bornent les valeurs configurées sous le garde de requête de texte/frappe sortant de 60 secondes afin que grammY n’interrompe pas la livraison de réponse visible avant que le garde de transport d’OpenClaw et le repli puissent s’exécuter. Le long polling utilise toujours un garde de requête getUpdates de 45 secondes afin que les polls inactifs ne soient pas abandonnés indéfiniment.
• channels.telegram.pollingStallThresholdMs vaut par défaut 120000 ; ajustez entre 30000 et 600000 uniquement pour les redémarrages sur blocage de polling faussement positifs.
• l’historique de contexte de groupe utilise channels.telegram.historyLimit ou messages.groupChat.historyLimit (par défaut 50) ; 0 le désactive.
• le contexte supplémentaire de réponse/citation/transfert est normalisé dans une seule fenêtre de contexte de conversation sélectionnée lorsque le Gateway a observé les messages parents ; le cache des messages observés est persisté à côté du stockage de session. Telegram n’inclut qu’un seul reply_to_message superficiel dans les mises à jour, les chaînes plus anciennes que le cache sont donc limitées à la charge utile de mise à jour actuelle de Telegram.
• les listes d’autorisation Telegram contrôlent principalement qui peut déclencher l’agent, pas une frontière complète de masquage du contexte supplémentaire.
• Contrôles de l’historique DM :
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• La configuration channels.telegram.retry s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de réponse finale entrante utilise aussi une nouvelle tentative bornée d’envoi sûr pour les échecs de préconnexion Telegram, mais elle ne réessaie pas les enveloppes réseau ambiguës après envoi qui pourraient dupliquer les messages visibles.

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 pour les sujets de forum (ou utilisez une cible :topic:)

• --presentation avec des blocs buttons pour les claviers en ligne lorsque channels.telegram.capabilities.inlineButtons l’autorise
• --pin ou --delivery '{"pin":true}' pour demander une livraison épinglée lorsque le bot peut épingler dans ce chat
• --force-document pour envoyer les images, GIF et vidéos sortants comme documents au lieu d’envois compressés de photo, média animé ou vidéo

• channels.telegram.actions.sendMessage=false désactive les messages Telegram sortants, y compris les polls
• channels.telegram.actions.poll=false désactive la création de polls Telegram tout en laissant les envois réguliers activés

• channels.telegram.execApprovals.enabled (s’active automatiquement lorsqu’au moins un approbateur peut être résolu)
• channels.telegram.execApprovals.approvers (se replie sur les ID numériques des propriétaires depuis commands.ownerAllowFrom)
• channels.telegram.execApprovals.target : dm (par défaut) | channel | both
• agentFilter, sessionFilter

• Si requireMention=false, le mode de confidentialité Telegram doit autoriser une visibilité complète.
  • BotFather : /setprivacy -> Disable
  • puis supprimez et réajoutez le bot au groupe
• openclaw channels status avertit lorsque la configuration attend des messages de groupe sans mention.
• openclaw channels status --probe peut vérifier des ID de groupe numériques explicites ; le caractère générique "*" ne peut pas faire l’objet d’une vérification d’appartenance.
• test rapide de session : /activation always.

• lorsque channels.telegram.groups existe, le groupe doit être listé (ou inclure "*")
• vérifiez l’appartenance du bot au groupe
• consultez les journaux : openclaw logs --follow pour les raisons d’ignorance

• autorisez l’identité de votre expéditeur (appariement et/ou allowFrom numérique)
• l’autorisation des commandes s’applique toujours même lorsque la stratégie de groupe est open
• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu natif contient trop d’entrées ; réduisez les commandes de plugins/Skills/personnalisées ou désactivez les menus natifs
• les appels de démarrage deleteMyCommands / setMyCommands et les appels de saisie sendChatAction sont bornés et réessayent une fois via le repli de transport de Telegram en cas d’expiration de la requête. Les erreurs réseau/fetch persistantes indiquent généralement des problèmes d’accessibilité DNS/HTTPS vers api.telegram.org

• getMe returned 401 est un échec d’authentification Telegram pour le jeton de bot configuré.
• Recopiez ou régénérez le jeton du bot dans BotFather, puis mettez à jour channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken ou TELEGRAM_BOT_TOKEN pour le compte par défaut.
• deleteWebhook 401 Unauthorized pendant le démarrage est également un échec d’authentification ; le traiter comme « aucun webhook n’existe » ne ferait que reporter le même échec de mauvais jeton à des appels d’API ultérieurs.

• Node 22+ avec un fetch/proxy personnalisé peut déclencher un comportement d’abandon immédiat si les types AbortSignal ne correspondent pas.
• Certains hôtes résolvent d’abord api.telegram.org en IPv6 ; une sortie IPv6 défectueuse peut provoquer des échecs intermittents de l’API Telegram.
• Si les journaux incluent TypeError: fetch failed ou Network request for 'getUpdates' failed!, OpenClaw réessaie désormais ces erreurs comme des erreurs réseau récupérables.
• Pendant le démarrage de l’interrogation, OpenClaw réutilise la sonde de démarrage getMe réussie pour grammY afin que l’exécuteur n’ait pas besoin d’un second getMe avant le premier getUpdates.
• Si deleteWebhook échoue avec une erreur réseau transitoire pendant le démarrage de l’interrogation, OpenClaw passe à l’interrogation longue au lieu d’effectuer un autre appel de plan de contrôle avant interrogation. Un webhook encore actif apparaît comme un conflit getUpdates ; OpenClaw reconstruit alors le transport Telegram et réessaie le nettoyage du webhook.
• Si les sockets Telegram sont recyclés selon une cadence fixe courte, vérifiez si channels.telegram.timeoutSeconds est bas ; les clients de bot bornent les valeurs configurées sous les gardes de requêtes sortantes et getUpdates, mais les anciennes versions pouvaient abandonner chaque interrogation ou réponse lorsque cette valeur était définie sous ces gardes.
• Si les journaux incluent Polling stall detected, OpenClaw redémarre l’interrogation et reconstruit le transport Telegram après 120 secondes sans activité de l’interrogation longue terminée par défaut.
• openclaw channels status --probe et openclaw doctor avertissent lorsqu’un compte d’interrogation en cours d’exécution n’a pas terminé getUpdates après le délai de grâce de démarrage, lorsqu’un compte webhook en cours d’exécution n’a pas terminé setWebhook après le délai de grâce de démarrage, ou lorsque la dernière activité réussie du transport d’interrogation est obsolète.
• Augmentez channels.telegram.pollingStallThresholdMs uniquement lorsque les appels getUpdates de longue durée sont sains, mais que votre hôte signale encore à tort des redémarrages pour blocage de l’interrogation. Les blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou sortie TLS entre l’hôte et api.telegram.org.
• Telegram respecte également les variables d’environnement de proxy du processus pour le transport Bot API, notamment HTTP_PROXY, HTTPS_PROXY, ALL_PROXY et leurs variantes en minuscules. NO_PROXY / no_proxy peut toujours contourner api.telegram.org.
• Si le proxy géré par OpenClaw est configuré via OPENCLAW_PROXY_URL pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise aussi cette URL pour le transport Bot API.
• Sur les hôtes VPS avec une sortie directe/TLS instable, routez les appels API Telegram via channels.telegram.proxy :

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

• Node 22+ utilise par défaut autoSelectFamily=true (sauf WSL2). L’ordre des résultats DNS Telegram respecte OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, puis channels.telegram.network.dnsResultOrder, puis la valeur par défaut du processus comme NODE_OPTIONS=--dns-result-order=ipv4first ; si aucune ne s’applique, Node 22+ revient à ipv4first.
• Si votre hôte est WSL2 ou fonctionne explicitement mieux avec un comportement IPv4 uniquement, forcez la sélection de famille :

channels:
  telegram:
    network:
      autoSelectFamily: false

• Les réponses de plage de benchmark RFC 2544 (198.18.0.0/15) sont déjà autorisées pour les téléchargements de médias Telegram par défaut. Si un faux IP de confiance ou un proxy transparent réécrit api.telegram.org vers une autre adresse privée/interne/à usage spécial pendant les téléchargements de médias, vous pouvez activer le contournement propre à Telegram :

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La même activation est disponible par compte à channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si votre proxy résout les hôtes de médias Telegram en 198.18.x.x, laissez d’abord l’indicateur dangereux désactivé. Les médias Telegram autorisent déjà la plage de benchmark RFC 2544 par défaut.

• Remplacements d’environnement (temporaires) :
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Validez les réponses DNS :

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