Telegram

• disabilitare la modalità privacy tramite /setprivacy, oppure
• rendere il bot amministratore del gruppo.

• /setjoingroups per consentire/negare l’aggiunta ai gruppi
• /setprivacy per il comportamento di visibilità nei gruppi

• chat dirette: messaggio di anteprima + editMessageText
• gruppi/argomenti: messaggio di anteprima + editMessageText

• channels.telegram.streaming è off | partial | block | progress (predefinito: partial)
• le brevi anteprime iniziali delle risposte sono sottoposte a debounce, poi materializzate dopo un ritardo limitato se l’esecuzione è ancora attiva
• progress mantiene una bozza di stato modificabile per l’avanzamento degli strumenti, mostra l’etichetta di stato stabile quando arriva attività di risposta prima dell’avanzamento degli strumenti, la cancella al completamento e invia la risposta finale come messaggio normale
• streaming.preview.toolProgress controlla se gli aggiornamenti di strumento/avanzamento riutilizzano lo stesso messaggio di anteprima modificato (predefinito: true quando lo streaming di anteprima è attivo)
• streaming.preview.commandText controlla i dettagli comando/exec all’interno di quelle righe di avanzamento strumenti: raw (predefinito, preserva il comportamento rilasciato) o status (solo etichetta dello strumento)
• streaming.progress.commentary (predefinito: false) abilita il testo di commento/preambolo dell’assistente nella bozza temporanea di avanzamento
• le chiavi legacy channels.telegram.streamMode, i valori booleani di streaming e le chiavi ritirate di anteprima bozza nativa vengono rilevati; esegui openclaw doctor --fix per migrarli alla configurazione di streaming corrente

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

• anteprime brevi DM/gruppo/argomento: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue la modifica finale sul posto
• i finali di testo lunghi che si dividono in più messaggi Telegram riutilizzano l’anteprima esistente come primo blocco finale quando possibile, poi inviano solo i blocchi rimanenti
• i finali in modalità progress cancellano la bozza di stato e usano la normale consegna finale invece di modificare la bozza trasformandola nella risposta
• se la modifica finale fallisce prima che il testo completato sia confermato, OpenClaw usa la normale consegna finale e pulisce l’anteprima obsoleta

• /reasoning stream usa il percorso di anteprima del ragionamento di un canale supportato; su Telegram, trasmette il ragionamento nell’anteprima live durante la generazione
• l’anteprima del ragionamento viene eliminata dopo la consegna finale; usa /reasoning on quando il ragionamento deve restare visibile
• la risposta finale viene inviata senza testo di ragionamento

{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}

• All’agente viene comunicato che i messaggi rich Telegram sono disponibili per questo bot/account.
• Il testo Markdown viene renderizzato attraverso la IR Markdown di OpenClaw e inviato come HTML rich Telegram.
• I payload HTML rich espliciti preservano i tag supportati da Bot API 10.1 come titoli, tabelle, dettagli, rich media e formule.
• Le didascalie dei media usano ancora le didascalie HTML Telegram perché i messaggi rich non sostituiscono le didascalie.

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

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

• i nomi vengono 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 nei log

• 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

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu Telegram ha comunque superato il limite dopo il trimming; riduci i comandi plugin/skill/personalizzati o disabilita channels.telegram.commands.native.
• Il fallimento di deleteWebhook, deleteMyCommands o setMyCommands con 404: Not Found mentre i comandi curl diretti di Bot API funzionano può significare che channels.telegram.apiRoot è stato impostato sull’endpoint completo /bot<TOKEN>. apiRoot deve essere solo la root di Bot API, e openclaw doctor --fix rimuove un /bot<TOKEN> finale accidentale.
• getMe returned 401 significa che Telegram ha rifiutato il token bot configurato. Aggiorna botToken, tokenFile o TELEGRAM_BOT_TOKEN con il token BotFather corrente; OpenClaw si ferma prima del polling, quindi questo non viene segnalato come errore di pulizia Webhook.
• setMyCommands failed con errori di rete/fetch di solito significa che DNS/HTTPS in uscita verso api.telegram.org è bloccato.

​

Comandi di associazione dispositivo (plugin device-pair)

1. /pair genera il codice di configurazione
2. incolla il codice nell’app iOS
3. /pair pending elenca le richieste in sospeso (inclusi ruolo/ambiti)
4. approva la richiesta:
   • /pair approve <requestId> per approvazione esplicita
   • /pair approve quando c’è una sola richiesta in sospeso
   • /pair approve latest per la più recente

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

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

• off
• dm
• group
• all
• allowlist (predefinito)

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, mediaUrl opzionale, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content o caption, pulsanti inline presentation opzionali; le modifiche dei soli pulsanti aggiornano il markup di risposta)
• createForumTopic (chatId, name, iconColor opzionale, iconCustomEmojiId)

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

• [[reply_to_current]] risponde al messaggio che ha attivato l’azione
• [[reply_to:<id>]] risponde a uno specifico ID messaggio Telegram

• off (predefinito)
• first
• all

• le chiavi di sessione degli argomenti aggiungono :topic:<threadId>
• risposte e digitazione hanno come destinazione il thread dell’argomento
• percorso di configurazione dell’argomento: channels.telegram.groups.<chatId>.topics.<threadId>

• gli invii di messaggi omettono message_thread_id (Telegram rifiuta sendMessage(...thread_id=1))
• le azioni di digitazione includono comunque message_thread_id

{
  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
          }
        }
      }
    }
  }
}

​

Messaggi audio

• predefinito: comportamento da file audio
• tag [[audio_as_voice]] nella risposta dell’agente per forzare l’invio come nota vocale
• le trascrizioni delle note vocali in ingresso vengono incorniciate come testo generato da macchina e non attendibile nel contesto dell’agente; il rilevamento delle menzioni usa comunque la trascrizione grezza, quindi i messaggi vocali soggetti a gate di menzione continuano a funzionare.

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

​

Messaggi video

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

​

Sticker

• WEBP statico: scaricato ed elaborato (placeholder <media:sticker>)
• TGS animato: ignorato
• WEBM video: ignorato

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

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

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

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

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

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

• own indica solo le reazioni degli utenti ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati).
• Gli eventi di reazione rispettano comunque i controlli di accesso di Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); i mittenti non autorizzati vengono scartati.
• Telegram non fornisce ID di thread negli aggiornamenti delle reazioni.
  • i gruppi non forum vengono indirizzati alla sessione della chat di gruppo
  • i gruppi forum vengono indirizzati alla sessione dell’argomento generale del gruppo (:topic:1), non all’argomento di origine esatto

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback all’emoji dell’identità dell’agente (agents.list[].identity.emoji, altrimenti ”👀”)

• Telegram si aspetta emoji Unicode (ad esempio ”👀”).
• Usa "" per disabilitare la reazione per un canale o un account.

• eventi di migrazione dei gruppi (migrate_to_chat_id) per aggiornare channels.telegram.groups
• /config set e /config unset (richiede l’abilitazione dei comandi)

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

• Il valore predefinito di channels.telegram.textChunkLimit è 4000.
• channels.telegram.chunkMode="newline" preferisce i confini di paragrafo (righe vuote) prima della suddivisione per lunghezza.
• channels.telegram.mediaMaxMb (predefinito 100) limita la dimensione dei media Telegram in ingresso e in uscita.
• channels.telegram.mediaGroupFlushMs (predefinito 500) controlla per quanto tempo gli album/gruppi multimediali Telegram vengono bufferizzati prima che OpenClaw li invii come un unico messaggio in ingresso. Aumentalo se le parti dell’album arrivano in ritardo; diminuiscilo per ridurre la latenza delle risposte agli album.
• channels.telegram.timeoutSeconds sovrascrive il timeout del client API Telegram (se non impostato, si applica il valore predefinito di grammY). I client bot limitano i valori configurati al di sotto della guardia di 60 secondi per le richieste di testo/typing in uscita, in modo che grammY non interrompa la consegna della risposta visibile prima che la guardia di trasporto e il fallback di OpenClaw possano essere eseguiti. Il long polling usa comunque una guardia di 45 secondi per le richieste getUpdates, così i polling inattivi non vengono abbandonati indefinitamente.
• channels.telegram.pollingStallThresholdMs è predefinito a 120000; regolalo tra 30000 e 600000 solo per riavvii da polling bloccato falsi positivi.
• la cronologia del contesto di gruppo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (predefinito 50); 0 disabilita.
• il contesto supplementare di risposta/citazione/inoltro viene normalizzato in un’unica finestra di contesto conversazionale selezionata quando il Gateway ha osservato i messaggi principali; la cache dei messaggi osservati risiede nello stato Plugin SQLite di OpenClaw e openclaw doctor --fix importa i sidecar legacy. Telegram include negli aggiornamenti solo un reply_to_message superficiale, quindi le catene più vecchie della cache sono limitate al payload di aggiornamento corrente di Telegram.
• le allowlist Telegram regolano principalmente chi può attivare l’agente, non un confine completo di oscuramento del contesto supplementare.
• Controlli della cronologia dei DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• La configurazione channels.telegram.retry si applica agli helper di invio Telegram (CLI/strumenti/azioni) per errori API in uscita recuperabili. Anche la consegna della risposta finale in ingresso usa un retry safe-send limitato per errori Telegram precedenti alla connessione, ma non ritenta envelope di rete ambigui successivi all’invio che potrebbero duplicare messaggi visibili.

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

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id per argomenti forum (oppure usa un target :topic:)

• --presentation con blocchi buttons per tastiere inline quando channels.telegram.capabilities.inlineButtons lo consente
• --pin o --delivery '{"pin":true}' per richiedere la consegna fissata quando il bot può fissare messaggi in quella chat
• --force-document per inviare immagini, GIF e video in uscita come documenti invece che come caricamenti foto compressa, media animato o video

• channels.telegram.actions.sendMessage=false disabilita i messaggi Telegram in uscita, inclusi i sondaggi
• channels.telegram.actions.poll=false disabilita la creazione di sondaggi Telegram lasciando abilitati gli invii normali

• channels.telegram.execApprovals.enabled (si abilita automaticamente quando almeno un approvatore è risolvibile)
• channels.telegram.execApprovals.approvers (ripiega sugli ID owner numerici da commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (predefinito) | channel | both
• agentFilter, sessionFilter

• Se requireMention=false, la modalità privacy di Telegram deve consentire visibilità completa.
  • BotFather: /setprivacy -> Disable
  • quindi rimuovi e riaggiungi il bot al gruppo
• openclaw channels status avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
• openclaw channels status --probe può controllare ID gruppo numerici espliciti; il carattere jolly "*" non può essere verificato tramite membership-probe.
• test rapido della sessione: /activation always.

• quando channels.telegram.groups esiste, il gruppo deve essere elencato (oppure includere "*")
• verifica l’appartenenza del bot al gruppo
• esamina i log: openclaw logs --follow per i motivi di salto

• autorizza la tua identità mittente (abbinamento e/o allowFrom numerico)
• l’autorizzazione dei comandi si applica comunque anche quando la policy del gruppo è open
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa che il menu nativo ha troppe voci; riduci i comandi Plugin/skill/personalizzati oppure disabilita i menu nativi
• le chiamate di avvio deleteMyCommands / setMyCommands e le chiamate di typing sendChatAction sono limitate e ritentano una volta tramite il fallback di trasporto di Telegram in caso di timeout della richiesta. Errori persistenti di rete/fetch di solito indicano problemi di raggiungibilità DNS/HTTPS verso api.telegram.org

• getMe returned 401 è un errore di autenticazione Telegram per il token bot configurato.
• Ricopia o rigenera il token bot in BotFather, quindi aggiorna channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken o TELEGRAM_BOT_TOKEN per l’account predefinito.
• Anche deleteWebhook 401 Unauthorized durante l’avvio è un errore di autenticazione; trattarlo come “nessun Webhook esiste” rimanderebbe solo lo stesso errore di token non valido a chiamate API successive.

• Node 22+ + fetch/proxy personalizzato può attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
• Alcuni host risolvono prima api.telegram.org in IPv6; un egress IPv6 non funzionante può causare errori intermittenti dell’API Telegram.
• Se i log includono TypeError: fetch failed o Network request for 'getUpdates' failed!, OpenClaw ora ritenta questi casi come errori di rete recuperabili.
• Durante l’avvio del polling, OpenClaw riusa la sonda getMe di avvio riuscita per grammY, così il runner non ha bisogno di un secondo getMe prima del primo getUpdates.
• Se deleteWebhook fallisce con un errore di rete transitorio durante l’avvio del polling, OpenClaw prosegue nel long polling invece di effettuare un’altra chiamata control-plane pre-poll. Un Webhook ancora attivo emerge come conflitto di getUpdates; OpenClaw quindi ricostruisce il trasporto Telegram e ritenta la pulizia del Webhook.
• Se i socket Telegram vengono riciclati a una cadenza fissa breve, controlla se channels.telegram.timeoutSeconds è basso; i client bot limitano i valori configurati al di sotto delle guardie delle richieste in uscita e getUpdates, ma le versioni precedenti potevano interrompere ogni polling o risposta quando questo valore era impostato al di sotto di tali guardie.
• Se i log includono Polling stall detected, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness completata del long-poll per impostazione predefinita.
• openclaw channels status --probe e openclaw doctor avvisano quando un account polling in esecuzione non ha completato getUpdates dopo il periodo di tolleranza all’avvio, quando un account Webhook in esecuzione non ha completato setWebhook dopo il periodo di tolleranza all’avvio, oppure quando l’ultima attività riuscita del trasporto di polling è obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo quando le chiamate getUpdates a lunga durata sono sane ma il tuo host segnala comunque falsi riavvii da polling bloccato. Blocchi persistenti di solito indicano problemi di proxy, DNS, IPv6 o egress TLS tra l’host e api.telegram.org.
• Telegram rispetta anche le variabili env proxy di processo per il trasporto Bot API, incluse HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le rispettive varianti minuscole. NO_PROXY / no_proxy può comunque bypassare api.telegram.org.
• Se il proxy gestito da OpenClaw è configurato tramite OPENCLAW_PROXY_URL per un ambiente di servizio e non è presente alcuna variabile env proxy standard, Telegram usa quell’URL anche per il trasporto Bot API.
• Su host VPS con egress/TLS diretto instabile, instrada le chiamate API Telegram tramite channels.telegram.proxy:

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

• Node 22+ usa per impostazione predefinita autoSelectFamily=true (tranne WSL2). L’ordine dei risultati DNS di Telegram rispetta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, poi channels.telegram.network.dnsResultOrder, poi il valore predefinito del processo, ad esempio NODE_OPTIONS=--dns-result-order=ipv4first; se nessuno si applica, Node 22+ ripiega su ipv4first.
• Se il tuo host è WSL2 o funziona esplicitamente meglio con il comportamento solo IPv4, forza la selezione della famiglia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Le risposte nell’intervallo di benchmark RFC 2544 (198.18.0.0/15) sono già consentite per impostazione predefinita per i download dei media di Telegram. Se un fake-IP attendibile o un proxy trasparente riscrive api.telegram.org in qualche altro indirizzo privato/interno/a uso speciale durante i download dei media, puoi aderire al bypass solo per Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La stessa adesione è disponibile per account in channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se il tuo proxy risolve gli host dei media Telegram in 198.18.x.x, lascia prima disattivato il flag pericoloso. I media Telegram consentono già l’intervallo di benchmark RFC 2544 per impostazione predefinita.

• Override di ambiente (temporanei):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Convalida le risposte DNS:

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