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)
• progress mantiene una bozza di stato modificabile per l’avanzamento degli strumenti, la cancella al completamento e invia la risposta finale come messaggio normale
• streaming.preview.toolProgress controlla se gli aggiornamenti di strumenti/avanzamento riutilizzano lo stesso messaggio di anteprima modificato (predefinito: true quando lo streaming dell’anteprima è attivo)
• streaming.preview.commandText controlla i dettagli di comando/exec dentro quelle righe di avanzamento degli strumenti: raw (predefinito, preserva il comportamento rilasciato) o status (solo etichetta dello strumento)
• i valori legacy channels.telegram.streamMode e booleani streaming vengono rilevati; esegui openclaw doctor --fix per migrarli a channels.telegram.streaming.mode

{
  "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 in DM/gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue la modifica finale sul posto
• i finali di testo lunghi che vengono divisi in più messaggi Telegram riutilizzano l’anteprima esistente come primo frammento finale quando possibile, poi inviano solo i frammenti rimanenti
• i finali in modalità progress cancellano la bozza di stato e usano la normale consegna finale invece di modificare la bozza 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 invia il reasoning all’anteprima live durante la generazione
• l’anteprima del reasoning viene eliminata dopo la consegna finale; usa /reasoning on quando il reasoning deve rimanere visibile
• la risposta finale viene inviata senza testo di reasoning

• Il testo simile a Markdown viene renderizzato in HTML sicuro per Telegram.
• I tag HTML supportati da Telegram vengono preservati; l’HTML non supportato viene sottoposto a escape.
• Se Telegram rifiuta l’HTML analizzato, OpenClaw riprova come testo semplice.

• 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 (rimozione dello / iniziale, minuscole)
• 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 un comportamento
• i comandi di Plugin/skill possono comunque funzionare quando vengono digitati, anche se non sono 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 di Plugin/skill/personalizzati o disabilita channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands o setMyCommands non riusciti con 404: Not Found mentre i comandi curl diretti della Bot API funzionano possono significare che channels.telegram.apiRoot è stato impostato sull’endpoint completo /bot<TOKEN>. apiRoot deve essere solo la radice della 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 del 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/scopes)
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" }],
  ],
}

• sendMessage (to, content, opzionale mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, opzionale iconColor, 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 attivante
• [[reply_to:<id>]] risponde a un ID messaggio Telegram specifico

• off (predefinito)
• first
• all

• le chiavi di sessione dei topic aggiungono :topic:<threadId>
• le risposte e la digitazione hanno come destinazione il thread del topic
• percorso di configurazione del topic: 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 sono incorniciate come testo generato da macchina, non attendibile, nel contesto dell’agente; il rilevamento delle menzioni usa comunque la trascrizione grezza, quindi i messaggi vocali filtrati per 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: saltato
• WEBM video: saltato

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

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

{
  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 instradati alla sessione della chat di gruppo
  • i gruppi forum vengono instradati alla sessione del topic generale del gruppo (:topic:1), non al topic esatto di origine

• 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 (per 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 dei paragrafi (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 media di Telegram vengono bufferizzati prima che OpenClaw li invii come un unico messaggio in ingresso. Aumentalo se 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 predefinito di grammY). I client bot limitano i valori configurati sotto la protezione di 60 secondi per richieste di testo/typing in uscita, così grammY non interrompe la consegna visibile della risposta prima che la protezione di trasporto e il fallback di OpenClaw possano eseguire. Il long polling usa comunque una protezione di 45 secondi per la richiesta getUpdates, così i poll inattivi non vengono abbandonati indefinitamente.
• channels.telegram.pollingStallThresholdMs ha valore predefinito 120000; regolalo tra 30000 e 600000 solo per riavvii da stallo del polling 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 una finestra di contesto conversazionale selezionata quando il Gateway ha osservato i messaggi padre; la cache dei messaggi osservati viene persistita accanto allo store di sessione. 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 controllano principalmente chi può attivare l’agente, non sono un confine completo di redazione del contesto supplementare.
• Controlli della cronologia 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 safe-send retry limitato per errori Telegram prima della connessione, ma non ritenta envelope di rete ambigui dopo l’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 i topic 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 in quella chat
• --force-document per inviare immagini, GIF e video in uscita come documenti invece che come foto compressa, media animato o caricamenti video

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

• 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 -> Disabilita
  • quindi rimuovi e aggiungi di nuovo il bot al gruppo
• openclaw channels status avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
• openclaw channels status --probe può controllare ID di gruppo numerici espliciti; il wildcard "*" non può essere verificato tramite probing dell’appartenenza.
• test rapido della sessione: /activation always.

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

• autorizza l’identità del mittente (associazione 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 comandi plugin/skill/personalizzati oppure disabilita i menu nativi
• le chiamate di avvio deleteMyCommands / setMyCommands e le chiamate di digitazione sendChatAction sono limitate e riprovano 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 del bot configurato.
• Ricopia o rigenera il token del 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 esistente” rinvierebbe soltanto lo stesso errore di token non valido alle 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 li ritenta come errori di rete recuperabili.
• Durante l’avvio del polling, OpenClaw riutilizza il probe getMe di avvio riuscito per grammY, così il runner non deve eseguire un secondo getMe prima del primo getUpdates.
• Se deleteWebhook fallisce con un errore di rete transitorio durante l’avvio del polling, OpenClaw continua con il long polling invece di effettuare un’altra chiamata di control plane prima del polling. 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 con una cadenza fissa breve, controlla se channels.telegram.timeoutSeconds è basso; i client bot limitano i valori configurati sotto le guardie delle richieste in uscita e getUpdates, ma le versioni precedenti potevano interrompere ogni poll o risposta quando questo valore era impostato sotto tali guardie.
• Se i log includono Polling stall detected, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness di long-poll completata per impostazione predefinita.
• openclaw channels status --probe e openclaw doctor avvisano quando un account di polling in esecuzione non ha completato getUpdates dopo il periodo di grazia dell’avvio, quando un account webhook in esecuzione non ha completato setWebhook dopo il periodo di grazia dell’avvio, oppure quando l’ultima attività riuscita del trasporto di polling è obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo quando le chiamate getUpdates di lunga durata sono sane ma il tuo host segnala ancora falsi riavvii per stallo del polling. Stalli persistenti di solito indicano problemi di proxy, DNS, IPv6 o egress TLS tra l’host e api.telegram.org.
• Telegram rispetta anche le env proxy del processo per il trasporto Bot API, incluse HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le relative 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 env proxy standard, Telegram usa quell’URL anche per il trasporto Bot API.
• Su host VPS con egress/TLS diretto instabile, instrada le chiamate all’API Telegram tramite channels.telegram.proxy:

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

• Node 22+ usa per impostazione predefinita autoSelectFamily=true (eccetto WSL2). L’ordine dei risultati DNS di Telegram rispetta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, poi channels.telegram.network.dnsResultOrder, poi il predefinito del processo come 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 comportamento solo IPv4, forza la selezione della famiglia:

channels:
  telegram:
    network:
      autoSelectFamily: false

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

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

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

• 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