Aller au contenu
OpenClaw Docs

TelegramTelegram

Prêt pour la production pour les DMs de bot et les groupes via grammY. Le polling long est le mode par défaut ; le mode webhook est facultatif.

Pairing

La stratégie DM par défaut pour Telegram est l’appariement.

Channel troubleshooting

Manuels de diagnostic et de réparation multi-canaux.

GatewayGateway configuration

Modèles et exemples complets de configuration de canal.

Configuration rapide

Section intitulée « Configuration rapide »

  1. Create the bot token in BotFather

    Ouvrez Telegram et chattez avec @BotFather (vérifiez que le pseudonyme est exactement @BotFather).

    Exécutez /newbot, suivez les instructions et enregistrez le jeton.

  2. Configure token and DM policy

    {
      channels: {
        telegram: {
          enabled: true,
          botToken: "123:abc",
          dmPolicy: "pairing",
          groups: { "*": { requireMention: true } },
        },
      },
    }
    Fallback Env : `TELEGRAM_BOT_TOKEN=...`Telegram (compte par défaut uniquement).
    Telegram n'utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans config/env, puis démarrez la passerelle.

  3. Start gateway and approve first DM

    Fenêtre de terminal
    openclaw gateway
    openclaw pairing list telegram
    openclaw pairing approve telegram
        Les codes d'appariement expirent après 1 heure.

Paramètres côté Telegram

Section intitulée « Paramètres côté Telegram »
Mode de confidentialité et visibilité du groupe

Les bots Telegram sont par défaut en Mode de confidentialité (Privacy Mode), ce qui limite les messages de groupe qu’ils reçoivent.

Si le bot doit voir tous les messages du groupe, soit :

  • désactivez le mode de confidentialité via /setprivacy, ou
  • rendez le bot administrateur du groupe.

Lorsque vous basculez le mode de confidentialité, retirez et ajoutez à nouveau le bot dans chaque groupe pour que Telegram applique le changement.

Autorisations de groupe

Le statut d’administrateur est contrôlé dans les paramètres de groupe Telegram.

Les bots administrateurs reçoivent tous les messages du groupe, ce qui est utile pour un comportement de groupe toujours actif.

Helpful BotFather toggles
  • /setjoingroups pour autoriser/refuser les ajouts aux groupes
  • /setprivacy pour le comportement de visibilité du groupe

Contrôle d’accès et activation

Section intitulée « Contrôle d’accès et activation »

channels.telegram.dmPolicy contrôle l’accès aux messages directs :

  • pairing (par défaut)
  • allowlist (requiert au moins un ID d’expéditeur dans allowFrom)
  • open (requiert que allowFrom inclue "*")
  • disabled

dmPolicy: "open" avec allowFrom: ["*"] permet à n’importe quel compte Telegram qui trouve ou devine la commande du nom d’utilisateur du bot de commander le bot. Utilisez-le uniquement pour les bots intentionnellement publics avec des outils strictement restreints ; les bots à un seul propriétaire doivent utiliser allowlist avec des ID utilisateur numériques.

channels.telegram.allowFrom accepte les ID utilisateur numériques Telegram. Les préfixes telegram: / tg: sont acceptés et normalisés. Dans les configurations multi-comptes, un channels.telegram.allowFrom de niveau supérieur restrictif 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 liste d’autorisation de compte effective contient toujours un caractère générique explicite après la fusion. dmPolicy: "allowlist" avec un allowFrom vide bloque tous les DMs et est rejeté par la validation de configuration. Le configuration demande uniquement des ID utilisateur numériques. Si vous avez effectué une mise à niveau et que votre configuration contient des entrées de liste d’autorisation @username, exécutez openclaw doctor --fix pour les résoudre (au mieux ; nécessite un jeton de bot Telegram). Si vous dépendiez précédemment de fichiers de liste d’autorisation de magasin d’appariement, openclaw doctor --fix peut récupérer les entrées dans channels.telegram.allowFrom dans les flux de liste d’autorisation (par exemple lorsque dmPolicy: "allowlist" n’a pas encore d’ID explicites).

Pour les bots à un seul propriétaire, préférez dmPolicy: "allowlist" avec des ID numériques explicites allowFrom pour garder la politique d’accès durable dans la configuration (au lieu de dépendre des approbations d’appariement précédentes).

Confusion courante : l’approbation d’appariement DM ne signifie pas « cet expéditeur est autorisé partout ». L’appariement accorde l’accès DM. Si aucun propriétaire de commande n’existe encore, le premier appariement approuvé définit également commands.ownerAllowFrom afin que les commandes réservées au propriétaire et les approbations exec aient un compte d’opérateur explicite. L’autorisation de l’expéditeur de groupe provient toujours des listes d’autorisation de configuration explicites. Si vous souhaitez « Je suis autorisé une fois et que les DMs et les commandes de groupe fonctionnent », mettez votre ID utilisateur numérique Telegram 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 (pas de bot tiers) :


1. Envoyez un DM à votre bot.
2. Exécutez `openclaw logs --follow`.
3. Lisez `from.id`.


Méthode officielle de Bot API :
Fenêtre de terminal
curl "https://api.telegram.org/bot

/getUpdates”

    Méthode tierce (moins privée) : `@userinfobot` ou `@getidsbot`.

Comportement à l’exécution

Section intitulée « Comportement à l’exécution »
  • Telegram appartient au processus de passerelle.
  • Le routage est déterministe : les réponses entrantes Telegram reviennent 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 pour les médias et un contexte de chaîne de réponse persistant pour les réponses Telegram que la passerelle a observées.
  • Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent :topic:<threadId> pour garder les sujets isolés.
  • Les messages DM peuvent transporter message_thread_idOpenClawTelegram ; OpenClaw le conserve pour les réponses. Les sessions de sujet DM ne se divisent que lorsque le getMe Telegram signale has_topics_enabled: true pour le bot ; sinon, les DMs restent sur la session plate.
  • Le long polling utilise le runner grammY avec un séquençage par chat par fil. La concurrence globale du sink du runner utilise agents.defaults.maxConcurrent.
  • Le démarrage multi-compte limite les sondes simultanées getMe Telegram afin que les grandes flottes de bots n’éparpillent pas chaque sonde de compte en même temps.
  • Le long polling est protégé à l’intérieur de chaque processus de passerelle afin qu’un seul sondeur actif puisse utiliser un jeton de bot à la fois. Si vous voyez encore des conflits getUpdates 409, une autre passerelle OpenClaw, un script ou un sondeur externe utilise probablement le même jeton.
  • Par défaut, les redémarrages du chien de garde de polling long se déclenchent après 120 secondes sans getUpdates de liveness terminée. Augmentez channels.telegram.pollingStallThresholdMs uniquement si votre déploiement rencontre toujours des redémarrages intempestifs dus à un arrêt du polling pendant des tâches de longue durée. La valeur est en millisecondes et est autorisée de 30000 à 600000 ; les remplacements par compte sont pris en charge.
  • L’Telegram Bot API ne prend pas en charge les accusés de réception (sendReadReceipts ne s’applique pas).

Référence des fonctionnalités

Section intitulée « Référence des fonctionnalités »
Aperçu en direct (modifications de message)

OpenClaw peut diffuser des réponses partielles en temps réel :

  • chats directs : message d’aperçu + editMessageText
  • groupes/sujets : message d’aperçu + editMessageText
  • progression de l’outil en chat direct : aperçu facultatif du statut natif sendMessageDraft lorsque activé et pris en charge

Conditions requises :

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

Les mises à jour d’aperçu de la progression de l’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, les résumés de correctifs ou le texte de préambule/commentaire Codex en mode serveur d’application Codex. Telegram les active par défaut pour correspondre au comportement publié de OpenClaw à partir de v2026.4.22 et des versions ultérieures.

Les chats directs peuvent utiliser les brouillons natifs Telegram pour ces lignes de progression d’outil sans rendre persistantes les discussions de l’outil dans l’historique du chat. Les brouillons natifs s’arrêtent avant le début du texte de réponse ; les réponses finales restent sur le chemin de livraison persistant normal. Cette voie est désactivée par défaut et doit d’abord être réservée aux ID de DM de confiance :

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "nativeToolProgress": true,
          "nativeToolProgressAllowFrom": ["123456789"]
        }
      }
    }
  }
}

Pour conserver l’aperçu modifié pour le texte de réponse mais masquer les lignes de progression de l’outil, définissez :

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

Pour garder la progression de l’outil visible mais masquer le texte de commande/exec, définissez :

{
  "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 le même message. Placez la stratégie de texte de commande sous streaming.progress :

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Utilisez streaming.mode: "off" uniquement lorsque vous souhaitez une livraison finale uniquement : les modifications d’aperçu Telegram sont désactivées et les discussions génériques d’outil/progression sont supprimées au lieu d’être envoyées sous forme de 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 souhaitez uniquement conserver les modifications d’aperçu de réponse tout en masquant les lignes de statut de progression de l’outil.

Pour les réponses texte uniquement :

  • aperçus DM/groupe/sujet courts : OpenClaw conserve le même message d’aperçu et effectue la modification finale sur place
  • les finales texte longues qui sont divisées en plusieurs messages Telegram réutilisent l’aperçu existant comme premier bloc final lorsque cela est possible, puis envoient uniquement 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 en réponse
  • si la modification finale échoue avant que le texte terminé ne soit confirmé, OpenClaw utilise la livraison finale normale et nettoie l’aperçu périmé

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 flux d’aperçu est distinct du flux de blocs. Lorsque le flux de blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter le double flux.

Comportement du flux de raisonnement :

  • /reasoning stream utilise le chemin d’aperçu de raisonnement d’un channel pris en charge ; sur Telegram, il diffuse le raisonnement dans 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
Mise en forme et repli HTML

Le texte sortant utilise Telegram parse_mode: "HTML"TelegramTelegramTelegramOpenClaw.

  • Le texte style Markdown est rendu en HTML sécurisé pour Telegram.
  • Les balises HTML prises en charge par Telegram sont conservé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.
Commandes natives et commandes personnalisées
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


Ajouter des entrées de menu de commandes personnalisées :
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}
Règles :


- les noms sont normalisés (suppression du `/` de tête, 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 consignés


Notes :


- les commandes personnalisées sont des entrées de menu uniquement ; elles n'implémentent pas automatiquement le comportement
- les commandes de plugin/skill peuvent toujours fonctionner lorsqu'elles sont tapées, 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 toujours s'enregistrer si elles sont configurées.


Échecs courants de la configuration :


- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram débordait encore après la réduction ; réduisez les commandes de plugin/skill/personnalisées ou désactivez `channels.telegram.commands.native`.
- `deleteWebhook`, `deleteMyCommands`, ou `setMyCommands` échouant avec `404: Not Found` alors que les commandes curl directes de Bot API fonctionnent peut signifier que `channels.telegram.apiRoot` a été défini sur le point de terminaison `/bot

complet.apiRootdoit être uniquement la racine de Bot API, etopenclaw doctor —fixsupprime un/bot

de fin accidentel. -getMe returned 401signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jourbotToken, tokenFile, ou TELEGRAM_BOT_TOKENavec le jeton actuel de BotFather ; OpenClaw s'arrête avant le polling, donc cela n'est pas signalé comme un échec de nettoyage de webhook. -setMyCommands failedavec des erreurs réseau/récupération signifie généralement que le DNS/HTTPS sortant versapi.telegram.org` est bloqué.

### Commandes d'appairage d'appareil (plugin `device-pair`)


Lorsque le plugin `device-pair` est installé :


1. `/pair` génère le code de configuration
2. collez le code dans l'application iOS
3. `/pair pending` liste les demandes en attente (y compris le rôle/portées)
4. approuvez la demande :
   - `/pair approve

pour une approbation explicite -/pair approvelorsqu'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 à courte durée de vie. L'amorçage du code de configuration intégré est réservé aux nœuds : la première connexion crée une demande de nœud en attente, et après approbation le Gateway renvoie un jeton de nœud durable avec `scopes: []`. Il ne renvoie pas de jeton d'opérateur transmis ; l'accès opérateur nécessite un flux distinct d'appairage ou de jeton d'opérateur approuvé.


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. Réexécutez `/pair pending` avant d'approuver.


Plus de détails : [Appairage](/fr/channels/pairing#pair-via-telegram-recommended-for-ios).
Boutons en ligne
Configurez la portée du clavier en ligne :
{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}
Substitution par compte :
{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}
Portées :


- `off`
- `dm`
- `group`
- `all`
- `allowlist` (par défaut)


L'ancien `capabilities: ["inlineButtons"]` correspond à `inlineButtons: "all"`.


Exemple d'action de message :
{
  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" }],
  ],
}
Exemple de bouton Mini App :
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}
Les boutons Telegram `web_app` ne fonctionnent que dans les discussions privées entre un utilisateur et le
bot.


Les clics sur les rappels (callbacks) sont transmis à l'agent sous forme de texte :
`callback_data:

`

<Accordion title=“TelegramActions de message Telegram pour les agents et l’automatisation”Telegram> Les actions d’outil Telegram incluent :

- `sendMessage` (`to`, `content`, `mediaUrl` facultatif, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content` ou `caption`, boutons en ligne `presentation` facultatifs ; les modifications de boutons uniquement mettent à jour le balisage de réponse)
- `createForumTopic` (`chatId`, `name`, `iconColor` facultatif, `iconCustomEmojiId`)


Les actions de message de canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).


Contrôles de validation :


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


Remarque : `edit` et `topic-create` sont actuellement activés par défaut et n'ont pas de commutateurs `channels.telegram.actions.*` séparés.
Les envois d'exécution utilisent l'instantané actif de la configuration/des secrets (démarrage/rechargement), les chemins d'action n'effectuent donc pas de nouvelle résolution ad hoc de SecretRef par envoi.


Sémantique de suppression des réactions : [/tools/reactions](/fr/tools/reactions)

<Accordion title=“Balises de discussion en réponse”Telegram> Telegram prend en charge les balises de discussion en réponse explicites dans la sortie générée :

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


`channels.telegram.replyToMode` contrôle la gestion :


- `off` (par défaut)
- `first`
- `all`TelegramOpenClawTelegramTelegramTelegram


Lorsque la discussion en réponse est activée et que le texte ou la légende Telegram d'origine est disponible, OpenClaw inclut automatiquement un extrait de citation natif Telegram. 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 reviennent à une réponse simple si Telegram rejette la citation.


Remarque : `off` désactive la discussion en réponse implicite. Les balises explicites `[[reply_to_*]]` sont toujours honorées.
Sujets de forum et comportement des fils

Super-groupes de forum :

  • les clés de session de sujet ajoutent `:topic:

- les réponses et l'écriture ciblent le fil du sujet - chemin de configuration du sujet : channels.telegram.groups.

.topics.

`

Cas particulier du sujet général (`threadId=1`) :


- l'envoi de messages omet `message_thread_id` (Telegram rejette `sendMessage(...thread_id=1)`)
- les actions d'écriture incluent toujours `message_thread_id`


Héritage de sujet : les entrées de sujet héritent des paramètres du groupe sauf en cas de remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` est exclusif au sujet et n'hérite pas des valeurs par défaut du groupe.
`topics."*"` définit les valeurs par défaut pour chaque sujet de ce groupe ; les ID de sujet exacts priment toujours sur `"*"`.


**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 isolé, sa mémoire et sa session. 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 les sessions de harnais ACP via des liaisons ACP typées de niveau supérieur (`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/super-groupes. Voir [Agents ACP](/fr/tools/acp-agents).


**Génération ACP liée au fil depuis le chat** : `/acp spawn

—thread here|autolie le sujet actuel à une nouvelle session ACP ; les suites y sont routées directement. OpenClaw épingle la confirmation de génération dans le sujet. Nécessite quechannels.telegram.threadBindings.spawnSessionsreste activé (par défaut :true`).

Le contexte du modèle expose MessageThreadId et IsForum``message_thread_id. Les conversations DM avec message_thread_id conservent les métadonnées de réponse ; elles n’utilisent des clés de session conscientes des fils que lorsque Telegram getMe signale has_topics_enabled: true pour le bot. Les anciens remplacements dm.threadReplies et direct.*.threadReplies sont intentionnellement abandonnés ; utilisez le mode fil de BotFather comme source unique de vérité et exécutez openclaw doctor --fix pour supprimer les clés de configuration obsolètes.

Audio, video, and stickers
### Messages audio


Telegram distingue les notes vocales des fichiers audio.


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


Exemple d'action de message :
{
  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 :
{
  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 du message fourni est envoyé séparément.


### Stickers


Gestion des stickers entrants :


- WEBP statique : téléchargé et traité (espace réservé `

`) - TGS animé : ignoré - WEBM vidéo : ignoré

Champs de contexte du sticker :


- `Sticker.emoji`
- `Sticker.setName`
- `Sticker.fileId`
- `Sticker.fileUniqueId`
- `Sticker.cachedDescription`


Les descriptions de stickers sont mises en cache dans l'état du plugin SQLite OpenClaw pour réduire les appels de vision répétitifs.


Activer les actions de sticker :
{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}
Envoyer une action de sticker :
{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}
Rechercher les stickers en cache :
{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

<Accordion title=“Notification de réaction”Telegram> Les réactions Telegram arrivent sous forme de mises à jour message_reactionOpenClaw (séparées des payloads de messages).

Lorsqu'elles sont activées, OpenClaw met en file d'attente des événements système tels que :


- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`


Config :


- `channels.telegram.reactionNotifications` : `off | own | all` (par défaut : `own`)
- `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` (par défaut : `minimal`)


Notes :


- `own`Telegram 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`Telegram) ; les expéditeurs non autorisés sont ignorés.
- Telegram ne fournit pas les ID de discussion dans les mises à jour de réaction.
  - les groupes non-forum sont routés vers la session de chat de groupe
  - les groupes forum sont routés vers la session du sujet général du groupe (`:topic:1`), et non vers le sujet exact d'origine


`allowed_updates` pour le polling/webhook incluent `message_reaction` automatiquement.
Ack reactions

ackReaction envoie un emoji de reconnaissance pendant qu’OpenClaw traite un message entrant. ackReactionScope décide quand cet emoji est réellement envoyé.

Ordre de résolution de l’emoji (ackReaction) :

  • `channels.telegram.accounts.

.ackReaction -channels.telegram.ackReaction -messages.ackReaction - retour de secours à l'emoji d'identité de l'agent (agents.list[].identity.emoji`, sinon ”👀”)

Notes :


- Telegram attend des emoji unicode (par exemple "👀").
- Utilisez `""` pour désactiver la réaction pour un channel ou un compte.


**Portée (`messages.ackReactionScope`) :**


Le fournisseur Telegram lit la portée depuis `messages.ackReactionScope` (par défaut `"group-mentions"`). Il n'y a aujourd'hui pas de substitution au niveau du compte Telegram ou du channel Telegram.


Valeurs : `"all"` (DMs + groupes), `"direct"` (DMs uniquement), `"group-all"` (chaque message de groupe, pas de DMs), `"group-mentions"` (groupes lorsque le bot est mentionné ; **pas de DMs** — c'est la valeur par défaut), `"off"` / `"none"` (désactivé).
TelegramÉcritures de configuration depuis les événements et commandes Telegram
Les écritures de configuration de canal sont activées par défaut (`configWrites !== false`Telegram).


Les écritures déclenchées par Telegram incluent :


- é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 :
{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}
Long polling vs webhook

Le mode par défaut est le long polling. Pour le mode webhook, définissez channels.telegram.webhookUrl et channels.telegram.webhookSecret ; optionnel webhookPath, webhookHost, webhookPort (par défaut /telegram-webhook, 127.0.0.1, 8787OpenClaw).

En mode long polling, OpenClaw persiste son filigrane de redémarrage uniquement après l’expédition 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 de redémarrage.

L’écouteur local se lie à 127.0.0.1:8787. Pour une entrée publique, placez soit un proxy inverse devant le port local, soit définissez webhookHost: "0.0.0.0"Telegram intentionnellement.

Le mode webhook valide les gardes de requête, le jeton secret Telegram et le corps JSON avant de renvoyer 200TelegramOpenClawTelegram à Telegram. OpenClaw traite ensuite la mise à jour de manière asynchrone via les mêmes voies de bot par chat/par sujet utilisées par le long polling, donc les tours d’agent lents ne bloquent pas l’ACK de livraison de Telegram.

Limites, nouvelles tentatives et cibles CLI
  • channels.telegram.textChunkLimit la valeur par défaut est 4000.
  • channels.telegram.chunkMode="newline" préfère les limites de paragraphe (lignes vides) avant le fractionnement par longueur.
  • channels.telegram.mediaMaxMb (100 par défaut) plafonne la taille des médias Telegram entrants et sortants.
  • channels.telegram.mediaGroupFlushMs (500 par défaut) contrôle la durée de mise en mémoire tampon des albums/groupes de médias Telegram avant que OpenClaw ne les distribue comme un seul message entrant. Augmentez-le si les parties de l’album arrivent en retard ; diminuez-le pour réduire la latence de réponse aux albums.
  • channels.telegram.timeoutSeconds remplace le délai d’attente du client de l’Telegram de l’API (si non défini, la valeur par défaut de grammY s’applique). Les clients de bot limitent les valeurs configurées en dessous de la garde de requête de texte/frappe sortante de 60 secondes afin que grammY n’abandonne pas la livraison de réponses visibles avant que la garde de transport et le basculement de OpenClaw puissent s’exécuter. Le sondage long utilise toujours une garde de requête de 45 secondes pour getUpdates afin que les sondages inactifs ne soient pas abandonnés indéfiniment.
  • channels.telegram.pollingStallThresholdMs est par défaut 120000 ; réglez entre 30000 et 600000 uniquement pour les redémarrages de blocage de sondage faux positifs.
  • l’historique du contexte de groupe utilise channels.telegram.historyLimit ou messages.groupChat.historyLimit (50 par défaut) ; 0 désactive.
  • le contexte supplémentaire de réponse/citation/transfert est normalisé en une seule fenêtre de contexte de conversation sélectionnée lorsque la passerelle a observé les messages parents ; le cache des messages observés réside dans l’état du plugin SQLite de OpenClaw et openclaw doctor --fix importe les sidecars hérités. Telegram n’inclut qu’un seul reply_to_message superficiel dans les mises à jour, donc les chaînes plus anciennes que le cache sont limitées à la charge utile de mise à jour actuelle de Telegram.
  • les listes blanches Telegram filtrent principalement qui peut déclencher l’agent, et non une limite complète de suppression du contexte supplémentaire.
  • contrôles de l’historique des :
    • channels.telegram.dmHistoryLimit
    • `channels.telegram.dms[”

“].historyLimit - la configchannels.telegram.retry` s’applique aux assistants d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de la réponse finale entrante utilise également une nouvelle tentative d’envoi sécurisé bornée pour les échecs de pré-connexion Telegram, mais elle ne répète 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 :
Fenêtre de terminal
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 sondages Telegram utilisent `openclaw message poll` et prennent en charge les sujets de forum :
Fenêtre de terminal
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 sondage exclusifs à 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 également 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 des images, des GIF et des vidéos sortants sous forme de documents au lieu de photos compressées, de médias animés ou de téléchargements vidéo


Gestion des actions :


- `channels.telegram.actions.sendMessage=false` désactive les messages sortants Telegram, y compris les sondages
- `channels.telegram.actions.poll=false` désactive la création de sondages Telegram tout en laissant les envois réguliers activés
Approbations exec dans Telegram

Telegram prend en charge les approbations exec dans les DM des approuveurs et peut éventuellement publier des invites dans la discussion ou le sujet d’origine. Les approuveurs doivent être des ID utilisateur numériques Telegram.

Chemin de configuration :

  • channels.telegram.execApprovals.enabled (s’active automatiquement lorsqu’au moins un approuveur est résoluble)
  • channels.telegram.execApprovals.approvers (revient aux ID de propriétaire numériques 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 approuveur exec. Le premier appariement DM approuvé amorce commands.ownerAllowFrom lorsqu’aucun propriétaire de commande n’existe encore, donc la configuration à un seul propriétaire fonctionne toujours sans dupliquer les ID sous execApprovals.approvers.

La livraison par canal affiche le texte de la commande dans la discussion ; n’activez channel ou both que dans les groupes/sujets de confiance. Lorsque l’invite atterrit dans un sujet de forum, OpenClaw préserve le sujet pour l’invite d’approbation et la suite. Les approbations exec expirent après 30 minutes par défaut.

Les boutons d’approbation en ligne nécessitent également channels.telegram.capabilities.inlineButtons pour autoriser 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 résolus d’abord via les approbations exec.

Voir Approbations exec.

Contrôles des réponses d’erreur

Section intitulée « Contrôles des réponses d’erreur »

Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut soit répondre avec le texte de l’erreur, soit le supprimer. Deux clés de configuration contrôlent ce comportement :

CléValeursPar défautDescription
channels.telegram.errorPolicyreply, silentreplyreply envoie un message d’erreur amical à la discussion. silent supprime entièrement les réponses d’erreur.
channels.telegram.errorCooldownMsnombre (ms)60000Temps minimum entre les réponses d’erreur pour la même conversation. Empêche le spam d’erreurs pendant les pannes.

Les redéfinitions par compte, par groupe et par sujet sont prises en charge (même héritage que pour les autres clés de configuration Telegram).

{
  channels: {
    telegram: {
      errorPolicy: "reply",
      errorCooldownMs: 120000,
      groups: {
        "-1001234567890": {
          errorPolicy: "silent", // suppress errors in this group
        },
      },
    },
  },
}

Dépannage

Section intitulée « Dépannage »
Bot does not respond to non mention group messages
  • Si requireMention=falseTelegram, le mode de confidentialité Telegram doit autoriser une visibilité complète.
    • BotFather : /setprivacy -> Désactiver
    • puis retirer et rajouter le bot au groupe
  • openclaw channels status avertit lorsque la configuration attend des messages de groupe non mentionnés.
  • openclaw channels status --probe peut vérifier les ID numériques explicites de groupe ; le caractère générique "*" ne peut pas faire l’objet d’une vérification d’appartenance.
  • test de session rapide : /activation always.
Bot not seeing group messages at all
  • 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 de l’ignorance
Commands work partially or not at all
  • autorisez votre identité d’expéditeur (appariement et/ou ID numérique allowFrom)
  • l’autorisation de commande 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 plugin/compétence/personnalisées ou désactivez les menus natifs
  • les appels de démarrage deleteMyCommands / setMyCommands et les appels de frappe sendChatActionTelegram sont limités et réessayent une fois via le transport de secours de Telegram en cas d’expiration de la demande. Des erreurs réseau/fetch persistantes indiquent généralement des problèmes d’accessibilité DNS/HTTPS vers api.telegram.org
Startup reports unauthorized token
  • getMe returned 401Telegram 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.

.botTokenouTELEGRAM_BOT_TOKENpour le compte par défaut. -deleteWebhook 401 Unauthorized`API lors du démarrage est également un échec d’authentification ; le traiter comme « aucun webhook n’existe » ne ferait que retarder le même échec de jeton invalide aux appels d’API ultérieurs.

Polling or network instability
- Node 22+ + custom fetch/proxy can trigger immediate abort behavior if AbortSignal types mismatch.
- Some hosts resolve `api.telegram.org` to IPv6 first; broken IPv6 egress can cause intermittent Telegram API failures.
- If logs include `TypeError: fetch failed` or `Network request for 'getUpdates' failed!`, OpenClaw now retries these as recoverable network errors.
- During polling startup, OpenClaw reuses the successful startup `getMe` probe for grammY so the runner does not need a second `getMe` before the first `getUpdates`.
- If `deleteWebhook` fails with a transient network error during polling startup, OpenClaw continues into long polling instead of making another pre-poll control-plane call. A still-active webhook surfaces as a `getUpdates` conflict; OpenClaw then rebuilds the Telegram transport and retries webhook cleanup.
- If Telegram sockets recycle on a short fixed cadence, check for a low `channels.telegram.timeoutSeconds`; bot clients clamp configured values below the outbound and `getUpdates` request guards, but older releases could abort every poll or reply when this was set below those guards.
- If logs include `Polling stall detected`, OpenClaw restarts polling and rebuilds the Telegram transport after 120 seconds without completed long-poll liveness by default.
- `openclaw channels status --probe` and `openclaw doctor` warn when a running polling account has not completed `getUpdates` after startup grace, when a running webhook account has not completed `setWebhook` after startup grace, or when the last successful polling transport activity is stale.
- Increase `channels.telegram.pollingStallThresholdMs` only when long-running `getUpdates` calls are healthy but your host still reports false polling-stall restarts. Persistent stalls usually point to proxy, DNS, IPv6, or TLS egress issues between the host and `api.telegram.org`.
- Telegram also honors process proxy env for Bot API transport, including `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and their lowercase variants. `NO_PROXY` / `no_proxy` can still bypass `api.telegram.org`.
- If the OpenClaw managed proxy is configured through `OPENCLAW_PROXY_URL` for a service environment and no standard proxy env is present, Telegram uses that URL for Bot API transport too.
- On VPS hosts with unstable direct egress/TLS, route Telegram API calls through `channels.telegram.proxy`:
channels:
  telegram:
    proxy: socks5://

:

@proxy-host:1080

    - Node 22+ defaults to `autoSelectFamily=true` (except WSL2). Telegram DNS result order honors `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, then `channels.telegram.network.dnsResultOrder`, then the process default such as `NODE_OPTIONS=--dns-result-order=ipv4first`; if none applies, Node 22+ falls back to `ipv4first`.
    - If your host is WSL2 or explicitly works better with IPv4-only behavior, force family selection:


```yaml
channels:
  telegram:
    network:
      autoSelectFamily: false
- RFC 2544 benchmark-range answers (`198.18.0.0/15`) are already allowed
  for Telegram media downloads by default. If a trusted fake-IP or
  transparent proxy rewrites `api.telegram.org` to some other
  private/internal/special-use address during media downloads, you can opt
  in to the Telegram-only bypass:
channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true
- The same opt-in is available per account at
  `channels.telegram.accounts.

.network.dangerouslyAllowPrivateNetwork. - If your proxy resolves Telegram media hosts into 198.18.x.x`, leave the dangerous flag off first. Telegram media already allows the RFC 2544 benchmark range by default.

- Environment overrides (temporary):
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Validate DNS answers:
Fenêtre de terminal
dig +short api.telegram.org A
dig +short api.telegram.org AAAA

Plus d’aide : Channel troubleshooting.

Référence de configuration

Section intitulée « Référence de configuration »

Référence principale : Configuration reference - Telegram.

TelegramChamps Telegram à signal fort
  • démarrage/auth : enabled, botToken, tokenFile, accounts.* (tokenFile doit pointer vers un fichier régulier ; les liens symboliques sont rejetés)
  • contrôle d’accès : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, bindings[] de premier niveau (type: "acp")
  • défauts de sujet : `groups.

.topics.”*”` s’applique aux sujets de forum non correspondants ; les ID de sujet exacts priment

  • approbations d’exécution : execApprovals, accounts.*.execApprovals
  • commande/menu : commands.native, commands.nativeSkills, customCommands
  • fil de discussion/réponses : replyToMode
  • streaming : streaming (aperçu), streaming.preview.toolProgress, blockStreaming
  • formatage/livraison : textChunkLimit, chunkMode, linkPreview, responsePrefix
  • média/réseau : mediaMaxMb, mediaGroupFlushMs, timeoutSeconds, pollingStallThresholdMs, retry, network.autoSelectFamily, network.dangerouslyAllowPrivateNetwork, proxyAPI
  • racine d’API personnalisée : apiRootAPI (racine de l’API Bot uniquement ; ne pas inclure `/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

Connexes

Section intitulée « Connexes »
Pairing

Associer un utilisateur Telegram à la passerelle.

Groups

Comportement de la liste d’autorisation des groupes et des sujets.

Channel routing

Acheminer les messages entrants vers les agents.

Security

Modèle de menace et durcissement.

Multi-agent routing

Associer les groupes et les sujets aux agents.

Troubleshooting

Diagnostics inter-canaux.