Telegram

• de privacymodus uitschakelen via /setprivacy, of
• de bot groepsbeheerder maken.

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

• directe chats: previewbericht + editMessageText
• groepen/topics: previewbericht + editMessageText

• channels.telegram.streaming is off | partial | block | progress (standaard: partial)
• progress wordt op Telegram gemapt naar partial (compatibiliteit met kanaaloverstijgende naamgeving)
• streaming.preview.toolProgress bepaalt of tool-/voortgangsupdates hetzelfde bewerkte previewbericht hergebruiken (standaard: true wanneer preview-streaming actief is)
• verouderde 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
        }
      }
    }
  }
}

• korte voorvertoningen in DM/groep/topic: OpenClaw behoudt hetzelfde voorvertoningsbericht en voert een laatste bewerking op dezelfde plek uit
• voorvertoningen ouder dan ongeveer één minuut: OpenClaw verzendt het voltooide antwoord als een nieuw definitief bericht en ruimt daarna de voorvertoning op, zodat de zichtbare tijdstempel van Telegram de voltooiingstijd weergeeft in plaats van de aanmaaktijd van de voorvertoning

• /reasoning stream verzendt reasoning naar de live voorvertoning tijdens het genereren
• het definitieve antwoord wordt zonder reasoning-tekst verzonden

• Markdown-achtige tekst wordt gerenderd naar Telegram-veilige HTML.
• Ruwe model-HTML wordt geëscapet om Telegram-parsefouten te verminderen.
• 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 (leidende / verwijderen, kleine letters)
• geldig patroon: a-z, 0-9, _, lengte 1..32
• aangepaste opdrachten kunnen native opdrachten niet overschrijven
• conflicten/dubbelen 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 faalt met 404: Not Found terwijl directe Bot API-curlopdrachten werken, kan betekenen dat channels.telegram.apiRoot was ingesteld op het volledige /bot<TOKEN>-endpoint. 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 het geconfigureerde bottoken heeft geweigerd. Werk botToken, tokenFile of TELEGRAM_BOT_TOKEN bij met het huidige BotFather-token; OpenClaw stopt vóór polling, dus dit wordt niet gerapporteerd als een Webhook-opruimfout.
• 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 een instelcode
2. plak de code in de iOS-app
3. /pair pending toont openstaande aanvragen (inclusief rol/scopes)
4. keur de aanvraag goed:
   • /pair approve <requestId> voor expliciete goedkeuring
   • /pair approve wanneer er maar éé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 triggerende bericht
• [[reply_to:<id>]] antwoordt op een specifiek Telegram-bericht-ID

• off (standaard)
• first
• all

• topicsessie-sleutels voegen :topic:<threadId> toe
• replies en typen richten zich op de topicthread
• topicconfiguratiepad: 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 agentantwoord om verzending als spraaknotitie af te dwingen
• transcripties van inkomende spraaknotities worden in de agentcontext ingekaderd als machinaal gegenereerde, niet-vertrouwde tekst; vermeldingsdetectie gebruikt nog steeds de ruwe transcriptie, zodat spraakberichten met vermeldingsgate 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 cache voor verzonden berichten).
• Reactiegebeurtenissen respecteren nog steeds de toegangscontroles van Telegram (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 emoji van 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 alinea-grenzen (lege regels) voordat op lengte wordt gesplitst.
• channels.telegram.mediaMaxMb (standaard 100) begrenst de grootte van inkomende en uitgaande Telegram-media.
• channels.telegram.timeoutSeconds overschrijft de time-out van de Telegram API-client (indien niet ingesteld, geldt de grammY-standaard).
• channels.telegram.pollingStallThresholdMs is standaard 120000; pas alleen aan tussen 30000 en 600000 voor fout-positieve herstarts door vastgelopen polling.
• groepscontexthistorie gebruikt channels.telegram.historyLimit of messages.groupChat.historyLimit (standaard 50); 0 schakelt dit uit.
• aanvullende context voor reply/quote/forward wordt momenteel doorgegeven zoals ontvangen.
• Telegram-allowlists bepalen primair wie de agent kan triggeren, niet een volledige redactiegrens voor aanvullende context.
• DM-historieknoppen:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry-configuratie geldt voor Telegram-verzendhelpers (CLI/tools/acties) voor herstelbare uitgaande API-fouten. Bezorging van het uiteindelijke inkomende antwoord gebruikt ook een begrensde safe-send-retry voor Telegram-fouten vóór verbinding, maar probeert geen ambigue netwerk-enveloppen na verzending opnieuw die zichtbare berichten kunnen dupliceren.

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

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 toetsenborden wanneer channels.telegram.capabilities.inlineButtons dit toestaat
• --pin of --delivery '{"pin":true}' om vastgezette bezorging aan te vragen wanneer de bot in die chat kan pinnen
• --force-document om uitgaande afbeeldingen en GIF’s als documenten te verzenden in plaats van gecomprimeerde foto- of animated-media-uploads

• channels.telegram.actions.sendMessage=false schakelt uitgaande Telegram-berichten uit, inclusief polls
• channels.telegram.actions.poll=false schakelt het aanmaken van Telegram-polls uit terwijl reguliere verzending ingeschakeld blijft

• 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 groepsberichten zonder vermelding verwacht.
• openclaw channels status --probe kan expliciete numerieke groeps-ID’s controleren; jokerteken "*" kan niet op lidmaatschap worden geprobed.
• snelle sessietest: /activation always.

• wanneer channels.telegram.groups bestaat, moet de groep worden vermeld (of "*" bevatten)
• verifieer botlidmaatschap in de groep
• bekijk logs: openclaw logs --follow voor redenen voor overslaan

• autoriseer je afzenderidentiteit (koppeling en/of numerieke allowFrom)
• opdrachtautorisatie blijft gelden, zelfs wanneer groepsbeleid open is
• setMyCommands failed met BOT_COMMANDS_TOO_MUCH betekent dat het native menu te veel items heeft; verminder Plugin-/skill-/aangepaste opdrachten of schakel native menu’s uit
• deleteMyCommands / setMyCommands-startupcalls zijn begrensd en proberen één keer opnieuw via de transportfallback van Telegram bij request-time-out. Aanhoudende netwerk-/fetch-fouten duiden 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 startup is ook een authenticatiefout; dit behandelen als “er bestaat geen webhook” zou dezelfde fout door een ongeldig token alleen uitstellen tot latere API-calls.
• Als deleteWebhook mislukt met een tijdelijke netwerkfout tijdens polling-startup, controleert OpenClaw getWebhookInfo; wanneer Telegram een lege Webhook-URL rapporteert, gaat polling door omdat opruiming al is voldaan.

• Node 22+ + aangepaste fetch/proxy kan onmiddellijk afbreekgedrag veroorzaken als AbortSignal-typen niet overeenkomen.
• Sommige hosts lossen api.telegram.org eerst op naar IPv6; defecte 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.
• Als logs Polling stall detected bevatten, herstart OpenClaw polling en bouwt het standaard de Telegram-transportlaag opnieuw op na 120 seconden zonder voltooide long-poll-liveness.
• openclaw channels status --probe en openclaw doctor waarschuwen wanneer een actief polling-account getUpdates niet heeft voltooid na de opstart-graceperiode, wanneer een actief webhook-account setWebhook niet heeft voltooid na de opstart-graceperiode, of wanneer de laatste succesvolle activiteit van de polling-transportlaag verouderd is.
• Verhoog channels.telegram.pollingStallThresholdMs alleen wanneer langlopende getUpdates-aanroepen gezond zijn maar je host nog steeds valse 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 proces-proxy-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) en dnsResultOrder=ipv4first.
• Als je host WSL2 is of expliciet beter werkt met alleen-IPv4-gedrag, forceer dan familieselectie:

channels:
  telegram:
    network:
      autoSelectFamily: false

• RFC 2544-benchmarkbereik-antwoorden (198.18.0.0/15) zijn standaard al toegestaan voor Telegram-mediadownloads. Als een vertrouwde fake-IP of transparante proxy api.telegram.org tijdens mediadownloads herschrijft naar een ander privé/intern/speciaal adres, kun je kiezen voor de alleen-Telegram-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 oplost 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