Telegram (API Bot)

Les bots Telegram sont en **Privacy Mode** par defaut, ce qui limite les messages de groupe qu'ils recoivent.

Si le bot doit voir tous les messages de groupe, vous pouvez soit :

- desactiver le mode confidentialite via `/setprivacy`, soit
- rendre le bot administrateur du groupe.

Lorsque vous basculez le mode confidentialite, retirez + re-ajoutez le bot dans chaque groupe pour que Telegram applique le changement.

Le statut administrateur est controle dans les parametres du groupe Telegram.

Les bots administrateurs recoivent tous les messages de groupe, ce qui est utile pour un comportement de groupe permanent.

- `/setjoingroups` pour autoriser/interdire l'ajout aux groupes
- `/setprivacy` pour le comportement de visibilite de groupe

OpenClaw peut diffuser les reponses partielles en temps reel :

- chats directs : message d'apercu + `editMessageText`
- groupes/sujets : message d'apercu + `editMessageText`

Prerequis :

- `channels.telegram.streaming` est `off | partial | block | progress` (par defaut : `partial`)
- `progress` correspond a `partial` sur Telegram (compatibilite inter-canaux)
- les valeurs anciennes `channels.telegram.streamMode` et booleennes `streaming` sont migrees automatiquement

Pour les reponses en texte seul :

- DM : OpenClaw conserve le meme message d'apercu et effectue une modification finale en place (pas de second message)
- groupe/sujet : OpenClaw conserve le meme message d'apercu et effectue une modification finale en place (pas de second message)

Pour les reponses complexes (par exemple payloads media), OpenClaw se replie sur la livraison finale normale et nettoie ensuite le message d'apercu.

Le streaming d'apercu est distinct du streaming par blocs. Lorsque le streaming par blocs est explicitement active pour Telegram, OpenClaw saute le flux d'apercu pour eviter un double streaming.

Si le transport de brouillon natif est indisponible/rejete, OpenClaw se replie automatiquement sur `sendMessage` + `editMessageText`.

Flux de raisonnement specifique a Telegram :

- `/reasoning stream` envoie le raisonnement dans l'apercu en direct pendant la generation
- la reponse finale est envoyee sans le texte de raisonnement

Le texte sortant utilise `parse_mode: "HTML"` de Telegram.

- Le texte de style Markdown est rendu en HTML compatible Telegram.
- Le HTML brut du modele est echappe pour reduire les echecs d'analyse Telegram.
- Si Telegram rejette le HTML analyse, OpenClaw reessaie en texte brut.

Les apercu de liens sont actives par defaut et peuvent etre desactives avec `channels.telegram.linkPreview: false`.

L'enregistrement du menu de commandes Telegram est gere au demarrage avec `setMyCommands`.

Valeurs par defaut des commandes natives :

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

Ajouter des entrees de menu de commandes personnalisees :

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

Regles :

- les noms sont normalises (suppression du `/` initial, minuscules)
- motif valide : `a-z`, `0-9`, `_`, longueur `1..32`
- les commandes personnalisees ne peuvent pas remplacer les commandes natives
- les conflits/doublons sont ignores et journalises

Remarques :

- les commandes personnalisees sont des entrees de menu uniquement ; elles n'implementent pas automatiquement de comportement
- les commandes de plugin/competence peuvent toujours fonctionner lorsqu'elles sont tapees meme si elles n'apparaissent pas dans le menu Telegram

Si les commandes natives sont desactivees, les commandes integrees sont supprimees. Les commandes personnalisees/plugin peuvent toujours s'enregistrer si elles sont configurees.

Echecs de configuration courants :

- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram a toujours deborde apres nettoyage ; reduisez les commandes plugin/competence/personnalisees ou desactivez `channels.telegram.commands.native`.
- `setMyCommands failed` avec des erreurs reseau/fetch signifie generalement que le DNS/HTTPS sortant vers `api.telegram.org` est bloque.

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

Lorsque le plugin `device-pair` est installe :

1. `/pair` genere un code de configuration
2. collez le code dans l'application iOS
3. `/pair approve` approuve la derniere requete en attente

Plus de details : [Appairage](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

Configurez le perimetre du clavier inline :

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

Remplacement par compte :

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

Perimetres :

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (par defaut)

L'ancien `capabilities: ["inlineButtons"]` correspond a `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" }],
  ],
}

Les clics de callback sont transmis a l'agent sous forme de texte :
`callback_data: <value>`

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`).

Controles :

- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (par defaut : desactive)

> **Remarque :** `edit` et `topic-create` sont actuellement actives par defaut et n'ont pas de bascules `channels.telegram.actions.*` separees.
Les envois a l'execution utilisent l'instantane actif de configuration/secrets (demarrage/rechargement), donc les chemins d'action n'effectuent pas de re-resolution SecretRef ad-hoc par envoi.

Semantique de suppression de reaction : [/tools/reactions](/docs/tools/reactions)

Telegram prend en charge les tags de fil de reponse explicites dans la sortie generee :

- `[[reply_to_current]]` repond au message declencheur
- `[[reply_to:<id>]]` repond a un identifiant de message Telegram specifique

`channels.telegram.replyToMode` controle le comportement :

- `off` (par defaut)
- `first`
- `all`

> **Remarque :** `off` desactive le fil de reponse implicite. Les tags explicites `[[reply_to_*]]` sont toujours honores.

Supergroupes forum :

- les cles de session de sujet ajoutent `:topic:<threadId>`
- les reponses et la saisie ciblent le fil du sujet
- chemin de configuration du sujet :
  `channels.telegram.groups.<chatId>.topics.<threadId>`

Cas special du sujet general (`threadId=1`) :

- les envois de messages omettent `message_thread_id` (Telegram rejette `sendMessage(...thread_id=1)`)
- les actions de saisie incluent toujours `message_thread_id`

Heritage de sujet : les entrees de sujet heritent des parametres du groupe sauf s'ils sont remplaces (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` est specifique au sujet et n'herite pas des valeurs par defaut du groupe.

**Routage d'agent par sujet** : chaque sujet peut router vers un agent different en definissant `agentId` dans la configuration du sujet. Cela donne a chaque sujet son propre espace de travail, memoire et session isoles. Exemple :

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Sujet general → agent main
            "3": { agentId: "zu" },        // Sujet Dev → agent zu
            "5": { agentId: "coder" }      // Revue de code → agent coder
          }
        }
      }
    }
  }
}
```

Chaque sujet a alors sa propre cle de session : `agent:zu:telegram:group:-1001234567890:topic:3`

**Liaison ACP persistante par sujet** : les sujets de forum peuvent epingler des sessions de harnais ACP via des liaisons ACP typees au niveau racine :

- `bindings[]` avec `type: "acp"` et `match.channel: "telegram"`

Exemple :

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
```

Ce perimetre est actuellement limite aux sujets de forum dans les groupes et supergroupes.

**Spawn ACP lie au fil depuis le chat** :

- `/acp spawn <agent> --thread here|auto` peut lier le sujet Telegram actuel a une nouvelle session ACP.
- Les messages suivants dans le sujet sont routes directement vers la session ACP liee (pas de `/acp steer` requis).
- OpenClaw epingle le message de confirmation du spawn dans le sujet apres une liaison reussie.
- Necessite `channels.telegram.threadBindings.spawnAcpSessions=true`.

Le contexte de template inclut :

- `MessageThreadId`
- `IsForum`

Comportement des fils DM :

- les chats prives avec `message_thread_id` conservent le routage DM mais utilisent des cles de session/cibles de reponse tenant compte du fil.

### Messages audio

Telegram distingue les notes vocales des fichiers audio.

- par defaut : comportement de fichier audio
- tag `[[audio_as_voice]]` dans la reponse de l'agent pour forcer l'envoi en note vocale

Exemple d'action de message :

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

### Messages video

Telegram distingue les fichiers video des notes video.

Exemple d'action de message :

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

Les notes video ne supportent pas les legendes ; le texte du message fourni est envoye separement.

### Stickers

Gestion des stickers entrants :

- WEBP statique : telecharge et traite (placeholder `<media:sticker>`)
- TGS anime : ignore
- WEBM video : ignore

Champs de contexte des stickers :

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

Fichier cache des stickers :

- `~/.openclaw/telegram/sticker-cache.json`

Les stickers sont decrits une fois (quand c'est possible) et mis en cache pour reduire les appels de vision repetes.

Activer les actions sticker :

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

Envoyer un sticker :

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

Rechercher dans les stickers en cache :

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

Les reactions Telegram arrivent sous forme de mises a jour `message_reaction` (separees des payloads de message).

Lorsqu'elles sont activees, OpenClaw met en file d'attente des evenements systeme comme :

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

Configuration :

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

Remarques :

- `own` signifie uniquement les reactions des utilisateurs aux messages envoyes par le bot (best-effort via le cache de messages envoyes).
- Les evenements de reaction respectent toujours les controles d'acces Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`) ; les expediteurs non autorises sont supprimes.
- Telegram ne fournit pas d'identifiants de fil dans les mises a jour de reaction.
  - les groupes non-forum sont routes vers la session de chat de groupe
  - les groupes forum sont routes vers la session du sujet general du groupe (`:topic:1`), pas le sujet d'origine exact

`allowed_updates` pour le polling/webhook inclut `message_reaction` automatiquement.

`ackReaction` envoie un emoji d'accuse de reception pendant qu'OpenClaw traite un message entrant.

Ordre de resolution :

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- emoji de secours de l'identite de l'agent (`agents.list[].identity.emoji`, sinon "eyes")

Remarques :

- Telegram attend des emojis unicode (par exemple "eyes").
- Utilisez `""` pour desactiver la reaction pour un canal ou un compte.

Les ecritures de configuration du canal sont activees par defaut (`configWrites !== false`).

Les ecritures declenchees par Telegram incluent :

- les evenements de migration de groupe (`migrate_to_chat_id`) pour mettre a jour `channels.telegram.groups`
- `/config set` et `/config unset` (necessite l'activation des commandes)

Desactivation :

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

Par defaut : long polling.

Mode webhook :

- definissez `channels.telegram.webhookUrl`
- definissez `channels.telegram.webhookSecret` (requis lorsque l'URL webhook est definie)
- optionnel `channels.telegram.webhookPath` (par defaut `/telegram-webhook`)
- optionnel `channels.telegram.webhookHost` (par defaut `127.0.0.1`)
- optionnel `channels.telegram.webhookPort` (par defaut `8787`)

L'ecouteur local par defaut pour le mode webhook se lie a `127.0.0.1:8787`.

Si votre point de terminaison public differe, placez un reverse proxy devant et pointez `webhookUrl` vers l'URL publique.
Definissez `webhookHost` (par exemple `0.0.0.0`) lorsque vous avez intentionnellement besoin d'un acces externe.

- `channels.telegram.textChunkLimit` par defaut est 4000.
- `channels.telegram.chunkMode="newline"` prefere les limites de paragraphes (lignes vides) avant le decoupage par longueur.
- `channels.telegram.mediaMaxMb` (par defaut 100) plafonne les medias entrants et sortants Telegram.
- `channels.telegram.timeoutSeconds` remplace le timeout du client API Telegram (si non defini, le defaut de grammY s'applique).
- le contexte d'historique de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (par defaut 50) ; `0` desactive.
- controles d'historique DM :
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- la configuration `channels.telegram.retry` s'applique aux helpers d'envoi Telegram (CLI/outils/actions) pour les erreurs API sortantes recuperables.

La cible d'envoi CLI peut etre un identifiant de chat numerique ou un nom d'utilisateur :

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Les sondages Telegram utilisent `openclaw message poll` et prennent en charge les sujets de forum :

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

Options de sondage specifiques a Telegram :

- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` pour les sujets de forum (ou utilisez une cible `:topic:`)

Controle des actions :

- `channels.telegram.actions.sendMessage=false` desactive les messages Telegram sortants, y compris les sondages
- `channels.telegram.actions.poll=false` desactive la creation de sondages Telegram tout en laissant les envois normaux actives

Telegram prend en charge les approbations d'execution dans les DMs de l'approbateur et peut optionnellement publier les invites d'approbation dans le chat ou sujet d'origine.

Chemin de configuration :

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, par defaut : `dm`)
- `agentFilter`, `sessionFilter`

Les approbateurs doivent etre des identifiants utilisateur Telegram numeriques. Lorsque `enabled` est false ou `approvers` est vide, Telegram n'agit pas comme client d'approbation d'execution. Les requetes d'approbation se replient sur d'autres routes d'approbation configurees ou la politique de secours d'approbation d'execution.

Regles de livraison :

- `target: "dm"` envoie les invites d'approbation uniquement aux DMs des approbateurs configures
- `target: "channel"` envoie l'invite vers le chat/sujet Telegram d'origine
- `target: "both"` envoie aux DMs des approbateurs et au chat/sujet d'origine

Seuls les approbateurs configures peuvent approuver ou refuser. Les non-approbateurs ne peuvent pas utiliser `/approve` ni les boutons d'approbation Telegram.

La livraison par salon montre le texte de la commande dans le chat, donc n'activez `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque l'invite arrive dans un sujet de forum, OpenClaw preserve le sujet pour l'invite d'approbation et le suivi post-approbation.

Les boutons d'approbation inline dependent egalement de `channels.telegram.capabilities.inlineButtons` autorisant la surface cible (`dm`, `group`, ou `all`).

Documentation associee : [Approbations d'execution](/docs/tools/exec-approvals)

- Si `requireMention=false`, le mode confidentialite Telegram doit permettre une visibilite complete.
  - BotFather : `/setprivacy` -> Disable
  - puis retirez + re-ajoutez le bot au groupe
- `openclaw channels status` avertit lorsque la configuration attend des messages de groupe sans mention.
- `openclaw channels status --probe` peut verifier des identifiants de groupe numeriques explicites ; le joker `"*"` ne peut pas etre sonde en termes d'appartenance.
- test rapide de session : `/activation always`.

- lorsque `channels.telegram.groups` existe, le groupe doit etre liste (ou inclure `"*"`)
- verifiez l'appartenance du bot au groupe
- consultez les logs : `openclaw logs --follow` pour les raisons de saut

- autorisez l'identite de votre expediteur (appairage et/ou `allowFrom` numerique)
- l'autorisation des commandes s'applique toujours meme lorsque la politique de groupe est `open`
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif a trop d'entrees ; reduisez les commandes plugin/competence/personnalisees ou desactivez les menus natifs
- `setMyCommands failed` avec des erreurs reseau/fetch indique generalement des problemes d'accessibilite DNS/HTTPS vers `api.telegram.org`

- Node 22+ + fetch/proxy personnalise peut declencher un comportement d'abandon immediat si les types AbortSignal ne correspondent pas.
- Certains hotes resolvent `api.telegram.org` en IPv6 d'abord ; une sortie IPv6 defaillante peut provoquer des echecs intermittents de l'API Telegram.
- Si les logs incluent `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, OpenClaw reessaie desormais ces erreurs comme des erreurs reseau recuperables.
- Sur les hotes VPS avec une sortie directe/TLS instable, routez les appels API Telegram via `channels.telegram.proxy` :

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

- Node 22+ utilise par defaut `autoSelectFamily=true` (sauf WSL2) et `dnsResultOrder=ipv4first`.
- Si votre hote est WSL2 ou fonctionne mieux avec un comportement IPv4 uniquement, forcez la selection de famille :

channels:
  telegram:
    network:
      autoSelectFamily: false

- Variables d'environnement de remplacement (temporaires) :
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Validez les reponses DNS :

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