Telegram

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

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

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

• channels.telegram.streaming is off | partial | block | progress (standaard: partial)
• progress houdt één bewerkbare statusconcepttekst bij voor toolvoortgang, wist die bij voltooiing en verzendt het definitieve antwoord als normaal bericht
• streaming.preview.toolProgress bepaalt of tool-/voortgangsupdates hetzelfde bewerkte voorbeeldbericht hergebruiken (standaard: true wanneer preview-streaming 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 DM-/groep-/topic-previews: OpenClaw behoudt hetzelfde previewbericht en voert de definitieve bewerking ter plekke uit
• lange definitieve teksten die in meerdere Telegram-berichten worden opgesplitst, hergebruiken waar mogelijk de bestaande preview als eerste definitieve chunk en verzenden daarna alleen de resterende chunks
• definitieve antwoorden in voortgangsmodus wissen het statusconcept en gebruiken normale definitieve levering in plaats van het concept in het antwoord te bewerken
• als de definitieve bewerking mislukt voordat de voltooide tekst is bevestigd, gebruikt OpenClaw normale definitieve levering en ruimt het de verouderde preview op

• /reasoning stream verzendt redenering naar de live preview tijdens het genereren
• de redeneerpreview wordt verwijderd na definitieve levering; gebruik /reasoning on wanneer redenering zichtbaar moet blijven
• het definitieve antwoord wordt zonder redeneertekst verzonden

• Markdown-achtige tekst wordt gerenderd naar Telegram-veilige HTML.
• Ruwe model-HTML wordt ge-escaped om Telegram-parsefouten te verminderen.
• Als Telegram geparsede HTML weigert, probeert OpenClaw het opnieuw als platte tekst.

• commands.native: "auto" schakelt native commando’s 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 commando’s kunnen native commando’s niet overschrijven
• conflicten/duplicaten worden overgeslagen en gelogd

• aangepaste commando’s zijn alleen menu-items; ze implementeren gedrag niet automatisch
• plugin-/skill-commando’s 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 commando’s of schakel channels.telegram.commands.native uit.
• Als deleteWebhook, deleteMyCommands of setMyCommands faalt met 404: Not Found terwijl directe Bot API-curlcommando’s werken, kan dat betekenen dat channels.telegram.apiRoot is 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 de geconfigureerde bottoken heeft geweigerd. Werk botToken, tokenFile of TELEGRAM_BOT_TOKEN bij met de huidige BotFather-token; OpenClaw stopt vóór het pollen, 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.

​

Commando’s voor apparaatkoppeling (device-pair Plugin)

1. /pair genereert installatiecode
2. plak code in 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 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 triggerende bericht
• [[reply_to:<id>]] antwoordt op een specifieke Telegram-bericht-ID

• off (standaard)
• first
• all

• topicsessiesleutels voegen :topic:<threadId> toe
• antwoorden en typen richten zich op de topicthread
• pad voor topicconfiguratie: 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 verzenden als spraaknotitie af te dwingen
• inkomende transcripties van spraaknotities worden als machinaal gegenereerde, niet-vertrouwde tekst in de agentcontext geplaatst; vermeldingsdetectie gebruikt nog steeds de ruwe transcriptie zodat door vermeldingen gated 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 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-topicsessie van de groep (:topic:1), niet naar het exacte oorspronkelijke topic

• 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 commando’s 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 splitsen op lengte.
• channels.telegram.mediaMaxMb (standaard 100) begrenst de grootte van inkomende en uitgaande Telegram-media.
• channels.telegram.mediaGroupFlushMs (standaard 500) bepaalt hoe lang Telegram-albums/mediagroepen worden gebufferd voordat OpenClaw ze als één inkomend bericht dispatcht. Verhoog dit als albumonderdelen laat aankomen; verlaag het om de antwoordlatentie voor albums te verminderen.
• channels.telegram.timeoutSeconds overschrijft de time-out van de Telegram API-client (indien niet ingesteld, geldt de grammY-standaard). Botclients klemmen geconfigureerde waarden onder de 60-seconden requestguard voor uitgaande tekst/typen zodat grammY zichtbare antwoordaflevering niet afbreekt voordat de transportguard en fallback van OpenClaw kunnen worden uitgevoerd. Long polling gebruikt nog steeds een 45-seconden getUpdates-requestguard zodat idle polls niet onbeperkt worden verlaten.
• channels.telegram.pollingStallThresholdMs is standaard 120000; stem alleen tussen 30000 en 600000 af voor fout-positieve herstarts bij polling-stalls.
• groepscontexthistorie gebruikt channels.telegram.historyLimit of messages.groupChat.historyLimit (standaard 50); 0 schakelt uit.
• aanvullende context voor antwoorden/citaten/doorsturen wordt genormaliseerd in één geselecteerd gesprekscontextvenster wanneer de Gateway de bovenliggende berichten heeft waargenomen; de cache met waargenomen berichten wordt naast de sessiestore bewaard. Telegram neemt slechts één ondiepe reply_to_message op in updates, dus ketens ouder dan de cache zijn beperkt tot de huidige updatepayload van Telegram.
• Telegram-allowlists regelen primair wie de agent kan triggeren, niet een volledige grens voor redactie van aanvullende context.
• DM-historiecontroles:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• De configuratie channels.telegram.retry geldt voor Telegram-verzendhelpers (CLI/tools/acties) bij herstelbare uitgaande API-fouten. Aflevering van inkomende eindantwoorden gebruikt ook een begrensde safe-send retry voor Telegram-preconnectfouten, maar probeert geen ambiguë post-send netwerk-enveloppen opnieuw die zichtbare berichten zouden kunnen dupliceren.

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 forumtopics (of gebruik een :topic:-target)

• --presentation met buttons-blokken voor inline toetsenborden wanneer channels.telegram.capabilities.inlineButtons dit toestaat
• --pin of --delivery '{"pin":true}' om vastgepinde aflevering 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 als 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 maken van Telegram-polls uit terwijl reguliere verzendingen ingeschakeld blijven

• channels.telegram.execApprovals.enabled (wordt automatisch ingeschakeld wanneer ten minste één goedkeurder kan worden opgelost)
• 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 daarna de bot 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 gecontroleerd.
• snelle sessietest: /activation always.

• wanneer channels.telegram.groups bestaat, moet de groep worden vermeld (of moet "*" zijn opgenomen)
• controleer of de bot lid is van de groep
• bekijk logs: openclaw logs --follow voor redenen waarom berichten worden overgeslagen

• autoriseer je afzenderidentiteit (koppeling en/of numerieke allowFrom)
• opdracht-autorisatie blijft gelden, 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 opdrachten of schakel native menu’s uit
• deleteMyCommands / setMyCommands-opstartaanroepen en sendChatAction-typaanduidingsaanroepen zijn begrensd en proberen één keer opnieuw via de transport-fallback van Telegram bij een request-time-out. Aanhoudende netwerk-/fetch-fouten wijzen meestal op problemen met DNS-/HTTPS-bereikbaarheid 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; 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.
• Tijdens het starten van polling hergebruikt OpenClaw de succesvolle getMe-probe van het opstarten voor grammY, zodat de runner geen tweede getMe nodig heeft vóór de eerste getUpdates.
• Als deleteWebhook tijdens het starten van polling mislukt met een tijdelijke netwerkfout, gaat OpenClaw door met long polling in plaats van nog een control-plane-aanroep vóór polling te doen. Een nog actieve Webhook verschijnt als een getUpdates-conflict; OpenClaw bouwt daarna het Telegram-transport opnieuw op en probeert webhook-opruiming opnieuw.
• Als Telegram-sockets op een korte vaste cadans worden gerecycled, controleer dan op een lage channels.telegram.timeoutSeconds; botclients begrenzen geconfigureerde waarden onder de outbound- en getUpdates-requestguards, maar oudere releases konden elke poll of reply afbreken wanneer dit onder die guards was ingesteld.
• Als logs Polling stall detected bevatten, start OpenClaw polling opnieuw 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 polling-account na de opstart-grace geen getUpdates heeft voltooid, wanneer een actief Webhook-account na de opstart-grace 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 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). De resultaatvolgorde van Telegram-DNS respecteert OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, daarna channels.telegram.network.dnsResultOrder, daarna de processtandaard zoals NODE_OPTIONS=--dns-result-order=ipv4first; als niets van toepassing is, valt Node 22+ terug op ipv4first.
• Als je host WSL2 is of expliciet beter werkt met alleen-IPv4-gedrag, dwing dan familieselectie af:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Antwoorden uit het RFC 2544-benchmarkbereik (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 prive-/intern/speciaal adres, kun je kiezen voor de alleen-voor-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 omzet naar 198.18.x.x, laat dan eerst de gevaarlijke vlag 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