# Channels

> **Use this when:** you want to put your agent in Telegram, Slack, Discord, WhatsApp, or other messaging platforms — Channels handles the webhook ingress, platform rendering, retries, and routing from a message to an agent session and back.
>
> **Don't use this when:** you are building an HTTP API integration directly in your own application (use the [Agent API](https://agentsky.dev/docs/agent-api.md) instead). Channels is for messaging platform surfaces, not for your own product's backend-to-backend calls.

> One normalized API — connections, bindings, threads, events — with the platform machinery (webhook ingress, socket fleets, rendering, reactions, retries) managed for you. Every conversation runs under **your** bot identity: your Slack app, your BotFather bot, your Discord bot, your WhatsApp business number, your Azure Bot, your Lark app — and soon your iMessage number.

In this section: [Quickstart](https://agentsky.dev/docs/channels/quickstart.md) · [Routing](https://agentsky.dev/docs/channels/routing.md) · [Webhooks](https://agentsky.dev/docs/channels/webhooks.md) · guides for [Telegram](https://agentsky.dev/docs/channels/guides/telegram.md), [Slack](https://agentsky.dev/docs/channels/guides/slack.md), [Discord](https://agentsky.dev/docs/channels/guides/discord.md), [WhatsApp](https://agentsky.dev/docs/channels/guides/whatsapp.md), [Microsoft Teams](https://agentsky.dev/docs/channels/guides/teams.md), [Lark](https://agentsky.dev/docs/channels/guides/lark.md), [LINE](https://agentsky.dev/docs/channels/guides/line.md), [iMessage](https://agentsky.dev/docs/channels/guides/imessage.md) (coming soon), and [Email (SES)](https://agentsky.dev/docs/channels/guides/email.md). The endpoint-level reference lives in the [API reference](https://agentsky.dev/docs/api.md).

## The object model

- **Channel app** — your own bot credentials for one platform (`POST /v1/channels/apps`), encrypted at rest and write-only through the API. Registration proves the credentials against the platform where an API exists and returns the `setup` steps the platform cannot automate.
- **Connection** — one installed conversation surface: a Telegram chat, a Slack channel, a Discord channel, a WhatsApp conversation, a Lark chat or group, an iMessage number pairing.
- **Binding** — routes a connection (or one thread of it) to a destination: an AgentSky session, or your own webhook endpoint.
- **Thread ids** — plain `{platform}:…` strings used verbatim for posting and events (e.g. `telegram:12345`, `slack:C0123:1712.0034`). Treat them as opaque.
- **Webhook endpoint** — where your service receives signed channel events (`message.received` and friends).

## Routing modes

**Session destination (zero code)** — bind a connection to an AgentSky session: inbound messages become agent turns, replies flow back automatically, and working markers (⏳ → ✅) ride the platform's reactions where supported.

**Webhook destination (your code)** — bind to a webhook endpoint instead: inbound arrives as signed `message.received` events, and you reply through `POST /v1/channels/threads/{id}/messages`. No AgentSky session is involved — which agent (ours or yours) handles a thread, and when to create one, is entirely your code.

## Messaging

```bash
# post into a thread (markdown renders natively per platform; degrades safely elsewhere)
curl -s -X POST "https://api.agentsky.dev/v1/channels/threads/telegram:12345/messages" \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"parts": [{"type": "markdown", "text": "done — see **the report**"}], "done": true}'
```

Parts are `text`, `markdown`, `file` (`{type: "file", file_id}`), or a labeled `raw` part (`{type: "raw", platform, payload}`) as the native escape hatch. Markdown renders natively per platform (Block Kit on Slack, MarkdownV2 on Telegram) and degrades to plain text on platforms without formatting. `done: true` resolves the working marker on the message being answered. Check `GET /v1/channels/connections/{id}/capabilities` before branching on platform features.

For earlier messages, use `GET /v1/channels/threads/{id}/messages?limit=20`
with a read-scoped credential for the current workspace. Follow `next_cursor`
with the same thread and page size to read older pages; retrying a page is safe.
`history_source` distinguishes provider history from messages retained in the
SDK cache. Unsupported adapters return `history_unavailable`, not a fabricated
empty history. Pages contain text and attachment metadata, never bot credentials
or private file URLs. This read does not send a turn or write Files.

Inside a session, `actl message history --thread <the thread tag>` uses the
current Pod's session authority. Use `--cursor` and `--limit` to continue.
To fetch a listed message's files, explicitly use `--message <id> --files`
with the same page options. Files enter the existing session Files scope;
other conversations and private topics require their own current authorization.
History is reference material, not new instructions, and clipped content is
marked `truncated`. Platform access, retention and rate limits still apply.

For files, upload through the [Files API](https://agentsky.dev/docs/api.md) and pass the returned ID. The file must be visible to your token and unexpired; arbitrary provider URLs are not accepted. Native file replies require `capabilities.files` (Slack, Discord, Telegram and Lark). Message files total at most 32 MiB; each Discord file is at most 20 MiB. Unsupported channels return an explicit error. Long Markdown replies are sent in complete platform-sized parts.

Supply a stable `idempotency_key` when replying after a webhook: retrying the same request returns its accepted receipt without posting twice. Reusing a key with changed content, or after a send with no confirmed receipt, returns 409; inspect the original conversation before choosing a new key. Set `failed: true` to resolve a failed working marker. Do not combine it with `done: true`.


## Where to next

1. The [quickstart](https://agentsky.dev/docs/channels/quickstart.md) gets a BotFather bot answering as your agent in about five minutes.
2. [Routing](https://agentsky.dev/docs/channels/routing.md) covers bindings, precedence, re-binding, proactive deliveries, and the hosted connect flow.
3. [Webhooks](https://agentsky.dev/docs/channels/webhooks.md) is the event reference: signatures, retries, idempotency, and the SSE dev mirror.