Telegram (Bot API)

I bot Telegram hanno la **Modalita Privacy** abilitata per impostazione predefinita, che limita quali messaggi di gruppo ricevono.

Se il bot deve vedere tutti i messaggi di gruppo:

- disabilita la modalita privacy tramite `/setprivacy`, oppure
- rendi il bot amministratore del gruppo.

Quando cambi la modalita privacy, rimuovi + ri-aggiungi il bot in ogni gruppo cosi Telegram applica la modifica.

Lo stato di amministratore e controllato nelle impostazioni del gruppo Telegram.

I bot amministratori ricevono tutti i messaggi di gruppo, utile per il comportamento di gruppo always-on.

- `/setjoingroups` per consentire/negare l'aggiunta ai gruppi
- `/setprivacy` per il comportamento di visibilita nei gruppi

OpenClaw puo fare lo streaming di risposte parziali in tempo reale:

- chat dirette: messaggio anteprima + `editMessageText`
- gruppi/topic: messaggio anteprima + `editMessageText`

Requisito:

- `channels.telegram.streaming` e `off | partial | block | progress` (predefinito: `partial`)
- `progress` mappa a `partial` su Telegram (compatibilita con naming cross-canale)
- i legacy `channels.telegram.streamMode` e valori booleani `streaming` vengono auto-mappati

Per risposte solo testo:

- DM: OpenClaw mantiene lo stesso messaggio anteprima e esegue una modifica finale sul posto (nessun secondo messaggio)
- gruppo/topic: OpenClaw mantiene lo stesso messaggio anteprima e esegue una modifica finale sul posto (nessun secondo messaggio)

Per risposte complesse (ad esempio payload media), OpenClaw torna alla consegna finale normale e poi pulisce il messaggio anteprima.

Lo streaming anteprima e separato dallo streaming a blocchi. Quando lo streaming a blocchi e esplicitamente abilitato per Telegram, OpenClaw salta lo streaming anteprima per evitare il doppio streaming.

Se il trasporto bozza nativo non e disponibile/rifiutato, OpenClaw torna automaticamente a `sendMessage` + `editMessageText`.

Stream ragionamento solo Telegram:

- `/reasoning stream` invia il ragionamento all'anteprima live durante la generazione
- la risposta finale viene inviata senza testo di ragionamento

Il testo in uscita usa `parse_mode: "HTML"` di Telegram.

- Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
- L'HTML raw del modello viene escaped per ridurre i fallimenti di parsing di Telegram.
- Se Telegram rifiuta l'HTML parsato, OpenClaw riprova come testo semplice.

Le anteprime link sono abilitate per impostazione predefinita e possono essere disabilitate con `channels.telegram.linkPreview: false`.

La registrazione del menu comandi Telegram e gestita all'avvio con `setMyCommands`.

Valori predefiniti comandi nativi:

- `commands.native: "auto"` abilita i comandi nativi per Telegram

Aggiungi voci personalizzate al menu comandi:

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

Regole:

- i nomi sono normalizzati (rimuovi `/` iniziale, minuscolo)
- pattern valido: `a-z`, `0-9`, `_`, lunghezza `1..32`
- i comandi personalizzati non possono sovrascrivere i comandi nativi
- conflitti/duplicati vengono saltati e registrati nel log

Note:

- i comandi personalizzati sono solo voci di menu; non implementano automaticamente il comportamento
- i comandi plugin/skill possono comunque funzionare quando digitati anche se non mostrati nel menu Telegram

Se i comandi nativi sono disabilitati, i comandi integrati vengono rimossi. I comandi personalizzati/plugin possono comunque registrarsi se configurati.

Fallimenti di setup comuni:

- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram ha ancora troppi comandi dopo il trimming; riduci i comandi plugin/skill/personalizzati o disabilita `channels.telegram.commands.native`.
- `setMyCommands failed` con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso `api.telegram.org` e bloccato.

### Comandi di pairing dispositivo (plugin `device-pair`)

Quando il plugin `device-pair` e installato:

1. `/pair` genera il codice di setup
2. incolla il codice nell'app iOS
3. `/pair approve` approva l'ultima richiesta in sospeso

Maggiori dettagli: [Pairing](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

Configura l'ambito della tastiera inline:

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

Override per account:

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

Ambiti:

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (predefinito)

Il legacy `capabilities: ["inlineButtons"]` mappa a `inlineButtons: "all"`.

Esempio azione messaggio:

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

I clic callback vengono passati all'agent come testo:
`callback_data: <valore>`

Le azioni strumento Telegram includono:

- `sendMessage` (`to`, `content`, opzionali `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, opzionali `iconColor`, `iconCustomEmojiId`)

Le azioni messaggio canale espongono alias ergonomici (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

Controlli di gating:

- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (predefinito: disabilitato)

Nota: `edit` e `topic-create` sono attualmente abilitati per impostazione predefinita e non hanno toggle `channels.telegram.actions.*` separati.
Gli invii runtime usano lo snapshot config/secrets attivo (avvio/ricarica), quindi i percorsi azione non eseguono ri-risoluzione SecretRef ad-hoc per invio.

Semantica rimozione reazione: [/tools/reactions](/docs/tools/reactions)

Telegram supporta tag di threading espliciti nel testo generato:

- `[[reply_to_current]]` risponde al messaggio trigger
- `[[reply_to:<id>]]` risponde a un ID messaggio Telegram specifico

`channels.telegram.replyToMode` controlla la gestione:

- `off` (predefinito)
- `first`
- `all`

Nota: `off` disabilita il threading implicito delle risposte. I tag espliciti `[[reply_to_*]]` vengono comunque rispettati.

Supergruppi forum:

- le chiavi di sessione dei topic appendono `:topic:<threadId>`
- risposte e typing puntano al thread del topic
- percorso config topic:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

Caso speciale topic generale (`threadId=1`):

- gli invii messaggi omettono `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`)
- le azioni typing includono comunque `message_thread_id`

Ereditarieta topic: le voci topic ereditano le impostazioni del gruppo a meno che non siano sovrascritte (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` e solo per topic e non eredita dai default del gruppo.

**Routing agent per topic**: ogni topic puo instradare a un agent diverso impostando `agentId` nella config topic. Questo da a ogni topic il proprio workspace, memoria e sessione isolati. Esempio:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Topic generale → agent main
            "3": { agentId: "zu" },        // Topic dev → agent zu
            "5": { agentId: "coder" }      // Code review → agent coder
          }
        }
      }
    }
  }
}
```

Ogni topic ha la propria chiave di sessione: `agent:zu:telegram:group:-1001234567890:topic:3`

**Binding ACP topic persistente**: i topic dei forum possono fissare sessioni harness ACP tramite binding ACP tipizzati top-level:

- `bindings[]` con `type: "acp"` e `match.channel: "telegram"`

Esempio:

```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,
            },
          },
        },
      },
    },
  },
}
```

Questo e attualmente limitato ai topic dei forum in gruppi e supergruppi.

**Spawn ACP thread-bound dalla chat**:

- `/acp spawn <agent> --thread here|auto` puo vincolare il topic Telegram corrente a una nuova sessione ACP.
- I messaggi successivi nel topic instradano direttamente alla sessione ACP vincolata (nessun `/acp steer` necessario).
- OpenClaw fissa il messaggio di conferma spawn nel topic dopo un bind riuscito.
- Richiede `channels.telegram.threadBindings.spawnAcpSessions=true`.

Il contesto template include:

- `MessageThreadId`
- `IsForum`

Comportamento thread DM:

- le chat private con `message_thread_id` mantengono il routing DM ma usano chiavi di sessione/target di risposta thread-aware.

### Messaggi audio

Telegram distingue le note vocali dai file audio.

- predefinito: comportamento file audio
- tag `[[audio_as_voice]]` nella risposta dell'agent per forzare l'invio come nota vocale

Esempio azione messaggio:

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

### Messaggi video

Telegram distingue i file video dalle note video.

Esempio azione messaggio:

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

Le note video non supportano didascalie; il testo del messaggio fornito viene inviato separatamente.

### Sticker

Gestione sticker in ingresso:

- WEBP statico: scaricato e elaborato (placeholder `<media:sticker>`)
- TGS animato: saltato
- WEBM video: saltato

Campi contesto sticker:

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

File cache sticker:

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

Gli sticker vengono descritti una volta (quando possibile) e messi in cache per ridurre le chiamate vision ripetute.

Abilita azioni sticker:

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

Azione invio sticker:

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

Ricerca sticker in cache:

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

Le reazioni Telegram arrivano come aggiornamenti `message_reaction` (separati dai payload messaggi).

Quando abilitato, OpenClaw accoda eventi di sistema come:

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

Config:

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

Note:

- `own` significa le reazioni utente solo ai messaggi inviati dal bot (best-effort tramite cache messaggi inviati).
- Gli eventi reazione rispettano comunque i controlli di accesso Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); i mittenti non autorizzati vengono scartati.
- Telegram non fornisce gli ID thread negli aggiornamenti reazione.
  - gruppi non-forum instradano alla sessione chat di gruppo
  - gruppi forum instradano alla sessione topic generale del gruppo (`:topic:1`), non al topic originario esatto

`allowed_updates` per polling/webhook include `message_reaction` automaticamente.

`ackReaction` invia un emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.

Ordine di risoluzione:

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

Note:

- Telegram si aspetta emoji unicode (ad esempio "👀").
- Usa `""` per disabilitare la reazione per un canale o account.

Le scritture config canale sono abilitate per impostazione predefinita (`configWrites !== false`).

Le scritture attivate da Telegram includono:

- eventi di migrazione gruppo (`migrate_to_chat_id`) per aggiornare `channels.telegram.groups`
- `/config set` e `/config unset` (richiede abilitazione comandi)

Disabilita:

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

Predefinito: long polling.

Modalita webhook:

- imposta `channels.telegram.webhookUrl`
- imposta `channels.telegram.webhookSecret` (necessario quando l'URL webhook e impostato)
- opzionale `channels.telegram.webhookPath` (predefinito `/telegram-webhook`)
- opzionale `channels.telegram.webhookHost` (predefinito `127.0.0.1`)
- opzionale `channels.telegram.webhookPort` (predefinito `8787`)

Il listener locale predefinito per la modalita webhook si associa a `127.0.0.1:8787`.

Se il tuo endpoint pubblico differisce, metti un reverse proxy davanti e punta `webhookUrl` all'URL pubblico.
Imposta `webhookHost` (ad esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno.

- `channels.telegram.textChunkLimit` predefinito e 4000.
- `channels.telegram.chunkMode="newline"` preferisce i confini di paragrafo (righe vuote) prima della divisione per lunghezza.
- `channels.telegram.mediaMaxMb` (predefinito 100) limita i media Telegram in ingresso e in uscita.
- `channels.telegram.timeoutSeconds` sovrascrive il timeout del client API Telegram (se non impostato, si applica il predefinito grammY).
- lo storico contesto di gruppo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predefinito 50); `0` disabilita.
- Controlli storico DM:
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- la config `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/strumenti/azioni) per errori API in uscita recuperabili.

Il target di invio CLI puo essere un ID chat numerico o username:

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

I sondaggi Telegram usano `openclaw message poll` e supportano i topic dei 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

Flag sondaggi solo Telegram:

- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` per topic dei forum (o usa un target `:topic:`)

Gating azioni:

- `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i sondaggi
- `channels.telegram.actions.poll=false` disabilita la creazione sondaggi Telegram mantenendo gli invii regolari abilitati

Telegram supporta le approvazioni exec nei DM dell'approvatore e puo opzionalmente pubblicare i prompt di approvazione nella chat o topic originario.

Percorso config:

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

Gli approvatori devono essere ID utente Telegram numerici. Quando `enabled` e false o `approvers` e vuoto, Telegram non agisce come client di approvazione exec. Le richieste di approvazione tornano ad altri percorsi di approvazione configurati o alla policy di fallback delle approvazioni exec.

Regole di consegna:

- `target: "dm"` invia i prompt di approvazione solo ai DM degli approvatori configurati
- `target: "channel"` invia il prompt nella chat/topic Telegram originario
- `target: "both"` invia ai DM degli approvatori e alla chat/topic originario

Solo gli approvatori configurati possono approvare o negare. I non-approvatori non possono usare `/approve` e non possono usare i bottoni di approvazione Telegram.

La consegna nel canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic sia per il prompt di approvazione che per il follow-up post-approvazione.

I bottoni di approvazione inline dipendono anche da `channels.telegram.capabilities.inlineButtons` che consenta la superficie target (`dm`, `group`, o `all`).

Documentazione correlata: [Approvazioni exec](/docs/tools/exec-approvals)

- Se `requireMention=false`, la modalita privacy Telegram deve consentire visibilita completa.
  - BotFather: `/setprivacy` -> Disable
  - poi rimuovi + ri-aggiungi il bot al gruppo
- `openclaw channels status` avvisa quando il config si aspetta messaggi di gruppo senza menzione.
- `openclaw channels status --probe` puo controllare ID gruppo numerici espliciti; il wildcard `"*"` non puo essere verificato per appartenenza.
- test rapido sessione: `/activation always`.

- quando `channels.telegram.groups` esiste, il gruppo deve essere elencato (o includere `"*"`)
- verifica l'appartenenza del bot al gruppo
- controlla i log: `openclaw logs --follow` per i motivi di skip

- autorizza la tua identita mittente (pairing e/o `allowFrom` numerico)
- l'autorizzazione comandi si applica comunque anche quando la policy di gruppo e `open`
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi plugin/skill/personalizzati o disabilita i menu nativi
- `setMyCommands failed` con errori di rete/fetch di solito indica problemi di raggiungibilita DNS/HTTPS verso `api.telegram.org`

- Node 22+ + fetch/proxy personalizzato possono causare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
- Alcuni host risolvono `api.telegram.org` prima in IPv6; l'egress IPv6 guasto puo causare fallimenti intermittenti delle API Telegram.
- Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora riprova questi come errori di rete recuperabili.
- Su host VPS con egress diretto/TLS instabile, instrada le chiamate API Telegram attraverso `channels.telegram.proxy`:

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

- Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (tranne WSL2) e `dnsResultOrder=ipv4first`.
- Se il tuo host e WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione famiglia:

channels:
  telegram:
    network:
      autoSelectFamily: false

- Override di ambiente (temporanei):
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Valida le risposte DNS:

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