--- read_when: - Travailler sur les fonctionnalités Telegram ou les Webhooks summary: Statut de prise en charge, capacités et configuration du robot Telegram title: Telegram x-i18n: generated_at: "2026-05-12T12:48:57Z" model: gpt-5.5 provider: openai source_hash: 185ac6051d3da2037b2727a6afca98bef946bc62c3f2b22cc9afe9831669297b source_path: channels/telegram.md workflow: 16 --- Prêt pour la production pour les DM et groupes de bot via grammY. Le mode par défaut est le long polling ; le mode webhook est facultatif. La politique de DM par défaut pour Telegram est l’appairage. Diagnostics intercanaux et guides de réparation. Modèles et exemples complets de configuration de canal. ## Configuration rapide Ouvrez Telegram et discutez avec **@BotFather** (vérifiez que l’identifiant est exactement `@BotFather`). Exécutez `/newbot`, suivez les invites et enregistrez le token. ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Solution de repli d’environnement : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement). Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le token dans la configuration/l’environnement, puis démarrez le Gateway. ```bash openclaw gateway openclaw pairing list telegram openclaw pairing approve telegram ``` Les codes d’appairage expirent au bout de 1 heure. Ajoutez le bot à votre groupe, puis récupérez les deux ID dont l’accès au groupe a besoin : - votre ID utilisateur Telegram, utilisé dans `allowFrom` / `groupAllowFrom` - l’ID de discussion du groupe Telegram, utilisé comme clé sous `channels.telegram.groups` Pour une première configuration, récupérez l’ID de discussion du groupe depuis `openclaw logs --follow`, un bot d’ID transféré ou `getUpdates` de la Bot API. Une fois le groupe autorisé, `/whoami@` peut confirmer les ID d’utilisateur et de groupe. Les ID de supergroupes Telegram négatifs qui commencent par `-100` sont des ID de discussion de groupe. Placez-les sous `channels.telegram.groups`, pas sous `groupAllowFrom`. L’ordre de résolution du token tient compte du compte. En pratique, les valeurs de configuration prévalent sur la solution de repli d’environnement, et `TELEGRAM_BOT_TOKEN` ne s’applique qu’au compte par défaut. ## Paramètres côté Telegram Les bots Telegram utilisent par défaut le **mode de confidentialité**, qui limite les messages de groupe qu’ils reçoivent. Si le bot doit voir tous les messages de groupe, vous pouvez soit : - désactiver le mode de confidentialité via `/setprivacy`, soit - faire du bot un administrateur du groupe. Lorsque vous changez le mode de confidentialité, retirez puis rajoutez le bot dans chaque groupe afin que Telegram applique le changement. Le statut d’administrateur est contrôlé dans les paramètres du groupe Telegram. Les bots administrateurs reçoivent tous les messages de groupe, ce qui est utile pour un comportement de groupe toujours actif. - `/setjoingroups` pour autoriser/refuser les ajouts à des groupes - `/setprivacy` pour le comportement de visibilité dans les groupes ## Contrôle d’accès et activation `channels.telegram.dmPolicy` contrôle l’accès par message direct : - `pairing` (par défaut) - `allowlist` (nécessite au moins un ID d’expéditeur dans `allowFrom`) - `open` (nécessite que `allowFrom` inclue `"*"`) - `disabled` `dmPolicy: "open"` avec `allowFrom: ["*"]` permet à tout compte Telegram qui trouve ou devine le nom d’utilisateur du bot de commander le bot. Utilisez-le uniquement pour des bots volontairement publics avec des outils strictement restreints ; les bots à propriétaire unique doivent utiliser `allowlist` avec des ID utilisateur numériques. `channels.telegram.allowFrom` accepte les ID utilisateur Telegram numériques. Les préfixes `telegram:` / `tg:` sont acceptés et normalisés. Dans les configurations multicomptes, un `channels.telegram.allowFrom` restrictif de niveau supérieur est traité comme une limite de sécurité : les entrées `allowFrom: ["*"]` au niveau du compte ne rendent pas ce compte public, sauf si la allowlist effective du compte contient toujours un joker explicite après fusion. `dmPolicy: "allowlist"` avec `allowFrom` vide bloque tous les DM et est rejeté par la validation de configuration. La configuration demande uniquement des ID utilisateur numériques. Si vous avez effectué une mise à niveau et que votre configuration contient des entrées de allowlist `@username`, exécutez `openclaw doctor --fix` pour les résoudre (au mieux ; nécessite un token de bot Telegram). Si vous vous appuyiez auparavant sur des fichiers de allowlist du magasin d’appairage, `openclaw doctor --fix` peut récupérer les entrées dans `channels.telegram.allowFrom` dans les flux allowlist (par exemple lorsque `dmPolicy: "allowlist"` n’a pas encore d’ID explicites). Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID numériques `allowFrom` explicites afin de conserver durablement la politique d’accès dans la configuration (au lieu de dépendre d’approbations d’appairage précédentes). Confusion fréquente : l’approbation d’appairage en DM ne signifie pas « cet expéditeur est autorisé partout ». L’appairage accorde l’accès aux DM. Si aucun propriétaire de commandes n’existe encore, le premier appairage approuvé définit aussi `commands.ownerAllowFrom` afin que les commandes réservées au propriétaire et les approbations d’exécution aient un compte opérateur explicite. L’autorisation de l’expéditeur dans les groupes provient toujours de allowlists de configuration explicites. Si vous voulez « je suis autorisé une fois, et les DM comme les commandes de groupe fonctionnent », placez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom` ; pour les commandes réservées au propriétaire, assurez-vous que `commands.ownerAllowFrom` contient `telegram:`. ### Trouver votre ID utilisateur Telegram Plus sûr (aucun bot tiers) : 1. Envoyez un DM à votre bot. 2. Exécutez `openclaw logs --follow`. 3. Lisez `from.id`. Méthode officielle de la Bot API : ```bash curl "https://api.telegram.org/bot/getUpdates" ``` Méthode tierce (moins privée) : `@userinfobot` ou `@getidsbot`. Deux contrôles s’appliquent ensemble : 1. **Quels groupes sont autorisés** (`channels.telegram.groups`) - aucune configuration `groups` : - avec `groupPolicy: "open"` : n’importe quel groupe peut passer les contrôles d’ID de groupe - avec `groupPolicy: "allowlist"` (par défaut) : les groupes sont bloqués jusqu’à ce que vous ajoutiez des entrées `groups` (ou `"*"`) - `groups` configuré : agit comme une allowlist (ID explicites ou `"*"`) 2. **Quels expéditeurs sont autorisés dans les groupes** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (par défaut) - `disabled` `groupAllowFrom` est utilisé pour le filtrage des expéditeurs de groupe. S’il n’est pas défini, Telegram se rabat sur `allowFrom`. Les entrées `groupAllowFrom` doivent être des ID utilisateur Telegram numériques (les préfixes `telegram:` / `tg:` sont normalisés). Ne placez pas d’ID de discussion de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de discussion négatifs doivent être sous `channels.telegram.groups`. Les entrées non numériques sont ignorées pour l’autorisation des expéditeurs. Limite de sécurité (`2026.2.25+`) : l’authentification des expéditeurs de groupe n’hérite **pas** des approbations du magasin d’appairage de DM. L’appairage reste limité aux DM. Pour les groupes, définissez `groupAllowFrom` ou `allowFrom` par groupe/par sujet. Si `groupAllowFrom` n’est pas défini, Telegram se rabat sur `allowFrom` dans la configuration, pas sur le magasin d’appairage. Modèle pratique pour les bots à propriétaire unique : définissez votre ID utilisateur dans `channels.telegram.allowFrom`, laissez `groupAllowFrom` non défini et autorisez les groupes cibles sous `channels.telegram.groups`. Note d’exécution : si `channels.telegram` est totalement absent, l’exécution utilise par défaut `groupPolicy="allowlist"` en mode fermé, sauf si `channels.defaults.groupPolicy` est explicitement défini. Configuration de groupe réservée au propriétaire : ```json5 { channels: { telegram: { enabled: true, dmPolicy: "pairing", allowFrom: [""], groupPolicy: "allowlist", groups: { "": { requireMention: true, }, }, }, }, } ``` Testez-le depuis le groupe avec `@ ping`. Les messages de groupe ordinaires ne déclenchent pas le bot tant que `requireMention: true`. Exemple : autoriser n’importe quel membre dans un groupe spécifique : ```json5 { channels: { telegram: { groups: { "-1001234567890": { groupPolicy: "open", requireMention: false, }, }, }, }, } ``` Exemple : autoriser uniquement des utilisateurs spécifiques dans un groupe spécifique : ```json5 { channels: { telegram: { groups: { "-1001234567890": { requireMention: true, allowFrom: ["8734062810", "745123456"], }, }, }, }, } ``` Erreur fréquente : `groupAllowFrom` n’est pas une allowlist de groupes Telegram. - Placez les ID de discussion de groupe ou de supergroupe Telegram négatifs comme `-1001234567890` sous `channels.telegram.groups`. - Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes d’un groupe autorisé qui peuvent déclencher le bot. - Utilisez `groupAllowFrom: ["*"]` uniquement lorsque vous voulez que tout membre d’un groupe autorisé puisse parler au bot. Les réponses de groupe nécessitent une mention par défaut. La mention peut provenir de : - une mention native `@botusername`, ou - des modèles de mention dans : - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` Bascules de commande au niveau de la session : - `/activation always` - `/activation mention` Elles ne mettent à jour que l’état de la session. Utilisez la configuration pour la persistance. Exemple de configuration persistante : ```json5 { channels: { telegram: { groups: { "*": { requireMention: false }, }, }, }, } ``` Obtenir l’ID de discussion du groupe : - transférez un message de groupe à `@userinfobot` / `@getidsbot` - ou lisez `chat.id` depuis `openclaw logs --follow` - ou inspectez `getUpdates` de la Bot API - une fois le groupe autorisé, exécutez `/whoami@` si les commandes natives sont activées ## Comportement à l’exécution - Telegram appartient au processus Gateway. - Le routage est déterministe : les messages entrants Telegram répondent vers Telegram (le modèle ne choisit pas les canaux). - Les messages entrants sont normalisés dans l’enveloppe de canal partagée avec des métadonnées de réponse, des espaces réservés de média et un contexte de chaîne de réponses persistant pour les réponses Telegram que le Gateway a observées. - Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent `:topic:` pour maintenir les sujets isolés. - Les messages DM peuvent porter `message_thread_id` ; OpenClaw conserve l’ID de fil pour les réponses mais garde les DM sur la session plate par défaut. Configurez `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` ou une configuration de sujet correspondante lorsque vous voulez intentionnellement isoler les sessions de sujet en DM. - Le long polling utilise le runner grammY avec séquencement par discussion/par fil. La concurrence globale du récepteur du runner utilise `agents.defaults.maxConcurrent`. - Le long polling est protégé dans chaque processus Gateway afin qu’un seul poller actif puisse utiliser un token de bot à la fois. Si vous voyez encore des conflits `getUpdates` 409, un autre Gateway OpenClaw, script ou poller externe utilise probablement le même token. - Les redémarrages du watchdog de long polling se déclenchent par défaut après 120 secondes sans vivacité `getUpdates` terminée. Augmentez `channels.telegram.pollingStallThresholdMs` uniquement si votre déploiement voit encore de faux redémarrages pour blocage de polling pendant un travail long. La valeur est en millisecondes et est autorisée de `30000` à `600000` ; les remplacements par compte sont pris en charge. - La Bot API Telegram ne prend pas en charge les accusés de lecture (`sendReadReceipts` ne s’applique pas). ## Référence des fonctionnalités OpenClaw peut diffuser des réponses partielles en temps réel : - discussions directes : message d’aperçu + `editMessageText` - groupes/sujets : message d’aperçu + `editMessageText` Exigence : - `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` Les mises à jour d’aperçu de progression d’outil sont les courtes lignes de statut affichées pendant l’exécution des outils, par exemple l’exécution de commandes, la lecture de fichiers, les mises à jour de planification ou les résumés de patch. Telegram les garde activées par défaut pour correspondre au comportement OpenClaw publié à partir de `v2026.4.22`. Pour conserver l’aperçu modifié pour le texte de réponse tout en masquant les lignes de progression d’outil, définissez : ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "toolProgress": false } } } } } ``` Pour garder la progression d’outil visible tout en masquant le texte de commande/exécution, définissez : ```json { "channels": { "telegram": { "streaming": { "mode": "partial", "preview": { "commandText": "status" } } } } } ``` Utilisez le mode `progress` lorsque vous voulez une progression d’outil visible sans modifier la réponse finale dans ce même message. Placez la politique de texte de commande sous `streaming.progress` : ```json { "channels": { "telegram": { "streaming": { "mode": "progress", "progress": { "toolProgress": true, "commandText": "status" } } } } } ``` Utilisez `streaming.mode: "off"` uniquement lorsque vous voulez une livraison finale seule : les modifications d’aperçu Telegram sont désactivées et le bavardage générique d’outil/de progression est supprimé au lieu d’être envoyé comme messages de statut autonomes. Les invites d’approbation, les charges utiles multimédias et les erreurs passent toujours par la livraison finale normale. Utilisez `streaming.preview.toolProgress: false` lorsque vous voulez seulement conserver les modifications d’aperçu de réponse tout en masquant les lignes de statut de progression d’outil. Les réponses Telegram à citation sélectionnée sont l’exception. Lorsque `replyToMode` vaut `"first"`, `"all"` ou `"batched"` et que le message entrant inclut le texte d’une citation sélectionnée, OpenClaw envoie la réponse finale via le chemin natif de réponse avec citation de Telegram au lieu de modifier l’aperçu de réponse ; `streaming.preview.toolProgress` ne peut donc pas afficher les courtes lignes de statut pour ce tour. Les réponses au message courant sans texte de citation sélectionnée conservent toujours le streaming d’aperçu. Définissez `replyToMode: "off"` lorsque la visibilité de la progression d’outil importe davantage que les réponses natives avec citation, ou définissez `streaming.preview.toolProgress: false` pour accepter le compromis. Pour les réponses en texte seul : - 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 Pour les réponses complexes (par exemple des charges utiles multimédias), OpenClaw revient à la livraison finale normale, puis nettoie le message d’aperçu. Le streaming d’aperçu est distinct du streaming par blocs. Lorsque le streaming par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter un double streaming. Flux de raisonnement propre à Telegram : - `/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 sortant utilise Telegram `parse_mode: "HTML"`. - 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. Les aperçus de liens sont activés par défaut et peuvent être désactivés avec `channels.telegram.linkPreview: false`. L’enregistrement du menu de commandes Telegram est géré au démarrage avec `setMyCommands`. Valeurs par défaut des commandes natives : - `commands.native: "auto"` active les commandes natives pour Telegram Ajoutez des entrées de menu de commandes personnalisées : ```json5 { channels: { telegram: { customCommands: [ { command: "backup", description: "Git backup" }, { command: "generate", description: "Create an image" }, ], }, }, } ``` Règles : - 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 Notes : - 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 Si les commandes natives sont désactivées, les commandes intégrées sont supprimées. Les commandes personnalisées/de Plugin peuvent encore s’enregistrer si elles sont configurées. Échecs courants de configuration : - `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`. `apiRoot` doit être uniquement la racine de l’API Bot, et `openclaw doctor --fix` supprime un suffixe `/bot` 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`) Lorsque le Plugin `device-pair` est installé : 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 ` 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 Le code de configuration contient un jeton d’amorçage à durée de vie courte. Le transfert d’amorçage intégré conserve le jeton du nœud principal à `scopes: []` ; tout jeton d’opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de portée d’amorçage sont préfixées par rôle, de sorte que cette liste d’autorisation d’opérateur ne satisfait que les demandes d’opérateur ; les rôles non opérateur ont toujours besoin de portées sous leur propre préfixe de rôle. Si un appareil réessaie avec des détails d’authentification modifiés (par exemple rôle/portées/clé publique), la demande en attente précédente est remplacée et la nouvelle demande utilise un `requestId` différent. Relancez `/pair pending` avant d’approuver. Plus de détails : [Appairage](/fr/channels/pairing#pair-via-telegram-recommended-for-ios). Configurez la portée du clavier en ligne : ```json5 { channels: { telegram: { capabilities: { inlineButtons: "allowlist", }, }, }, } ``` Remplacement par compte : ```json5 { channels: { telegram: { accounts: { main: { capabilities: { inlineButtons: "allowlist", }, }, }, }, }, } ``` Portées : - `off` - `dm` - `group` - `all` - `allowlist` (par défaut) L’ancien `capabilities: ["inlineButtons"]` est mappé vers `inlineButtons: "all"`. Exemple d’action de message : ```json5 { 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" }], ], } ``` Les clics de rappel sont transmis à l’agent sous forme de texte : `callback_data: ` Les actions d’outil Telegram incluent : - `sendMessage` (`to`, `content`, optionnel `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, optionnel `iconColor`, `iconCustomEmojiId`) Les actions de message de canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). Contrôles de restriction : - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (par défaut : désactivé) Note : `edit` et `topic-create` sont actuellement activés par défaut et n’ont pas de bascules `channels.telegram.actions.*` distinctes. Les envois à l’exécution utilisent l’instantané de configuration/secrets actif (démarrage/rechargement), de sorte que les chemins d’action n’effectuent pas de nouvelle résolution SecretRef ponctuelle à chaque envoi. Sémantique de suppression des réactions : [/tools/reactions](/fr/tools/reactions) Telegram prend en charge des balises explicites de fil de réponse dans la sortie générée : - `[[reply_to_current]]` répond au message déclencheur - `[[reply_to:]]` répond à un ID de message Telegram spécifique `channels.telegram.replyToMode` contrôle le traitement : - `off` (par défaut) - `first` - `all` Lorsque le fil de réponse est activé et que le texte ou la légende Telegram d’origine est disponible, OpenClaw inclut automatiquement un extrait de citation Telegram natif. Telegram limite le texte de citation natif à 1024 unités de code UTF-16 ; les messages plus longs sont donc cités depuis le début et basculent vers une réponse simple si Telegram rejette la citation. Note : `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` restent honorées. Supergroupes de forum : - les clés de session de sujet ajoutent `:topic:` - les réponses et l’indication de saisie ciblent le fil du sujet - chemin de configuration du sujet : `channels.telegram.groups..topics.` Cas particulier du sujet général (`threadId=1`) : - les envois de message omettent `message_thread_id` (Telegram rejette `sendMessage(...thread_id=1)`) - les actions de saisie incluent toujours `message_thread_id` Héritage des sujets : les entrées de sujet héritent des paramètres de groupe sauf remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` est propre au sujet et n’hérite pas des valeurs par défaut du groupe. **Routage d’agent par sujet** : chaque sujet peut être routé vers un agent différent en définissant `agentId` dans la configuration du sujet. Cela donne à chaque sujet son propre espace de travail, sa mémoire et sa session isolés. Exemple : ```json5 { 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 } } } } } } ``` Chaque sujet possède alors sa propre clé de session : `agent:zu:telegram:group:-1001234567890:topic:3` **Liaison persistante de sujet ACP** : les sujets de forum peuvent épingler des sessions de harnais ACP via des liaisons ACP typées de premier niveau (`bindings[]` avec `type: "acp"` et `match.channel: "telegram"`, `peer.kind: "group"`, et un ID qualifié par sujet comme `-1001234567890:topic:42`). Actuellement limité aux sujets de forum dans les groupes/supergroupes. Consultez [Agents ACP](/fr/tools/acp-agents). **Création ACP liée au fil depuis le chat** : `/acp spawn --thread here|auto` lie le sujet actuel à une nouvelle session ACP ; les messages suivants y sont routés directement. OpenClaw épingle la confirmation de création dans le sujet. Nécessite que `channels.telegram.threadBindings.spawnSessions` reste activé (par défaut : `true`). Le contexte de modèle expose `MessageThreadId` et `IsForum`. Les chats DM avec `message_thread_id` conservent par défaut le routage DM et les métadonnées de réponse sur des sessions plates ; ils n’utilisent des clés de session tenant compte des fils que lorsqu’ils sont configurés avec `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou une configuration de sujet correspondante. Utilisez `channels.telegram.dm.threadReplies` de premier niveau pour la valeur par défaut du compte, ou `direct..threadReplies` pour un DM. ### Messages audio Telegram distingue les notes vocales des fichiers 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. Exemple d’action de message : ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/voice.ogg", asVoice: true, } ``` ### Messages vidéo Telegram distingue les fichiers vidéo des notes vidéo. Exemple d’action de message : ```json5 { action: "send", channel: "telegram", to: "123456789", media: "https://example.com/video.mp4", asVideoNote: true, } ``` Les notes vidéo ne prennent pas en charge les légendes ; le texte de message fourni est envoyé séparément. ### Stickers Gestion des stickers entrants : - WEBP statique : téléchargé et traité (placeholder ``) - TGS animé : ignoré - WEBM vidéo : ignoré Champs de contexte de sticker : - `Sticker.emoji` - `Sticker.setName` - `Sticker.fileId` - `Sticker.fileUniqueId` - `Sticker.cachedDescription` Fichier de cache des stickers : - `~/.openclaw/telegram/sticker-cache.json` Les stickers sont décrits une fois (lorsque c’est possible) et mis en cache pour réduire les appels répétés à la vision. Activer les actions de sticker : ```json5 { channels: { telegram: { actions: { sticker: true, }, }, }, } ``` Action d’envoi de sticker : ```json5 { action: "sticker", channel: "telegram", to: "123456789", fileId: "CAACAgIAAxkBAAI...", } ``` Rechercher des stickers en cache : ```json5 { action: "sticker-search", channel: "telegram", query: "cat waving", limit: 5, } ``` Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (distinctes des charges utiles de message). Lorsque cette option est activée, OpenClaw met en file des événements système comme : - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` Configuration : - `channels.telegram.reactionNotifications` : `off | own | all` (par défaut : `own`) - `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` (par défaut : `minimal`) Remarques : - `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 `allowed_updates` pour polling/Webhook inclut automatiquement `message_reaction`. `ackReaction` envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant. Ordre de résolution : - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀") Remarques : - Telegram attend un emoji Unicode (par exemple "👀"). - Utilisez `""` pour désactiver la réaction pour un canal ou un compte. Les écritures de configuration de canal sont activées par défaut (`configWrites !== false`). Les écritures déclenchées par Telegram incluent : - 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) Désactiver : ```json5 { channels: { telegram: { configWrites: false, }, }, } ``` La valeur par défaut est le long polling. Pour le mode Webhook, définissez `channels.telegram.webhookUrl` et `channels.telegram.webhookSecret` ; paramètres facultatifs `webhookPath`, `webhookHost`, `webhookPort` (valeurs par défaut `/telegram-webhook`, `127.0.0.1`, `8787`). En mode long-polling, OpenClaw ne persiste son filigrane de redémarrage qu’après la distribution réussie d’une mise à jour. Si un gestionnaire échoue, cette mise à jour reste réessayable dans le même processus et n’est pas écrite comme terminée pour la déduplication au redémarrage. L’écouteur local se lie à `127.0.0.1:8787`. Pour une entrée publique, placez un proxy inverse devant le port local ou définissez volontairement `webhookHost: "0.0.0.0"`. Le mode Webhook valide les gardes de requête, le jeton secret Telegram et le corps JSON avant de renvoyer `200` à Telegram. OpenClaw traite ensuite la mise à jour de façon asynchrone via les mêmes files bot par chat/par sujet que celles utilisées par le long polling, afin que les tours d’agent lents ne retiennent pas l’ACK de livraison de Telegram. - 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[""].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. Les cibles d’envoi CLI et de l’outil de message peuvent être un ID de chat numérique, un nom d’utilisateur ou une cible de sujet de forum : ```bash 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" ``` Les polls Telegram utilisent `openclaw message poll` et prennent en charge les sujets de forum : ```bash 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 ``` Indicateurs de poll propres à Telegram : - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - `--thread-id` pour les sujets de forum (ou utilisez une cible `:topic:`) L’envoi Telegram prend aussi en charge : - `--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 Contrôle des actions : - `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 Telegram prend en charge les approbations exec dans les DM des approbateurs et peut facultativement publier des invites dans le chat ou le sujet d’origine. Les approbateurs doivent être des ID d’utilisateurs Telegram numériques. Chemin de configuration : - `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` `channels.telegram.allowFrom`, `groupAllowFrom` et `defaultTo` contrôlent qui peut parler au bot et où il envoie les réponses normales. Ils ne font pas de quelqu’un un approbateur exec. Le premier appairage DM approuvé amorce `commands.ownerAllowFrom` lorsqu’aucun propriétaire de commandes n’existe encore, de sorte que la configuration à propriétaire unique fonctionne toujours sans dupliquer les ID sous `execApprovals.approvers`. La livraison au canal affiche le texte de la commande dans le chat ; n’activez `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw conserve le sujet pour l’invite d’approbation et le suivi. Les approbations exec expirent par défaut après 30 minutes. Les boutons d’approbation en ligne nécessitent aussi que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`). Les ID d’approbation préfixés par `plugin:` sont résolus via les approbations de Plugin ; les autres sont d’abord résolus via les approbations exec. Consultez [Approbations exec](/fr/tools/exec-approvals). ## Contrôles des réponses d’erreur Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut répondre avec le texte de l’erreur ou le supprimer. Deux clés de configuration contrôlent ce comportement : | Clé | Valeurs | Par défaut | Description | | ----------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial au chat. `silent` supprime entièrement les réponses d’erreur. | | `channels.telegram.errorCooldownMs` | nombre (ms) | `60000` | Temps minimal entre les réponses d’erreur au même chat. Évite le spam d’erreurs pendant les pannes. | Les remplacements par compte, par groupe et par sujet sont pris en charge (même héritage que les autres clés de configuration Telegram). ```json5 { channels: { telegram: { errorPolicy: "reply", errorCooldownMs: 120000, groups: { "-1001234567890": { errorPolicy: "silent", // suppress errors in this group }, }, }, }, } ``` ## Dépannage - 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..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` : ```yaml channels: telegram: proxy: socks5://:@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 : ```yaml 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 : ```yaml channels: telegram: network: dangerouslyAllowPrivateNetwork: true ``` - La même activation est disponible par compte à `channels.telegram.accounts..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. `channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections SSRF des médias Telegram. Utilisez-le uniquement pour des environnements de proxy de confiance contrôlés par l’opérateur, comme le routage faux IP de Clash, Mihomo ou Surge, lorsqu’ils synthétisent des réponses privées ou à usage spécial en dehors de la plage de benchmark RFC 2544. Laissez-le désactivé pour un accès Telegram normal à Internet public. - 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 : ```bash dig +short api.telegram.org A dig +short api.telegram.org AAAA ``` Aide supplémentaire : [Dépannage des canaux](/fr/channels/troubleshooting). ## Référence de configuration Référence principale : [Référence de configuration - Telegram](/fr/gateway/config-channels#telegram). - démarrage/authentification : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier ordinaire ; les liens symboliques sont rejetés) - contrôle d’accès : `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de premier niveau (`type: "acp"`) - approbations exec : `execApprovals`, `accounts.*.execApprovals` - commande/menu : `commands.native`, `commands.nativeSkills`, `customCommands` - fils/réponses : `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - streaming : `streaming` (aperçu), `streaming.preview.toolProgress`, `blockStreaming` - formatage/livraison : `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - médias/réseau : `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - racine d’API personnalisée : `apiRoot` (racine Bot API uniquement ; n’incluez pas `/bot`) - webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - actions/capacités : `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - réactions : `reactionNotifications`, `reactionLevel` - erreurs : `errorPolicy`, `errorCooldownMs` - écritures/historique : `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` Priorité multi-compte : lorsque deux ID de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) pour rendre le routage par défaut explicite. Sinon, OpenClaw revient au premier ID de compte normalisé et `openclaw doctor` avertit. Les comptes nommés héritent de `channels.telegram.allowFrom` / `groupAllowFrom`, mais pas des valeurs `accounts.default.*`. ## Connexe Appariez un utilisateur Telegram au gateway. Comportement de la liste d’autorisation des groupes et sujets. Routez les messages entrants vers les agents. Modèle de menace et durcissement. Associez les groupes et les sujets aux agents. Diagnostics intercanaux.