Telegram (Bot API)

Telegram-bots staan standaard in **Privacymodus**, wat beperkt welke groepsberichten ze ontvangen.

Als de bot alle groepsberichten moet zien, doe dan een van de volgende:

- schakel privacymodus uit via `/setprivacy`, of
- maak de bot een groepsbeheerder.

Na het wisselen van privacymodus moet je de bot verwijderen en opnieuw toevoegen in elke groep zodat Telegram de wijziging toepast.

Beheerdersstatus wordt beheerd in Telegram-groepsinstellingen.

Beheerderbots ontvangen alle groepsberichten, wat handig is voor altijd-aan-groepsgedrag.

- `/setjoingroups` om groepstoevoegingen toe te staan/weigeren
- `/setprivacy` voor groepszichtbaarheidsgedrag

OpenClaw kan deelantwoorden in realtime streamen:

- directe chats: preview-bericht + `editMessageText`
- groepen/topics: preview-bericht + `editMessageText`

Vereiste:

- `channels.telegram.streaming` is `off | partial | block | progress` (standaard: `partial`)
- `progress` mapt naar `partial` op Telegram (compatibiliteit met kanaaloverschrijdende naamgeving)
- verouderde `channels.telegram.streamMode` en boolean `streaming`-waarden worden automatisch gemapt

Voor alleen-tekst-antwoorden:

- DM: OpenClaw houdt hetzelfde preview-bericht en voert een definitieve bewerking ter plaatse uit (geen tweede bericht)
- groep/topic: OpenClaw houdt hetzelfde preview-bericht en voert een definitieve bewerking ter plaatse uit (geen tweede bericht)

Voor complexe antwoorden (bijvoorbeeld mediapayloads) valt OpenClaw terug op normale definitieve aflevering en ruimt vervolgens het preview-bericht op.

Preview-streaming is apart van blokstreaming. Wanneer blokstreaming expliciet is ingeschakeld voor Telegram, slaat OpenClaw de preview-stream over om dubbel streamen te voorkomen.

Als native draft-transport niet beschikbaar/geweigerd is, valt OpenClaw automatisch terug op `sendMessage` + `editMessageText`.

Telegram-only reasoning-stream:

- `/reasoning stream` stuurt reasoning naar de live preview tijdens het genereren
- het uiteindelijke antwoord wordt verstuurd zonder reasoning-tekst

Uitgaande tekst gebruikt Telegram `parse_mode: "HTML"`.

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

Linkpreviews zijn standaard ingeschakeld en kunnen worden uitgeschakeld met `channels.telegram.linkPreview: false`.

Telegram-commandomenuregistratie wordt bij opstart afgehandeld met `setMyCommands`.

Native commando-standaarden:

- `commands.native: "auto"` schakelt native commando's in voor Telegram

Voeg aangepaste commandomenuvermeldingen toe:

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

Regels:

- namen worden genormaliseerd (strip voorafgaande `/`, kleine letters)
- geldig patroon: `a-z`, `0-9`, `_`, lengte `1..32`
- aangepaste commando's kunnen geen native commando's overschrijven
- conflicten/duplicaten worden overgeslagen en gelogd

Opmerkingen:

- aangepaste commando's zijn alleen menuvermeldingen; ze implementeren niet automatisch gedrag
- plugin-/skillcommando's kunnen nog steeds werken wanneer getypt, zelfs als ze niet in het Telegram-menu worden getoond

Als native commando's zijn uitgeschakeld, worden ingebouwde commando's verwijderd. Aangepaste/plugincommando's kunnen nog steeds worden geregistreerd indien geconfigureerd.

Veelvoorkomende setupfouten:

- `setMyCommands failed` met `BOT_COMMANDS_TOO_MUCH` betekent dat het Telegram-menu na trimming nog steeds te vol was; verminder plugin-/skill-/aangepaste commando's of schakel `channels.telegram.commands.native` uit.
- `setMyCommands failed` met netwerk-/fetchfouten betekent meestal dat uitgaande DNS/HTTPS naar `api.telegram.org` wordt geblokkeerd.

### Apparaatkoppelingscommando's (`device-pair`-plugin)

Wanneer de `device-pair`-plugin is geïnstalleerd:

1. `/pair` genereert een setupcode
2. plak de code in de iOS-app
3. `/pair approve` keurt het laatste openstaande verzoek goed

Meer details: [Koppeling](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

Configureer inline keyboard-bereik:

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

Per-account-overschrijving:

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

Bereiken:

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (standaard)

Verouderde `capabilities: ["inlineButtons"]` mapt naar `inlineButtons: "all"`.

Berichtactie-voorbeeld:

{
  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" }],
  ],
}

Callback-klikken worden als tekst aan de agent doorgegeven:
`callback_data: <value>`

Telegram-toolacties omvatten:

- `sendMessage` (`to`, `content`, optioneel `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, optioneel `iconColor`, `iconCustomEmojiId`)

Kanaalberichtacties bieden ergonomische aliassen (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

Gating-controles:

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

Opmerking: `edit` en `topic-create` zijn momenteel standaard ingeschakeld en hebben geen aparte `channels.telegram.actions.*`-schakelaars.
Runtime-verzendingen gebruiken de actieve config-/secretssnapshot (opstart/herladen), dus actiepaden voeren geen ad-hoc SecretRef-herresolutie per verzending uit.

Reactieverwijderingssemantiek: [/tools/reactions](/docs/tools/reactions)

Telegram ondersteunt expliciete reply-threading-tags in gegenereerde uitvoer:

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

`channels.telegram.replyToMode` beheert de afhandeling:

- `off` (standaard)
- `first`
- `all`

Opmerking: `off` schakelt impliciete reply-threading uit. Expliciete `[[reply_to_*]]`-tags worden nog steeds gehonoreerd.

Forum-supergroepen:

- topic-sessiesleutels voegen `:topic:<threadId>` toe
- antwoorden en typen targeten de topic-thread
- topic-configuratiepad:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

Algemeen topic (`threadId=1`) speciale gevallen:

- berichtverzendingen laten `message_thread_id` weg (Telegram wijst `sendMessage(...thread_id=1)` af)
- typacties bevatten nog steeds `message_thread_id`

Topic-overerving: topicvermeldingen erven groepsinstellingen tenzij overschreven (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` is topic-only en erft niet van groepsstandaarden.

**Per-topic-agentroutering**: Elk topic kan naar een andere agent routeren door `agentId` in de topicconfiguratie in te stellen. Dit geeft elk topic zijn eigen geïsoleerde werkruimte, geheugen en sessie. Voorbeeld:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Algemeen topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}
```

Elk topic heeft dan zijn eigen sessiesleutel: `agent:zu:telegram:group:-1001234567890:topic:3`

**Persistent ACP-topicbinding**: Forum-topics kunnen ACP-harness-sessies vastpinnen via top-level getypte ACP-bindings:

- `bindings[]` met `type: "acp"` en `match.channel: "telegram"`

Voorbeeld:

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
```

Dit is momenteel beperkt tot forum-topics in groepen en supergroepen.

**Thread-gebonden ACP-spawn vanuit chat**:

- `/acp spawn <agent> --thread here|auto` kan het huidige Telegram-topic binden aan een nieuwe ACP-sessie.
- Vervolgberichten in het topic routeren direct naar de gebonden ACP-sessie (geen `/acp steer` vereist).
- OpenClaw pint het spawn-bevestigingsbericht in het topic na een succesvolle binding.
- Vereist `channels.telegram.threadBindings.spawnAcpSessions=true`.

Templatecontext bevat:

- `MessageThreadId`
- `IsForum`

DM-threadgedrag:

- privéchats met `message_thread_id` behouden DM-routering maar gebruiken thread-bewuste sessiesleutels/antwoorddoelen.

### Audioberichten

Telegram maakt onderscheid tussen voicenotities en audiobestanden.

- standaard: audiobestandgedrag
- tag `[[audio_as_voice]]` in agentantwoord om verzending als voicenotitie te forceren

Berichtactie-voorbeeld:

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

### Videoberichten

Telegram maakt onderscheid tussen videobestanden en videonotities.

Berichtactie-voorbeeld:

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

Videonotities ondersteunen geen bijschriften; verstrekte berichttekst wordt apart verstuurd.

### Stickers

Inkomende stickerafhandeling:

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

Stickercontextvelden:

- `Sticker.emoji`
- `Sticker.setName`
- `Sticker.fileId`
- `Sticker.fileUniqueId`
- `Sticker.cachedDescription`

Sticker-cachebestand:

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

Stickers worden eenmalig beschreven (wanneer mogelijk) en gecachet om herhaalde vision-aanroepen te verminderen.

Stickeracties inschakelen:

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

Sticker-verzendactie:

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

Gecachete stickers zoeken:

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

Telegram-reacties komen aan als `message_reaction`-updates (apart van berichtpayloads).

Wanneer ingeschakeld, plaatst OpenClaw systeemevents in de wachtrij zoals:

- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`

Configuratie:

- `channels.telegram.reactionNotifications`: `off | own | all` (standaard: `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (standaard: `minimal`)

Opmerkingen:

- `own` betekent gebruikersreacties op alleen door de bot verzonden berichten (best-effort via verzonden-bericht-cache).
- Reactie-events respecteren nog steeds Telegram-toegangscontroles (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); ongeautoriseerde afzenders worden verworpen.
- Telegram verstrekt geen thread-ID's in reactie-updates.
  - niet-forum-groepen routeren naar groepschatsessie
  - forum-groepen routeren naar de groeps-algemeen-topic-sessie (`:topic:1`), niet het exacte oorspronkelijke topic

`allowed_updates` voor polling/webhook bevatten automatisch `message_reaction`.

`ackReaction` stuurt een bevestigingsemoji terwijl OpenClaw een inkomend bericht verwerkt.

Resolutievolgorde:

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- agent-identiteitsemoji-terugval (`agents.list[].identity.emoji`, anders "👀")

Opmerkingen:

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

Kanaalconfigschrijfacties zijn standaard ingeschakeld (`configWrites !== false`).

Telegram-getriggerde schrijfacties omvatten:

- groepsmigratieevents (`migrate_to_chat_id`) om `channels.telegram.groups` bij te werken
- `/config set` en `/config unset` (vereist commando-inschakeling)

Uitschakelen:

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

Standaard: long polling.

Webhookmodus:

- stel `channels.telegram.webhookUrl` in
- stel `channels.telegram.webhookSecret` in (vereist wanneer webhook-URL is ingesteld)
- optioneel `channels.telegram.webhookPath` (standaard `/telegram-webhook`)
- optioneel `channels.telegram.webhookHost` (standaard `127.0.0.1`)
- optioneel `channels.telegram.webhookPort` (standaard `8787`)

Standaard lokale luisteraar voor webhookmodus bindt aan `127.0.0.1:8787`.

Als je publieke eindpunt verschilt, plaats een reverse proxy ervoor en wijs `webhookUrl` naar de publieke URL.
Stel `webhookHost` in (bijvoorbeeld `0.0.0.0`) wanneer je bewust externe ingress nodig hebt.

- `channels.telegram.textChunkLimit` standaard is 4000.
- `channels.telegram.chunkMode="newline"` geeft voorkeur aan alineagrenzen (lege regels) voor lengteopsplitsing.
- `channels.telegram.mediaMaxMb` (standaard 100) beperkt inkomende en uitgaande Telegram-mediagrootte.
- `channels.telegram.timeoutSeconds` overschrijft Telegram API-clienttimeout (indien niet ingesteld, geldt grammY-standaard).
- groepscontextgeschiedenis gebruikt `channels.telegram.historyLimit` of `messages.groupChat.historyLimit` (standaard 50); `0` schakelt uit.
- DM-geschiedeniscontroles:
  - `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.

CLI-verzenddoel kan een numerieke chat-ID of gebruikersnaam zijn:

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

Telegram-polls gebruiken `openclaw message poll` en ondersteunen forum-topics:

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

Telegram-specifieke poll-vlaggen:

- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` voor forum-topics (of gebruik een `:topic:`-doel)

Actie-gating:

- `channels.telegram.actions.sendMessage=false` schakelt uitgaande Telegram-berichten uit, inclusief polls
- `channels.telegram.actions.poll=false` schakelt Telegram-pollaanmaak uit terwijl gewone verzendingen ingeschakeld blijven

Telegram ondersteunt exec-goedkeuringen in goedkeurder-DM's en kan optioneel goedkeuringsprompts posten in de oorspronkelijke chat of het oorspronkelijke topic.

Configuratiepad:

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, standaard: `dm`)
- `agentFilter`, `sessionFilter`

Goedkeurders moeten numerieke Telegram-gebruikers-ID's zijn. Wanneer `enabled` false is of `approvers` leeg is, fungeert Telegram niet als exec-goedkeuringsclient. Goedkeuringsverzoeken vallen terug op andere geconfigureerde goedkeuringsroutes of het exec-goedkeuringsterugvalbeleid.

Afleveringsregels:

- `target: "dm"` stuurt goedkeuringsprompts alleen naar geconfigureerde goedkeurder-DM's
- `target: "channel"` stuurt de prompt terug naar de oorspronkelijke Telegram-chat/het oorspronkelijke topic
- `target: "both"` stuurt naar goedkeurder-DM's en de oorspronkelijke chat/het oorspronkelijke topic

Alleen geconfigureerde goedkeurders kunnen goedkeuren of weigeren. Niet-goedkeurders kunnen `/approve` niet gebruiken en kunnen geen Telegram-goedkeuringsknoppen gebruiken.

Kanaalaflevering toont de commandotekst in de chat, dus schakel `channel` of `both` alleen in in vertrouwde groepen/topics. Wanneer de prompt in een forum-topic belandt, bewaart OpenClaw het topic voor zowel de goedkeuringsprompt als de post-goedkeuring-opvolging.

Inline goedkeuringsknoppen zijn ook afhankelijk van `channels.telegram.capabilities.inlineButtons` die het doeloppervlak toestaat (`dm`, `group` of `all`).

Gerelateerde documentatie: [Exec-goedkeuringen](/docs/tools/exec-approvals)

- Als `requireMention=false`, moet de Telegram-privacymodus volledige zichtbaarheid toestaan.
  - BotFather: `/setprivacy` -> Disable
  - verwijder dan de bot en voeg opnieuw toe aan de groep
- `openclaw channels status` waarschuwt wanneer de configuratie onvermelde groepsberichten 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 zijn vermeld (of `"*"` bevatten)
- verifieer botlidmaatschap in de groep
- bekijk logs: `openclaw logs --follow` voor overslaan-redenen

- autoriseer je afzenderidentiteit (koppeling en/of numerieke `allowFrom`)
- commando-autorisatie geldt nog steeds zelfs wanneer groepsbeleid `open` is
- `setMyCommands failed` met `BOT_COMMANDS_TOO_MUCH` betekent dat het native menu te veel vermeldingen heeft; verminder plugin-/skill-/aangepaste commando's of schakel native menu's uit
- `setMyCommands failed` met netwerk-/fetchfouten duidt meestal op DNS/HTTPS-bereikbaarheidsproblemen naar `api.telegram.org`

- Node 22+ + aangepaste fetch/proxy kan direct-afbreekgedrag triggeren als AbortSignal-typen niet overeenkomen.
- Sommige hosts resolven `api.telegram.org` eerst 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.
- Op VPS-hosts met instabiele directe egress/TLS, routeer Telegram API-oproepen via `channels.telegram.proxy`:

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

- Node 22+ staat standaard op `autoSelectFamily=true` (behalve WSL2) en `dnsResultOrder=ipv4first`.
- Als je host WSL2 is of expliciet beter werkt met IPv4-only gedrag, forceer familieselectie:

channels:
  telegram:
    network:
      autoSelectFamily: false

- Omgevingsoverschrijvingen (tijdelijk):
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- DNS-antwoorden valideren:

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