AgentSkyDocs
OverviewQuickstartCLI referenceAPI referenceAPI GatewayCapabilitiesagent.tomlChannels

Channels quickstart

Five minutes: register your Telegram bot as a channel app, mint a connect link, and talk to your agent in the chat — everything under your bot's identity.

1. Bring a bot token

Create a bot with Telegram's @BotFather (/newbot) and copy its token. You'll also want an AgentSky session to talk to — sky launch gives you one, or use any session id from GET /v1/sessions.

2. Register the channel app

bash
curl -s -X POST https://api.agentsky.dev/v1/channels/apps \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "telegram", "label": "My bot", "credentials": {"bot_token": "123456:ABC..."}}'
# -> { "id": "app_...", "credential_keys": ["bot_token", "bot_username", "webhook_secret"], ... }

Registration proves the token with Telegram and points your bot's webhook at a per-app ingress automatically. Credentials are encrypted at rest and never returned — reads list key names only.

3. Connect a chat

bash
curl -s -X POST https://api.agentsky.dev/v1/channels/connections \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "telegram", "app": "app_...", "destination": {"session": "sess-your-session-id"}}'
# -> { "id": "...", "status": "PENDING", "connect": { "url": "https://t.me/your_bot?start=..." } }

Open the URL and tap Start. The chat claims the link (links expire after 15 minutes), the connection flips CONNECTED, your session becomes its default binding, and the bot greets the user. A channel.connected event lands on your webhook endpoints with your metadata echoed.

4. Talk

Message the bot — the text becomes an agent turn and the reply lands back in the chat, rendered from markdown. The working marker rides the message (👀 while working on Telegram, resolved when the agent finishes).

bash
# proactive: post into the thread yourself
curl -s -X POST "https://api.agentsky.dev/v1/channels/threads/telegram:app_...:12345/messages" \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"parts": [{"type": "markdown", "text": "nightly report is **ready**"}]}'

No agent? Route to your own code instead

Skip destination and bind the connection to a webhook endpoint: inbound arrives as signed message.received events and you answer through the threads API — no AgentSky session involved. See Routing and Webhooks.