> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Integration v0

> Telegram as a dialog target in AIOS, including adapter reuse posture, route binding, and metadata-only operational boundaries.

# 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

### Recommended Config Shape

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

```json theme={null}
{
  "auth": {
    "bot_token_ref": "secret://telegram/bot-token",
    "allowlist": ["tg-admin-001"]
  }
}
```

### Telegram config example

```json theme={null}
{
  "config": {
    "polling_mode": true,
    "context_cache": true,
    "message_chunk_limit": 4000
  }
}
```

### Telegram route example

```json theme={null}
{
  "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.

## 相关页面

* [Dialog Ecosystem v0](/agent-platform/integrations/dialog-ecosystem/index)
* [Channel Integration Page v0](/agent-platform/console/channel-integration-page/index)
* [WeChat Integration v0](/agent-platform/integrations/wechat/index)