Telegram

• schakel de privacymodus uit via /setprivacy, of
• maak de bot groepsbeheerder.

• /setjoingroups om toevoegen aan groepen toe te staan/te weigeren
• /setprivacy voor gedrag rond zichtbaarheid in groepen

• directe chats: voorbeeldbericht + editMessageText
• groepen/onderwerpen: voorbeeldbericht + editMessageText

• channels.telegram.streaming is off | partial | block | progress (standaard: partial)
• progress behoudt één bewerkbaar statusconcept voor toolvoortgang, wist dit bij voltooiing en verzendt het uiteindelijke antwoord als een normaal bericht
• streaming.preview.toolProgress bepaalt of tool-/voortgangsupdates hetzelfde bewerkte voorbeeldbericht opnieuw gebruiken (standaard: true wanneer voorbeeldstreaming actief is)
• streaming.preview.commandText bepaalt opdracht-/exec-details binnen die toolvoortgangsregels: raw (standaard, behoudt uitgebracht gedrag) of status (alleen toollabel)
• verouderde waarden channels.telegram.streamMode en booleaanse streaming-waarden worden gedetecteerd; voer openclaw doctor --fix uit om ze te migreren naar 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"
        }
      }
    }
  }
}

• korte voorbeelden in DM/groep/topic: OpenClaw behoudt hetzelfde voorbeeldbericht en voert de uiteindelijke bewerking ter plaatse uit
• lange tekstfinales die in meerdere Telegram-berichten worden opgesplitst, gebruiken het bestaande voorbeeld waar mogelijk opnieuw als het eerste uiteindelijke deel en verzenden daarna alleen de resterende delen
• finales in voortgangsmodus wissen het statusconcept en gebruiken normale uiteindelijke levering in plaats van het concept in het antwoord te bewerken
• als de uiteindelijke bewerking mislukt voordat de voltooide tekst is bevestigd, gebruikt OpenClaw normale uiteindelijke levering en ruimt het verouderde voorbeeld op

• /reasoning stream verzendt redenering naar het livevoorbeeld tijdens het genereren
• het redeneringsvoorbeeld wordt verwijderd na uiteindelijke levering; gebruik /reasoning on wanneer redenering zichtbaar moet blijven
• het uiteindelijke antwoord wordt zonder redeneringstekst verzonden

• Markdown-achtige tekst wordt gerenderd naar Telegram-veilige HTML.
• Ondersteunde Telegram-HTML-tags blijven behouden; niet-ondersteunde HTML wordt geëscapet.
• Als Telegram geparste HTML weigert, probeert OpenClaw het opnieuw als platte tekst.

• commands.native: "auto" schakelt native opdrachten in voor Telegram

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

• namen worden genormaliseerd (voorloop-/ verwijderen, naar kleine letters)
• geldig patroon: a-z, 0-9, _, lengte 1..32
• aangepaste opdrachten kunnen native opdrachten niet overschrijven
• conflicten/duplicaten worden overgeslagen en gelogd

• aangepaste opdrachten zijn alleen menu-items; ze implementeren niet automatisch gedrag
• plugin-/skill-opdrachten kunnen nog steeds werken wanneer ze worden getypt, zelfs als ze niet in het Telegram-menu worden weergegeven

• setMyCommands failed met BOT_COMMANDS_TOO_MUCH betekent dat het Telegram-menu na inkorten nog steeds te vol was; verminder plugin-/skill-/aangepaste opdrachten of schakel channels.telegram.commands.native uit.
• deleteWebhook, deleteMyCommands of setMyCommands die mislukt met 404: Not Found terwijl directe Bot API-curlopdrachten werken, kan betekenen dat channels.telegram.apiRoot was ingesteld op het volledige /bot<TOKEN>-eindpunt. apiRoot mag alleen de Bot API-root zijn, en openclaw doctor --fix verwijdert een per ongeluk toegevoegde afsluitende /bot<TOKEN>.
• getMe returned 401 betekent dat Telegram de geconfigureerde bottoken heeft geweigerd. Werk botToken, tokenFile of TELEGRAM_BOT_TOKEN bij met de huidige BotFather-token; OpenClaw stopt vóór polling, zodat dit niet als een webhook-opruimfout wordt gerapporteerd.
• setMyCommands failed met netwerk-/fetchfouten betekent meestal dat uitgaande DNS/HTTPS naar api.telegram.org is geblokkeerd.

​

Opdrachten voor apparaatkoppeling (device-pair-plugin)

1. /pair genereert installatiecode
2. plak code in iOS-app
3. /pair pending geeft openstaande aanvragen weer (inclusief rol/scopes)
4. keur de aanvraag goed:
   • /pair approve <requestId> voor expliciete goedkeuring
   • /pair approve wanneer er slechts één openstaande aanvraag is
   • /pair approve latest voor de meest recente

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

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

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

{
  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, optioneel mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, optioneel iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (standaard: uitgeschakeld)

• [[reply_to_current]] antwoordt op het activerende bericht
• [[reply_to:<id>]] antwoordt op een specifiek Telegram-bericht-ID

• off (standaard)
• first
• all

• topic-sessiesleutels voegen :topic:<threadId> toe
• antwoorden en typen richten zich op de topicthread
• configuratiepad voor topic: channels.telegram.groups.<chatId>.topics.<threadId>

• berichtverzendingen laten message_thread_id weg (Telegram weigert sendMessage(...thread_id=1))
• typeacties bevatten nog steeds 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
          }
        }
      }
    }
  }
}

​

Audioberichten

• standaard: gedrag voor audiobestanden
• tag [[audio_as_voice]] in het antwoord van de agent om verzending als spraaknotitie af te dwingen
• inkomende transcripties van spraaknotities worden in de agentcontext omlijst als machinaal gegenereerde, niet-vertrouwde tekst; vermeldingsdetectie gebruikt nog steeds de ruwe transcriptie, zodat vermeldingsgebonden spraakberichten blijven werken.

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

​

Videoberichten

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

​

Stickers

• statische WEBP: gedownload en verwerkt (placeholder <media:sticker>)
• geanimeerde TGS: overgeslagen
• video-WEBM: overgeslagen

• 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 (standaard: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (standaard: minimal)

• own betekent alleen gebruikersreacties op door de bot verzonden berichten (best-effort via de cache voor verzonden berichten).
• Reactiegebeurtenissen respecteren nog steeds Telegram-toegangscontroles (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); onbevoegde afzenders worden genegeerd.
• Telegram levert geen thread-ID’s in reactie-updates.
  • niet-forumgroepen routeren naar de groepschatsessie
  • forumgroepen routeren naar de algemene-onderwerpsessie van de groep (:topic:1), niet naar het exacte oorspronkelijke onderwerp

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback naar de emoji van de agentidentiteit (agents.list[].identity.emoji, anders ”👀”)

• Telegram verwacht unicode-emoji (bijvoorbeeld ”👀”).
• Gebruik "" om de reactie voor een kanaal of account uit te schakelen.

• groepsmigratiegebeurtenissen (migrate_to_chat_id) om channels.telegram.groups bij te werken
• /config set en /config unset (vereist dat opdrachten zijn ingeschakeld)

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

• channels.telegram.textChunkLimit is standaard 4000.
• channels.telegram.chunkMode="newline" geeft de voorkeur aan alineagrenzen (lege regels) vóór splitsing op lengte.
• channels.telegram.mediaMaxMb (standaard 100) begrenst de grootte van inkomende en uitgaande Telegram-media.
• channels.telegram.mediaGroupFlushMs (standaard 500) bepaalt hoelang Telegram-albums/mediagroepen worden gebufferd voordat OpenClaw ze als één inkomend bericht verzendt. Verhoog dit als albumdelen laat aankomen; verlaag dit om albumantwoordlatentie te verminderen.
• channels.telegram.timeoutSeconds overschrijft de timeout van de Telegram API-client (als dit niet is ingesteld, geldt de grammY-standaard). Botclients klemmen geconfigureerde waarden onder de 60-secondenrequest-guard voor uitgaande tekst/typen, zodat grammY de zichtbare antwoordaflevering niet afbreekt voordat de transport-guard en fallback van OpenClaw kunnen draaien. Long polling gebruikt nog steeds een 45-secondenrequest-guard voor getUpdates, zodat inactieve polls niet onbeperkt worden verlaten.
• channels.telegram.pollingStallThresholdMs is standaard 120000; stel alleen af tussen 30000 en 600000 voor fout-positieve herstarts door polling-stalls.
• groepscontexthistorie gebruikt channels.telegram.historyLimit of messages.groupChat.historyLimit (standaard 50); 0 schakelt dit uit.
• aanvullende context voor antwoord/citaat/doorsturen wordt genormaliseerd naar één geselecteerd conversatiecontextvenster wanneer de gateway de bovenliggende berichten heeft waargenomen; de cache voor waargenomen berichten wordt naast de sessieopslag bewaard. Telegram bevat slechts één oppervlakkige reply_to_message in updates, dus ketens die ouder zijn dan de cache zijn beperkt tot de huidige updatepayload van Telegram.
• Telegram-allowlists begrenzen primair wie de agent kan triggeren, niet een volledige redactieboundary voor aanvullende context.
• DM-historiebesturing:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• De configuratie channels.telegram.retry is van toepassing op Telegram-verzendhelpers (CLI/tools/acties) voor herstelbare uitgaande API-fouten. Aflevering van inkomende eindantwoorden gebruikt ook een begrensde safe-send-retry voor Telegram-pre-connect-fouten, maar probeert ambigue post-send-netwerkenveloppen die zichtbare berichten kunnen dupliceren niet opnieuw.

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 voor forumonderwerpen (of gebruik een :topic:-doel)

• --presentation met buttons-blokken voor inline keyboards wanneer channels.telegram.capabilities.inlineButtons dit toestaat
• --pin of --delivery '{"pin":true}' om vastgezette aflevering aan te vragen wanneer de bot in die chat kan vastzetten
• --force-document om uitgaande afbeeldingen, GIF’s en video’s als documenten te verzenden in plaats van als gecomprimeerde foto-, geanimeerde-media- of video-uploads

• channels.telegram.actions.sendMessage=false schakelt uitgaande Telegram-berichten uit, inclusief polls
• channels.telegram.actions.poll=false schakelt het maken van Telegram-polls uit, terwijl reguliere verzendingen ingeschakeld blijven

• channels.telegram.execApprovals.enabled (wordt automatisch ingeschakeld wanneer ten minste één goedkeurder oplosbaar is)
• channels.telegram.execApprovals.approvers (valt terug op numerieke eigenaar-ID’s uit commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (standaard) | channel | both
• agentFilter, sessionFilter

• Als requireMention=false, moet de privacymodus van Telegram volledige zichtbaarheid toestaan.
  • BotFather: /setprivacy -> Disable
  • verwijder de bot daarna uit de groep en voeg deze opnieuw toe
• openclaw channels status waarschuwt wanneer de configuratie niet-genoemde groepsberichten verwacht.
• openclaw channels status --probe kan expliciete numerieke groeps-ID’s controleren; wildcard "*" kan niet op lidmaatschap worden gecontroleerd.
• snelle sessietest: /activation always.

• wanneer channels.telegram.groups bestaat, moet de groep worden vermeld (of "*" bevatten)
• controleer het botlidmaatschap in de groep
• bekijk logs: openclaw logs --follow voor redenen waarom iets wordt overgeslagen

• autoriseer je afzenderidentiteit (koppeling en/of numerieke allowFrom)
• commandoautorisatie blijft van toepassing, zelfs wanneer het groepsbeleid open is
• setMyCommands failed met BOT_COMMANDS_TOO_MUCH betekent dat het native menu te veel items heeft; verminder plugin-/skill-/aangepaste commando’s of schakel native menu’s uit
• deleteMyCommands / setMyCommands-aanroepen bij opstarten en sendChatAction-typaanroepen zijn begrensd en proberen één keer opnieuw via Telegram’s transportfallback bij een request-time-out. Aanhoudende netwerk-/fetchfouten wijzen meestal op DNS-/HTTPS-bereikbaarheidsproblemen naar api.telegram.org

• getMe returned 401 is een Telegram-authenticatiefout voor het geconfigureerde bottoken.
• Kopieer het bottoken opnieuw of genereer het opnieuw in BotFather, en werk daarna channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken of TELEGRAM_BOT_TOKEN bij voor het standaardaccount.
• deleteWebhook 401 Unauthorized tijdens het opstarten is ook een authenticatiefout; dit behandelen als “er bestaat geen Webhook” zou dezelfde fout door een ongeldig token alleen uitstellen tot latere API-aanroepen.

• Node 22+ + aangepaste fetch/proxy kan direct afbreekgedrag veroorzaken als AbortSignal-typen niet overeenkomen.
• Sommige hosts lossen api.telegram.org eerst op naar IPv6; kapotte IPv6-egress kan intermitterende Telegram API-fouten veroorzaken.
• Als logs TypeError: fetch failed of Network request for 'getUpdates' failed! bevatten, probeert OpenClaw deze nu opnieuw als herstelbare netwerkfouten.
• Tijdens het starten van polling hergebruikt OpenClaw de succesvolle opstartprobe getMe voor grammY, zodat de runner geen tweede getMe nodig heeft vóór de eerste getUpdates.
• Als deleteWebhook faalt met een tijdelijke netwerkfout tijdens het starten van polling, gaat OpenClaw door met long polling in plaats van nog een pre-poll control-plane-aanroep te doen. Een nog actieve Webhook verschijnt als een getUpdates-conflict; OpenClaw bouwt daarna het Telegram-transport opnieuw op en probeert de Webhook-opruiming opnieuw.
• Als Telegram-sockets op een korte vaste cadans worden gerecycled, controleer dan op een lage channels.telegram.timeoutSeconds; botclients klemmen geconfigureerde waarden onder de uitgaande en getUpdates-requestguards, maar oudere releases konden elke poll of elk antwoord afbreken wanneer dit onder die guards was ingesteld.
• Als logs Polling stall detected bevatten, herstart OpenClaw polling en bouwt het Telegram-transport opnieuw op na standaard 120 seconden zonder voltooide long-poll-liveness.
• openclaw channels status --probe en openclaw doctor waarschuwen wanneer een actief pollingaccount na de opstartgratie geen getUpdates heeft voltooid, wanneer een actief Webhook-account na de opstartgratie geen setWebhook heeft voltooid, of wanneer de laatste succesvolle polling-transportactiviteit verouderd is.
• Verhoog channels.telegram.pollingStallThresholdMs alleen wanneer langlopende getUpdates-aanroepen gezond zijn, maar je host nog steeds onterechte polling-stall-herstarts meldt. Aanhoudende stalls wijzen meestal op proxy-, DNS-, IPv6- of TLS-egressproblemen tussen de host en api.telegram.org.
• Telegram respecteert ook procesproxy-env voor Bot API-transport, inclusief HTTP_PROXY, HTTPS_PROXY, ALL_PROXY en hun varianten in kleine letters. NO_PROXY / no_proxy kan api.telegram.org nog steeds omzeilen.
• Als de door OpenClaw beheerde proxy via OPENCLAW_PROXY_URL is geconfigureerd voor een serviceomgeving en er geen standaard proxy-env aanwezig is, gebruikt Telegram die URL ook voor Bot API-transport.
• Routeer Telegram API-aanroepen op VPS-hosts met instabiele directe egress/TLS via channels.telegram.proxy:

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

• Node 22+ gebruikt standaard autoSelectFamily=true (behalve WSL2). De volgorde van Telegram DNS-resultaten respecteert OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, daarna channels.telegram.network.dnsResultOrder, daarna de processtandaard zoals NODE_OPTIONS=--dns-result-order=ipv4first; als geen daarvan van toepassing is, valt Node 22+ terug op ipv4first.
• Als je host WSL2 is of expliciet beter werkt met IPv4-only-gedrag, forceer dan familieselectie:

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544-antwoorden uit het benchmarkbereik (198.18.0.0/15) zijn standaard al toegestaan voor Telegram-mediadownloads. Als een vertrouwde fake-IP- of transparante proxy api.telegram.org herschrijft naar een ander privé/intern/special-use-adres tijdens mediadownloads, kun je je aanmelden voor de Telegram-only bypass:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Dezelfde opt-in is per account beschikbaar op channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Als je proxy Telegram-mediahosts omzet naar 198.18.x.x, laat de gevaarlijke vlag eerst uit. Telegram-media staat het RFC 2544- benchmarkbereik standaard al toe.

• Omgevingsoverschrijvingen (tijdelijk):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Valideer DNS-antwoorden:

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