---
title: "Connect a surface — link-flow platforms return a pending connect ceremony [write]"
method: POST
path: "/channels/connections"
tags: ["channels"]
---

# Connect a surface — link-flow platforms return a pending connect ceremony \[write\]

`POST /channels/connections`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/channels/connections`
- Auth: HTTP bearer

telegram/imessage/whatsapp/x/lark/gchat mint a connect ceremony (hosted page or deep link + code) the end user claims in-platform. Slack/Discord with destination.webhook return a LINK ceremony; other Slack/Discord flows create a channel synchronously. Pass app for BYO; callback_url (link flows) redirects the hosted connect page to you after the claim.

## Request body

- CreateChannelConnection
  - `platform` 'telegram' | 'slack' | 'discord' | 'whatsapp' | 'imessage' | 'email' | 'teams' | 'x' | 'lark' | 'buzz' | 'gchat' | 'line' | 'loopback', required
  - `label` string
  - `metadata` object: Echoed on channel.connected and the callback redirect
  - `destination` object: Pre-bind to exactly one owned session or webhook endpoint when the surface is claimed
    - `session` string
    - `webhook` string
  - `app` string: BYO ChannelApp id — the connect ceremony runs on your bot/number
  - `adopt` object: Admin-scope migration of the app owner's previously verified conversation. Requires an owned active app, an app-scoped thread ID and destination. The caller attests the existing sender binding and consent; no LINK ceremony or provider message is performed. Exact replay reuses the connection; changed sender, metadata, destination or a disconnected record returns 409. Cannot combine with callback_url or invite_user.
    - `thread_id` string, required
    - `author_id` string, required
    - `tenant_key` string: Required only for Lark Store adoption; provider app and chat state must confirm this organization.
  - `invite_user` string: Slack only: user id to invite into the created channel
  - `callback_url` string: Link-flow platforms only: the hosted connect page redirects here after the claim with connection_id, status, and metadata query params

## Response `201`

Created

- ChannelConnection
  - `id` string
  - `platform` string
  - `channel_id` string, nullable
  - `thread_id` string: Present after administrative adoption; the existing app-scoped reply address
  - `label` string
  - `status` 'PENDING' | 'CONNECTED' | 'DISCONNECTED'
  - `bound_session` object, nullable
    - `id` string
    - `label` string
  - `created_at` string, date-time
  - `connect` object: PENDING only: open url; X and webhook-based Slack/Discord use a hosted page, phone-based flows include phone + code, and Lark includes app_id and a code to send to the bot.
    - `url` string
    - `phone` string
    - `app_id` string: Lark app ID used to open the bot
    - `code` string
    - `expires_at` string, date-time

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - added the optional property `error/request_id` to the response with the `default` status

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/channels/connections/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)