> ## 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.

# Channel Integration Page v0

> Information architecture and form model for channel onboarding, routing, status, and credential-backed configuration.

# Channel Integration Page v0

## Scope

Defines the v0 information architecture and form model for the Agent Platform Channel Integration Page.

This page formalizes the configuration-driven console surface used to onboard channels, manage credentials and routing, inspect status, and test connectivity without creating a parallel control plane.

## Terminology

* **Channel Integration Page**: the management UI for channel onboarding and status inspection.
* **Route target**: the canonical AIOS binding to `workspace_id + agent_id`.
* **Create wizard**: the guided flow for adding a new channel configuration.
* **Recent events**: metadata-only event summaries, not persisted transcript bodies.

## Normative Spec

### Page Responsibilities

The page MUST support:

* channel onboarding
* credential and parameter configuration
* route binding management
* channel enablement and disablement
* health and recent error inspection
* connection testing and pairing visibility

The page MUST NOT change these platform boundaries:

* Gateway remains the only control plane
* `dialog` remains the multi-channel ingress layer
* adapters remain behind canonical contracts
* AIOS retains canonical session, route, and policy models

### IA Model

The page SHOULD contain four primary areas:

1. Channel List
2. Channel Detail
3. Create Channel Wizard
4. Status and Test Panel

### Channel List Requirements

Each list item SHOULD show at least:

* `channel_name`
* `channel_type`
* `enabled`
* `status`
* `last_seen_at`
* `route_target`

### Top-level Form Model

Every configured channel MUST map to this top-level structure:

* `channel_id`
* `channel_type`
* `display_name`
* `enabled`
* `auth`
* `config`
* `route`
* `policy`

### Minimum Required Inputs

Following frozen P1 direction, the page MUST be able to capture at least:

* `channel_type`
* `target_id`
* `endpoint`
* `auth_ref`
* `routing_scope`
* `metadata_schema_version`
* `enabled`

### Route Model

The page MUST support routing to canonical AIOS route identity:

* `workspace_id`
* `agent_id`
* optional default-route behavior

### Status and Test Model

The page MUST surface:

* connection test trigger
* current health state
* last error summary
* pairing, owner, or allowlist status when relevant
* last successful heartbeat or handshake time

### Data Boundary Rule

Recent events and health summaries MUST remain metadata-only. The page MUST NOT show long-term stored dialog transcript content.

## Examples

### Top-level channel document

```json theme={null}
{
  "channel_id": "ch-001",
  "channel_type": "wechat",
  "display_name": "Team WeChat",
  "enabled": true,
  "auth": {},
  "config": {},
  "route": {},
  "policy": {}
}
```

### Route section example

```json theme={null}
{
  "route": {
    "workspace_id": "ws-001",
    "agent_id": "codex",
    "default": true
  }
}
```

### Policy section example

```json theme={null}
{
  "policy": {
    "pairing_required": false,
    "dedup_window_sec": 60,
    "owner_only": true
  }
}
```

## Error & Recovery

* Invalid or incomplete configuration SHOULD fail during wizard validation rather than deferred runtime failure where possible.
* Connection test failures MUST surface as metadata summaries with the last relevant error.
* Route bindings MUST fail safely if they cannot resolve to canonical AIOS route identity.

## Security & Audit

* Credential material SHOULD be referenced through secret refs rather than inline plaintext storage.
* Console actions such as enable, disable, test, or route update MUST remain auditable.
* The page is a management surface only and MUST NOT become a hidden alternate control plane.

## Status

Current status: `draft`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-24-channel-integration-page-requirement.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-channel-integration-page-ia-and-form-model.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md`

## Changelog

* 2026-03-24: Initial formal channel integration page specification created from frozen discussion drafts.

## 相关页面

* [Channel Adapter Contract v0](/agent-platform/contracts/channel-adapter-v0/index)
* [WeChat Integration v0](/agent-platform/integrations/wechat/index)
* [Telegram Integration v0](/agent-platform/integrations/telegram/index)