Telegram

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

• /setjoingroups om groepstoevoegingen toe te staan/te weigeren
• /setprivacy voor zichtbaarheidsgedrag in groepen

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

• channels.telegram.streaming is off | partial | block | progress (standaard: partial)
• korte previews van initiële antwoorden worden gedebounced en daarna na een begrensde vertraging gematerialiseerd als de run nog actief is
• progress houdt één bewerkbaar statusconcept bij voor toolvoortgang, toont het stabiele statuslabel wanneer antwoordactiviteit binnenkomt vóór toolvoortgang, wist dit bij voltooiing en verzendt het definitieve antwoord als normaal bericht
• streaming.preview.toolProgress bepaalt of tool-/voortgangsupdates hetzelfde bewerkte previewbericht hergebruiken (standaard: true wanneer previewstreaming actief is)
• streaming.preview.commandText bepaalt commando-/exec-details binnen die toolvoortgangsregels: raw (standaard, behoudt uitgebracht gedrag) of status (alleen toollabel)
• streaming.progress.commentary (standaard: false) schakelt assistentcommentaar/preambuletekst in het tijdelijke voortgangsconcept in
• legacy channels.telegram.streamMode, booleaanse streaming-waarden en gepensioneerde native conceptpreviewsleutels worden gedetecteerd; voer openclaw doctor --fix uit om ze naar de huidige streamingconfiguratie te migreren

{
  "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-/groeps-/onderwerppreviews: OpenClaw behoudt hetzelfde previewbericht en voert de definitieve bewerking op zijn plek uit
• lange definitieve tekst die in meerdere Telegram-berichten wordt gesplitst, hergebruikt de bestaande preview waar mogelijk als het eerste definitieve fragment en verzendt daarna alleen de resterende fragmenten
• definitieve antwoorden in progress-modus wissen het statusconcept en gebruiken normale definitieve levering in plaats van het concept tot 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 gebruikt het reasoning-previewpad van een ondersteund kanaal; op Telegram streamt het reasoning tijdens het genereren naar de live preview
• de reasoningpreview wordt verwijderd na definitieve levering; gebruik /reasoning on wanneer reasoning zichtbaar moet blijven
• het definitieve antwoord wordt zonder reasoningtekst verzonden

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

• De agent krijgt te horen dat rijke Telegram-berichten beschikbaar zijn voor deze bot/dit account.
• Markdown-tekst wordt gerenderd via OpenClaw’s Markdown IR en verzonden als rijke Telegram-HTML.
• Expliciete rijke HTML-payloads behouden ondersteunde Bot API 10.1-tags zoals koppen, tabellen, details, rijke media en formules.
• Mediabijschriften gebruiken nog steeds Telegram HTML-bijschriften, omdat rijke berichten bijschriften niet vervangen.

• 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 niet automatisch gedrag
• plugin-/skillcommando’s kunnen nog steeds werken wanneer ze worden getypt, zelfs als ze niet in het Telegram-menu worden getoond

• setMyCommands failed met BOT_COMMANDS_TOO_MUCH betekent dat het Telegram-menu na inkorten nog steeds is overgelopen; verminder plugin-/skill-/aangepaste commando’s of schakel channels.telegram.commands.native uit.
• deleteWebhook, deleteMyCommands of setMyCommands dat faalt met 404: Not Found terwijl directe Bot API-curlcommando’s werken, kan 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 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, dus dit wordt niet gemeld 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 setupcode
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" }],
  ],
}

{
  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, optioneel mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content of caption, optioneel presentation inline-knoppen; bewerkingen met alleen knoppen werken reply markup bij)
• 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 specifieke Telegram-bericht-ID

• off (standaard)
• first
• all

• onderwerpsessiesleutels voegen :topic:<threadId> toe
• antwoorden en typindicaties zijn gericht op de onderwerpthread
• configpad voor onderwerpen: channels.telegram.groups.<chatId>.topics.<threadId>

• berichtverzendingen laten message_thread_id weg (Telegram weigert sendMessage(...thread_id=1))
• typacties 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
• binnenkomende transcripties van spraaknotities worden in de agentcontext ingekaderd als machinaal gegenereerde, niet-vertrouwde tekst; vermeldingsdetectie gebruikt nog steeds de onbewerkte transcriptie, zodat spraakberichten achter een vermeldingspoort 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

{
  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 Telegram-toegangscontroles (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); niet-geautoriseerde afzenders worden geweigerd.
• Telegram geeft geen thread-ID’s mee in reactie-updates.
  • niet-forumgroepen worden gerouteerd naar de groepschatsessie
  • forumgroepen worden gerouteerd 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 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) voordat er op lengte wordt gesplitst.
• 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 dit om de latentie van albumantwoorden te verminderen.
• channels.telegram.timeoutSeconds overschrijft de time-out van de Telegram API-client (als deze niet is ingesteld, geldt de standaard van grammY). Botclients begrenzen geconfigureerde waarden onder de 60-secondenbeveiliging voor uitgaande tekst-/typverzoeken, zodat grammY de zichtbare antwoordlevering niet afbreekt voordat de transportbeveiliging en fallback van OpenClaw kunnen worden uitgevoerd. Long polling gebruikt nog steeds een 45-secondenbeveiliging voor getUpdates-verzoeken, zodat inactieve polls niet oneindig worden verlaten.
• 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 van antwoorden/citaten/doorsturen wordt genormaliseerd tot één geselecteerd gesprekscontextvenster wanneer de Gateway de bovenliggende berichten heeft gezien; de cache met waargenomen berichten bevindt zich in de OpenClaw SQLite-Pluginstatus, en openclaw doctor --fix importeert legacy sidecars. Telegram bevat slechts één oppervlakkige reply_to_message in updates, dus ketens ouder dan de cache zijn beperkt tot de huidige updatepayload van Telegram.
• Telegram-allowlists bepalen vooral wie de agent kan activeren, niet een volledige redactiegrens voor aanvullende context.
• besturing van DM-historie:
  • 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. Levering van inkomende eindantwoorden gebruikt ook een begrensde veilige verzendretry voor Telegram-pre-connectfouten, maar probeert geen dubbelzinnige netwerk-enveloppen na verzending 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:-doel)

• --presentation met buttons-blokken voor inline toetsenborden wanneer channels.telegram.capabilities.inlineButtons dit toestaat
• --pin of --delivery '{"pin":true}' om vastgezette levering 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 gecomprimeerde foto-, animated-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 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 -> Uitschakelen
  • verwijder de bot daarna uit de groep en voeg deze opnieuw toe
• openclaw channels status waarschuwt wanneer configuratie groepsberichten zonder vermelding verwacht.
• openclaw channels status --probe kan expliciete numerieke groeps-ID’s controleren; wildcard "*" kan niet op lidmaatschap worden geprobed.
• snelle sessietest: /activation always.

• wanneer channels.telegram.groups bestaat, moet de groep worden vermeld (of moet "*" worden opgenomen)
• 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 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-startupaanroepen en sendChatAction-typaanroepen zijn begrensd en proberen één keer opnieuw via de transportfallback van Telegram bij een verzoektime-out. Aanhoudende netwerk-/fetchfouten wijzen meestal op DNS-/HTTPS-bereikbaarheidsproblemen naar api.telegram.org

• getMe returned 401 is een Telegram-authenticatiefout voor de geconfigureerde bottoken.
• Kopieer of regenereer de bottoken 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 authfout; dit behandelen als “er bestaat geen Webhook” zou dezelfde fout door een ongeldige token alleen uitstellen tot latere API-aanroepen.

• 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.
• Tijdens polling-startup hergebruikt OpenClaw de succesvolle startup-getMe-probe voor grammY, zodat de runner geen tweede getMe nodig heeft vóór de eerste getUpdates.
• Als deleteWebhook mislukt met een tijdelijke netwerkfout tijdens polling-startup, 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 dan het Telegram-transport opnieuw op en probeert Webhook-opschoning opnieuw.
• Als Telegram-sockets volgens een korte vaste cadans worden gerecycled, controleer dan op een lage channels.telegram.timeoutSeconds; botclients begrenzen geconfigureerde waarden onder de uitgaande en getUpdates-verzoekbeveiligingen, maar oudere releases konden elke poll of elk antwoord afbreken wanneer dit onder die beveiligingen was ingesteld.
• Als logs Polling stall detected bevatten, herstart OpenClaw standaard polling en bouwt het Telegram-transport opnieuw op na 120 seconden zonder voltooide long-poll-liveness.
• openclaw channels status --probe en openclaw doctor waarschuwen wanneer een actief pollingaccount getUpdates na de startup-gratie niet heeft voltooid, wanneer een actief Webhook-account setWebhook na de startup-gratie niet heeft voltooid, of wanneer de laatste succesvolle pollingtransportactiviteit verouderd is.
• Verhoog channels.telegram.pollingStallThresholdMs alleen wanneer langlopende getUpdates-aanroepen gezond zijn maar je host nog steeds foutieve 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 alleen-IPv4-gedrag, forceer familieselectie:

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 herschrijft naar een ander privé-/intern/speciaal 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