Skip to main content

​
Telegram Integration v0

​
Scope

Defines the v0 integration model for Telegram as a dialog target in AIOS. This page formalizes the reuse posture for Telegram, its relation to OpenClaw-style adapter boundaries, and the canonical AIOS ownership that must remain intact.

​
Terminology

  • Telegram target: dialog.target = telegram.
  • Polling mode: adapter transport driven by periodic fetch.
  • Webhook mode: adapter transport driven by external callback delivery.

​
Normative Spec

​
Position in AIOS

Telegram MUST be treated as a first-batch dialog target in v0. Telegram integration MUST:
  • enter AIOS through channel adapters
  • normalize to the canonical dialog event model
  • bind to canonical route identity workspace_id + agent_id
  • preserve forward-only and metadata-only audit boundaries

​
Reuse Posture

Telegram SHOULD reuse OpenClaw-style channel adapter boundaries and ecosystem patterns where practical. Telegram MUST NOT:
  • define a separate session model
  • define a separate route model
  • become an independent control plane
Telegram config SHOULD map into:
  • auth.bot_token_ref
  • auth.allowlist
  • config.webhook_mode or config.polling_mode
  • config.context_cache
  • config.message_chunk_limit
  • route.workspace_id
  • route.agent_id

​
Architecture Equality with WeChat

Although transport details differ, Telegram and WeChat MUST be treated as the same architecture class:
  • external channel entry
  • normalized through channel adapter
  • delivered into canonical dialog ingress

​
Examples

​
Telegram auth example

{
  "auth": {
    "bot_token_ref": "secret://telegram/bot-token",
    "allowlist": ["tg-admin-001"]
  }
}

​
Telegram config example

{
  "config": {
    "polling_mode": true,
    "context_cache": true,
    "message_chunk_limit": 4000
  }
}

​
Telegram route example

{
  "route": {
    "workspace_id": "ws-001",
    "agent_id": "codex",
    "default": true
  }
}

​
Error & Recovery

  • Telegram transport interruptions MUST surface through canonical adapter health and fault reporting.
  • Polling or webhook mode failures MUST not create a parallel recovery model outside AIOS metadata and adapter contracts.
  • Dedup and reconnect behavior SHOULD follow the canonical dialog contract rather than Telegram-specific transcript handling.

​
Security & Audit

  • Telegram bot credentials SHOULD be secret-backed references.
  • Allowlist and route decisions MUST remain auditable.
  • Telegram transcript content remains forward-only and MUST NOT become persisted platform conversation history.

​
Status

Current status: draft Source discussions:
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-telegram-channel-ecosystem-note.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-dialog-channel-ecosystem-reuse-strategy-v0.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-channel-adapter-contract-v0-draft.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md

​
Changelog

  • 2026-03-24: Initial formal Telegram integration specification created from frozen discussion sources.