Telegram (Bot API)¶

Statut : prêt pour la production pour les Messages prives des bots + les groupes via grammY. Long-polling par défaut ; webhook optionnel.

Default DM policy for Telegram is pairing. Cross-channel diagnostics and repair playbooks. Full channel config patterns and examples.

Configuration (chemin rapide)¶

Ouvrez Telegram et discutez avec @BotFather (lien direct). Confirmez que le handle est exactement @BotFather.

```
`/newbot` cree le bot et renvoie le token (gardez‑le secret).
```

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

```
Option env : `TELEGRAM_BOT_TOKEN=...` (fonctionne pour le compte par defaut).
```

`openclaw pairing approve telegram <CODE>`

```
Pairing codes expire after 1 hour.
```

Pour les groupes : ajoutez le bot, decidez du comportement de confidentialite/admin (ci‑dessous), puis definissez channels.telegram.groups pour controler le filtrage par mention + les listes d’autorisation.

Token resolution order is account-aware. In practice, config values win over env fallback, and TELEGRAM_BOT_TOKEN only applies to the default account.

Telegram side settings¶

Remarque : Lors d’un changement du mode confidentialite, Telegram exige de retirer puis de rajouter le bot dans chaque groupe pour que le changement prenne effet.

```
`/setprivacy` — controler si le bot voit tous les messages de groupe.
```

Le statut admin se definit dans le groupe (UI Telegram).

```
Ajouter le bot comme **admin** du groupe (les bots admins recoivent tous les messages).
```

```
`/setjoingroups` — autoriser/interdire l’ajout du bot aux groupes.
```

Access control and activation¶

channels.telegram.dmPolicy controls direct message access:

```
`channels.telegram.allowFrom` accepte des IDs utilisateur numeriques (recommande) ou des entrees `@username`. Ce n’est **pas** le nom d’utilisateur du bot ; utilisez l’ID de l’expediteur humain. L’assistant accepte `@username` et le resout vers l’ID numerique lorsque possible.
```

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

```
Envoyez un Message prive a `@userinfobot` ou `@getidsbot` et utilisez l’ID utilisateur renvoye.
```

Deux controles independants :

```
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // all groups, always respond
      },
    },
  },
}
```

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Group replies require mention by default.

```
Mention can come from:

- native `@botusername` mention, or
- mention patterns in:
  - `agents.list[].groupChat.mentionPatterns`
  - `messages.groupChat.mentionPatterns`

Session-level command toggles:

- `/activation always`
- `/activation mention`

These update session state only. Use config for persistence.

Persistent config example:
```

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // or omit groups entirely
      },
    },
  },
}

```
Transmettez n’importe quel message du groupe a `@userinfobot` ou `@getidsbot` sur Telegram pour voir l’ID du chat (nombre negatif comme `-1001234567890`).
```

Runtime behavior¶

• Telegram is owned by the gateway process.
• Routage deterministe : les reponses repartent vers Telegram ; le modele ne choisit jamais les canaux.
• Les messages entrants sont normalises dans l’enveloppe de canal partagee avec contexte de reponse et emplacements media.
• Group sessions are isolated by group ID. Ajoute :topic:<threadId> a la cle de session du groupe Telegram afin que chaque sujet soit isole.
• Les chats prives peuvent inclure message_thread_id dans certains cas limites. OpenClaw conserve la cle de session DM inchangée, mais utilise tout de meme l’id de fil pour les reponses/le streaming de brouillons lorsqu’il est present.
• Long polling uses grammY runner with per-chat/per-thread sequencing. Le long‑polling utilise le runner grammY avec un sequencage par chat ; la concurrence globale est plafonnee par agents.defaults.maxConcurrent.
• L’API Bot Telegram ne prend pas en charge les accusés de lecture ; il n’existe pas d’option sendReadReceipts.

Feature reference¶

OpenClaw peut diffuser des reponses partielles dans les Messages prives Telegram via sendMessageDraft.

```
Requirement:

- `channels.telegram.streamMode` is not `"off"` (default: `"partial"`)

Modes:

- `off`: no live preview
- `partial`: frequent preview updates from partial text
- `block`: chunked preview updates using `channels.telegram.draftChunk`

`draftChunk` defaults for `streamMode: "block"`:

- `minChars: 200`
- `maxChars: 800`
- `breakPreference: "paragraph"`

`maxChars` is clamped by `channels.telegram.textChunkLimit`.

This works in direct chats and groups/topics.

For text-only replies, OpenClaw keeps the same preview message and performs a final edit in place (no second message).

For complex replies (for example media payloads), OpenClaw falls back to normal final delivery and then cleans up the preview message.

`streamMode` is separate from block streaming. When block streaming is explicitly enabled for Telegram, OpenClaw skips the preview stream to avoid double-streaming.

Telegram-only reasoning stream:

- `/reasoning stream` sends reasoning to the live preview while generating
- final answer is sent without reasoning text
```

Le texte Telegram sortant utilise parse_mode: "HTML" (sous‑ensemble de balises pris en charge par Telegram).

```
- Markdown-ish text is rendered to Telegram-safe HTML.
- Raw model HTML is escaped to reduce Telegram parse failures.
- If Telegram rejects parsed HTML, OpenClaw retries as plain text.

Link previews are enabled by default and can be disabled with `channels.telegram.linkPreview: false`.
```

Some commands can be handled by plugins/skills without being registered in Telegram’s command menu.

```
OpenClaw enregistre des commandes natives (comme `/status`, `/reset`, `/model`) dans le menu de bot Telegram au demarrage. Vous pouvez ajouter des commandes personnalisees au menu via la config :
```

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

```
Rules:

- names are normalized (strip leading `/`, lowercase)
- valid pattern: `a-z`, `0-9`, `_`, length `1..32`
- custom commands cannot override native commands
- conflicts/duplicates are skipped and logged

Notes:

- custom commands are menu entries only; they do not auto-implement behavior
- plugin/skill commands can still work when typed even if not shown in Telegram menu

If native commands are disabled, built-ins are removed. Custom/plugin commands may still register if configured.

Common setup failure:

- `setMyCommands failed` usually means outbound DNS/HTTPS to `api.telegram.org` is blocked.

### Device pairing commands (`device-pair` plugin)

When the `device-pair` plugin is installed:

1. `/pair` generates setup code
2. paste code in iOS app
3. `/pair approve` approves latest pending request

More details: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios).
```

Configure inline keyboard scope:

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

```
Per-account override:
```

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

```
`"disabled"` = aucun message de groupe accepte
  La valeur par defaut est `groupPolicy: "allowlist"` (bloque tant que vous n’ajoutez pas `groupAllowFrom`).
```

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

```
Lorsqu’un utilisateur clique sur un bouton, les donnees de rappel sont renvoyees a l’agent sous forme de message au format :
`callback_data: value`
```

Telegram tool actions include:

```
- `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)

Channel message actions expose ergonomic aliases (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`).

Gating controls:

- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.editMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (default: disabled)

Reaction removal semantics: [/tools/reactions](/tools/reactions)
```

Telegram prend en charge les reponses filaires optionnelles via des balises :

```
- `[[reply_to_current]]` replies to the triggering message
- `[[reply_to:<id>]]` replies to a specific Telegram message ID

`channels.telegram.replyToMode` controls handling:

- `off` (default)
- `first`
- `all`

Note: `off` disables implicit reply threading. Explicit `[[reply_to_*]]` tags are still honored.
```

Sujets (supergroupes forum)

```
Fils de discussion en chat prive uniquement (Telegram inclut `message_thread_id` dans les messages entrants).
```

### Audio messages

```
`[[audio_as_voice]]` — envoyer l’audio comme note vocale au lieu d’un fichier.
```

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

```
Video messages (video vs video note)
```

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

```
Video notes do not support captions; provided message text is sent separately.

### Stickers

Inbound sticker handling:

- static WEBP: downloaded and processed (placeholder `<media:sticker>`)
- animated TGS: skipped
- video WEBM: skipped

Sticker context fields:

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

Sticker cache file:

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

Stickers are described once (when possible) and cached to reduce repeated vision calls.

Enable sticker actions:
```

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

```
Envoi d’autocollants
```

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

```
Cache des autocollants
```

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

Recoit la mise a jour message_reaction depuis l’API Telegram

```
When enabled, OpenClaw enqueues system events like:

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

Config:

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

Notes:

- `own` means user reactions to bot-sent messages only (best-effort via sent-message cache).
- Telegram does not provide thread IDs in reaction updates.
  - non-forum groups route to group chat session
  - forum groups route to the group general-topic session (`:topic:1`), not the exact originating topic

`allowed_updates` for polling/webhook include `message_reaction` automatically.
```

Fonctionnement des reactions : Les reactions Telegram arrivent sous forme d’evenements message_reaction distincts, et non comme des proprietes dans les charges de message. Lorsqu’un utilisateur ajoute une reaction, OpenClaw :

```
Resolution order:

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")

Notes:

- Telegram expects unicode emoji (for example "👀").
- Use `""` to disable the reaction for a channel or account.
```

Channel config writes are enabled by default (configWrites !== false).

```
Par defaut, Telegram est autorise a ecrire des mises a jour de configuration declenchees par des evenements de canal ou `/config set|unset`.
```

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

Default: long polling.

```
Si votre URL publique est differente, utilisez un proxy inverse et pointez `channels.telegram.webhookUrl` vers le point de terminaison public.
```

Le texte sortant est segmente jusqu’a channels.telegram.textChunkLimit (par defaut 4000). Segmentation optionnelle par sauts de ligne : definissez channels.telegram.chunkMode="newline" pour scinder sur les lignes vides (frontieres de paragraphes) avant la segmentation par longueur. Les telechargements/envois de medias sont plafonnes par channels.telegram.mediaMaxMb (par defaut 5). Les requetes API Bot Telegram expirent apres channels.telegram.timeoutSeconds (par defaut 500 via grammY). Le contexte d’historique de groupe utilise channels.telegram.historyLimit (ou channels.telegram.accounts.*.historyLimit), avec repli sur messages.groupChat.historyLimit. Definissez 0 pour desactiver (par defaut 50). - DM history controls: - channels.telegram.dmHistoryLimit - channels.telegram.dms["<user_id>"].historyLimit - outbound Telegram API retries are configurable via channels.telegram.retry.

```
CLI send target can be numeric chat ID or username:
```

Exemple : `openclaw message send --channel telegram --target 123456789 --message "hi"`.

Problemes courants¶

```
Si vous avez defini `channels.telegram.groups.*.requireMention=false`, le **mode confidentialite** de l’API Bot Telegram doit etre desactive.
```

```
- when `channels.telegram.groups` exists, group must be listed (or include `"*"`)
- verify bot membership in group
- review logs: `openclaw logs --follow` for skip reasons
```

```
`setMyCommands failed` dans les journaux signifie generalement que la sortie HTTPS/DNS est bloquee vers `api.telegram.org`.
```

```
- 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.
- Validate DNS answers:
```

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

Plus d’aide : Depannage des canaux.

Reference de configuration (Telegram)¶

Primary reference:

• channels.telegram.enabled : activer/desactiver le demarrage du canal.

• channels.telegram.botToken : token du bot (BotFather).

• channels.telegram.tokenFile : lire le token depuis un chemin de fichier.

• channels.telegram.dmPolicy : pairing | allowlist | open | disabled (par defaut : appairage).

• channels.telegram.allowFrom : liste d’autorisation DM (ids/noms d’utilisateur). open requiert "*". openclaw doctor --fix can resolve legacy @username entries to IDs.

• channels.telegram.groupPolicy : open | allowlist | disabled (par defaut : liste d’autorisation).

• channels.telegram.groupAllowFrom : liste d’autorisation des expéditeurs de groupe (ids/noms d’utilisateur). openclaw doctor --fix can resolve legacy @username entries to IDs.

• channels.telegram.groups : valeurs par defaut par groupe + liste d’autorisation (utilisez "*" pour les valeurs globales).

• channels.telegram.groups.<id>.groupPolicy : surcharge par groupe pour groupPolicy (open | allowlist | disabled).
• channels.telegram.groups.<id>.requireMention : filtrage par mention par defaut.
• channels.telegram.groups.<id>.skills : filtre de skills (omis = tous les skills, vide = aucun).
• channels.telegram.groups.<id>.allowFrom : surcharge de liste d’autorisation des expéditeurs par groupe.
• channels.telegram.groups.<id>.systemPrompt : invite systeme supplementaire pour le groupe.
• channels.telegram.groups.<id>.enabled : desactiver le groupe lorsque false.
• .topics.channels.telegram.groups.<id>.* : surcharges par sujet (memes champs que le groupe).
• channels.telegram.groups.<id>.topics.<threadId>.groupPolicy : surcharge par sujet pour groupPolicy (open | allowlist | disabled).

• .topics.channels.telegram.groups.<id>.requireMention : surcharge de filtrage par mention par sujet.

• channels.telegram.capabilities.inlineButtons : off | dm | group | all | allowlist (par defaut : liste d’autorisation).

• channels.telegram.accounts.<account>.capabilities.inlineButtons : surcharge par compte.

• channels.telegram.replyToMode : off | first | all (par defaut : first).

• channels.telegram.textChunkLimit : taille de segmentation sortante (caracteres).

• channels.telegram.chunkMode : length (par defaut) ou newline pour scinder sur les lignes vides (frontieres de paragraphes) avant la segmentation par longueur.

• channels.telegram.linkPreview : activer/desactiver les apercus de lien pour les messages sortants (par defaut : true).

• channels.telegram.streamMode : off | partial | block (streaming de brouillons).

• channels.telegram.mediaMaxMb : plafond media entrant/sortant (Mo).

• channels.telegram.retry : politique de reessai pour les appels API Telegram sortants (tentatives, minDelayMs, maxDelayMs, jitter).

• channels.telegram.network.autoSelectFamily : surcharge de Node autoSelectFamily (true=activer, false=desactiver). Desactive par defaut sur Node 22 pour eviter les delais Happy Eyeballs.

• channels.telegram.proxy : URL de proxy pour les appels API Bot (SOCKS/HTTP).

• channels.telegram.webhookUrl : activer le mode webhook (necessite channels.telegram.webhookSecret).

• channels.telegram.webhookSecret : secret de webhook (requis lorsque webhookUrl est defini).

• channels.telegram.webhookPath : chemin local du webhook (par defaut /telegram-webhook).

• L’ecouteur local se lie a 0.0.0.0:8787 et sert POST /telegram-webhook par defaut.

• channels.telegram.actions.reactions : filtrer les reactions de l’outil Telegram.

• channels.telegram.actions.sendMessage : filtrer les envois de messages de l’outil Telegram.

• channels.telegram.actions.deleteMessage : filtrer les suppressions de messages de l’outil Telegram.

• channels.telegram.actions.sticker : filtrer les actions d’autocollants Telegram — envoi et recherche (par defaut : false).

• channels.telegram.reactionNotifications : off | own | all — controler quelles reactions declenchent des evenements systeme (par defaut : own lorsqu’il n’est pas defini).

• channels.telegram.reactionLevel : off | ack | minimal | extensive — controler la capacite de reaction de l’agent (par defaut : minimal lorsqu’il n’est pas defini).

• Configuration complete : Configuration

Telegram-specific high-signal fields:

• startup/auth: enabled, botToken, tokenFile, accounts.*
• Les commandes necessitent une autorisation meme dans les groupes avec groupPolicy: "open"
• command/menu: commands.native, customCommands
• threading/replies: replyToMode
• Optionnel (uniquement pour streamMode: "block") :
• formatting/delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
• media/network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• Mode webhook : definissez channels.telegram.webhookUrl et channels.telegram.webhookSecret (optionnellement channels.telegram.webhookPath).
• actions/capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• Notifications de reactions
• writes/history: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

Related¶

• Pairing
• More details: Pairing.
• channels.telegram.streamMode: "off" | "partial" | "block" (par defaut : partial)