Telegram

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

• /setjoingroups — autoriser ou refuser l’ajout aux groupes
• /setprivacy — comportement de visibilité dans les groupes

• channels.telegram.streaming est off | partial | block | progress (valeur par défaut : partial)
• les courts aperçus de réponse initiaux sont temporisés, puis matérialisés après un délai limité si l’exécution est toujours active
• progress conserve un unique brouillon d’état modifiable pour la progression des outils, affiche le libellé d’état stable lorsque l’activité de réponse commence avant la progression des outils, l’efface à la fin et envoie la réponse finale comme un message normal
• streaming.preview.toolProgress détermine si les mises à jour des outils et de la progression réutilisent le même message d’aperçu modifié (valeur par défaut : true lorsque la diffusion de l’aperçu est active)
• streaming.preview.commandText contrôle le niveau de détail des commandes et de leur exécution dans ces lignes : raw (valeur par défaut) ou status (libellé de l’outil uniquement)
• streaming.progress.commentary (valeur par défaut : false) permet d’inclure le commentaire et le préambule de l’assistant dans le brouillon de progression temporaire
• l’ancien channels.telegram.streamMode, les valeurs booléennes streaming et les clés d’aperçu de brouillon natif retirées sont détectés ; exécutez openclaw doctor --fix pour les migrer

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

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": { "commandText": "status" }
      }
    }
  }
}

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

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Sauvegarde Git" },
        { command: "generate", description: "Créer une image" },
      ],
    },
  },
}

• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH après une nouvelle tentative de réduction signifie que le menu dépasse encore la limite ; réduisez le nombre de commandes de Plugin, de compétence ou personnalisées, ou désactivez channels.telegram.commands.native.
• Si deleteWebhook, deleteMyCommands ou setMyCommands échoue avec 404: Not Found alors que les commandes curl directes de Bot API fonctionnent, cela signifie généralement que channels.telegram.apiRoot a été défini sur le point de terminaison /bot<TOKEN> complet. apiRoot doit uniquement correspondre à la racine de Bot API ; openclaw doctor --fix supprime un suffixe /bot<TOKEN> ajouté par erreur.
• getMe returned 401 signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour botToken, tokenFile ou TELEGRAM_BOT_TOKEN (compte par défaut) avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation afin que cette erreur ne soit pas signalée comme un échec de nettoyage du Webhook.
• setMyCommands failed accompagné d’erreurs de réseau ou de récupération signifie généralement que les connexions DNS/HTTPS sortantes vers api.telegram.org sont bloquées.

​

Commandes d’association d’appareils (Plugin device-pair)

1. /pair génère un code de configuration
2. collez le code dans l’application iOS
3. /pair pending répertorie les demandes en attente (y compris le rôle et les portées)
4. approuver : /pair approve <requestId>, /pair approve (seule demande en attente) ou /pair approve latest

• sendMessage (to, content, mediaUrl facultatif, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content ou caption, boutons intégrés presentation facultatifs ; les modifications portant uniquement sur les boutons mettent à jour le balisage de réponse)
• createForumTopic (chatId, name, iconColor facultatif, iconCustomEmojiId)

• [[reply_to_current]] — répond au message déclencheur
• [[reply_to:<id>]] — répond à un ID de message précis

​

Messages audio

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

​

Messages vidéo

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

​

Emplacements et lieux

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  location: {
    latitude: 48.858844,
    longitude: 2.294351,
    accuracy: 12,
    name: "Tour Eiffel",
    address: "Champ de Mars, Paris",
  },
}

​

Autocollants

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

{
  action: "sticker-search",
  channel: "telegram",
  query: "chat qui fait signe",
  limit: 5,
}

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

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• emoji de secours de l’identité de l’agent (agents.list[].identity.emoji, sinon « 👀 »)

• channels.telegram.textChunkLimit vaut 4000 par défaut ; streaming.chunkMode="newline" privilégie les limites de paragraphes (lignes vides) avant le découpage selon la longueur.
• channels.telegram.mediaMaxMb (100 par défaut) limite la taille des médias entrants et sortants.
• channels.telegram.mediaGroupFlushMs (500 par défaut, plage 10-60000) contrôle la durée de mise en mémoire tampon des albums/groupes de médias avant qu’OpenClaw ne les transmette sous forme d’un seul message entrant. Augmentez cette valeur si des éléments de l’album arrivent tardivement ; diminuez-la pour réduire la latence de réponse aux albums.
• channels.telegram.timeoutSeconds remplace le délai d’expiration du client API (la valeur par défaut de grammY s’applique s’il n’est pas défini). Les clients de bot plafonnent les valeurs configurées inférieures à la garde de 60 secondes des requêtes sortantes de texte/de saisie afin que grammY n’interrompe pas la remise d’une réponse visible avant que la garde de transport et le mécanisme de repli d’OpenClaw puissent s’exécuter. L’interrogation longue utilise toujours une garde de requête getUpdates de 45 secondes afin que les interrogations inactives ne soient pas abandonnées indéfiniment.
• channels.telegram.pollingStallThresholdMs vaut 120000 par défaut ; ajustez-la entre 30000 et 600000 uniquement en cas de redémarrages dus à de fausses détections de blocage de l’interrogation.
• l’historique du contexte de groupe utilise channels.telegram.historyLimit ou messages.groupChat.historyLimit (50 par défaut) ; 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 réside dans l’état SQLite du Plugin OpenClaw, et openclaw doctor --fix importe les fichiers annexes hérités. Telegram n’inclut qu’un seul reply_to_message superficiel par mise à jour ; les chaînes plus anciennes que le cache sont donc limitées à cette charge utile.
• les listes d’autorisation Telegram déterminent principalement qui peut déclencher l’agent ; elles ne constituent pas une frontière complète de masquage du contexte supplémentaire.
• historique des messages privés : channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry s’applique aux utilitaires d’envoi Telegram (CLI/outils/actions) pour les erreurs récupérables de l’API sortante. La remise de la réponse finale entrante utilise une nouvelle tentative d’envoi sécurisé et limitée pour les échecs antérieurs à la connexion, mais ne réessaie pas les enveloppes réseau ambiguës postérieures à l’envoi, qui pourraient dupliquer les messages visibles.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• channels.telegram.execApprovals.enabled ("auto" l’active lorsqu’au moins un approbateur peut être résolu)
• channels.telegram.execApprovals.approvers (utilise à défaut les identifiants numériques des propriétaires provenant de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target : dm (par défaut) | channel | both
• agentFilter, sessionFilter

• Si requireMention=false, le mode de confidentialité de Telegram doit autoriser une visibilité complète : BotFather /setprivacy -> Disable, puis supprimez le bot du groupe et ajoutez-le à nouveau.
• openclaw channels status émet un avertissement lorsque la configuration attend des messages de groupe sans mention.
• openclaw channels status --probe vérifie les identifiants numériques explicites des groupes ; le caractère générique "*" ne permet pas de vérifier l’appartenance.
• Test rapide de session : /activation always.

• Lorsque channels.telegram.groups existe, le groupe doit être répertorié (ou inclure "*").
• Vérifiez que le bot appartient au groupe.
• Consultez openclaw logs --follow pour connaître les motifs d’exclusion.

• Autorisez l’identité de l’expéditeur (appairage et/ou allowFrom numérique) ; l’autorisation des commandes s’applique toujours, même lorsque la politique du groupe est open.
• setMyCommands failed avec BOT_COMMANDS_TOO_MUCH signifie que le menu natif comporte trop d’entrées ; réduisez le nombre de commandes de Plugin/Skills/personnalisées ou désactivez les menus natifs.
• Les appels de démarrage deleteMyCommands / setMyCommands et les appels de saisie sendChatAction sont limités et font l’objet d’une nouvelle tentative via le mécanisme de repli du transport Telegram en cas d’expiration de la requête. Les erreurs persistantes de réseau/récupération signifient généralement que api.telegram.org est inaccessible par DNS/HTTPS.

• getMe returned 401 est un échec d’authentification Telegram pour le jeton de bot configuré. Copiez à nouveau ou régénérez le jeton dans BotFather, puis mettez à jour channels.telegram.botToken, tokenFile, accounts.<id>.botToken ou TELEGRAM_BOT_TOKEN (compte par défaut).
• deleteWebhook 401 Unauthorized au démarrage est également un échec d’authentification ; le traiter comme « aucun Webhook n’existe » ne ferait que différer le même échec dû au jeton incorrect jusqu’à un appel API ultérieur.

• Node 22+ avec un mécanisme de récupération/proxy personnalisé peut provoquer un 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 provoque des échecs intermittents de l’API.
• Les journaux contenant TypeError: fetch failed ou Network request for 'getUpdates' failed! font l’objet de nouvelles tentatives en tant qu’erreurs réseau récupérables.
• Au démarrage de l’interrogation, OpenClaw réutilise pour grammY la sonde getMe ayant réussi au démarrage, afin que l’exécuteur n’ait pas besoin d’effectuer un second getMe avant le premier getUpdates.
• Si deleteWebhook échoue en raison d’une erreur réseau temporaire au démarrage de l’interrogation, OpenClaw passe à l’interrogation longue au lieu d’effectuer un autre appel du plan de contrôle avant l’interrogation. Un Webhook encore actif se manifeste alors sous forme de conflit getUpdates ; OpenClaw reconstruit le transport et réessaie de nettoyer le Webhook.
• Si les sockets Telegram sont renouvelés selon une cadence fixe et courte, recherchez une valeur channels.telegram.timeoutSeconds faible : les clients de bot plafonnent les valeurs configurées inférieures aux gardes de requête sortantes et getUpdates, mais les anciennes versions pouvaient interrompre chaque interrogation ou réponse lorsque cette valeur était inférieure à ces gardes.
• Polling stall detected dans les journaux signifie qu’OpenClaw redémarre l’interrogation et reconstruit le transport après 120 secondes sans activité d’interrogation longue achevée par défaut.
• openclaw channels status --probe et openclaw doctor émettent un avertissement lorsqu’un compte d’interrogation actif n’a pas achevé getUpdates après le délai de grâce du démarrage, qu’un compte Webhook actif n’a pas achevé setWebhook après le délai de grâce du démarrage, ou que 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 fonctionnent correctement, mais que votre hôte signale toujours de faux redémarrages dus au blocage de l’interrogation. Les blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou de sortie TLS vers api.telegram.org.
• Telegram respecte les variables d’environnement de proxy du processus pour le transport de l’API Bot : HTTP_PROXY, HTTPS_PROXY, ALL_PROXY et leurs variantes en minuscules. NO_PROXY / no_proxy peuvent toujours contourner api.telegram.org.
• Si OPENCLAW_PROXY_URL est défini pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise également cette URL pour le transport de l’API Bot.
• Sur les hôtes VPS dont la sortie directe/TLS est instable, acheminez les appels à l’API Telegram via un proxy :

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

• Node 22+ utilise par défaut autoSelectFamily=true (sauf sous WSL2). L’ordre des résultats DNS de Telegram respecte OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, puis channels.telegram.network.dnsResultOrder, puis la valeur par défaut du processus (par exemple NODE_OPTIONS=--dns-result-order=ipv4first), avec un repli vers ipv4first sous Node 22+ si aucune ne s’applique.
• Sous WSL2, ou lorsqu’un fonctionnement exclusivement en IPv4 donne de meilleurs résultats, forcez la sélection de la famille :

channels:
  telegram:
    network:
      autoSelectFamily: false

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

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La même activation est disponible pour chaque compte dans channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si votre proxy résout les hôtes de médias Telegram dans 198.18.x.x, laissez d’abord l’option dangereuse désactivée — cette plage est déjà autorisée par défaut.

• Remplacements temporaires par variables d’environnement : OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Validez les réponses DNS :

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