<span id="连接消息通道"></span>

# Connect a messaging channel

Associate an inbound connection with a selected agent or team. Discover advertised provider, channel type and receive mode before preparing credentials, creating the connection and reading its runtime state.

<span id="api-操作"></span>

## API operations

Paths are relative to the Product Endpoint. Use credentials from [API call basics](../../api-call-basics.md).

| Method and path | Purpose |
| --- | --- |
| `GET /workspaces/{workspace_id}/ingress-capabilities` | Available provider, channel type and receive modes. |
| `GET /workspaces/{workspace_id}/ingress-connections` | Supply `target_kind`, `target_workspace_id`, and `target_id` together to query one target. The current list is not paginated. |
| `POST /workspaces/{workspace_id}/ingress-connections` | Create an inbound connection. |
| `GET /workspaces/{workspace_id}/ingress-connections/{id}` | Read versions and state. |
| `PATCH /workspaces/{workspace_id}/ingress-connections/{id}` | Update enabled state, model or credentials using both expected versions. |
| `POST /workspaces/{workspace_id}/ingress-connections/{id}/test` | Validates only `callback` connections. The JSON includes both current versions; Telegram also requires callback_url. |
| `DELETE /workspaces/{workspace_id}/ingress-connections/{id}` | Send both expected versions as query parameters to delete the association; body values are not used. |

<span id="请求与结果"></span>

## Requests and results

Creation includes `target` (`kind`, `workspace_id`, `id`), `provider`, `channel_type`, `receive_mode` and its matching configuration. `managed_stream` carries provider credentials; `callback` or `mail_polling` references an existing `channel_instance_id`. Select the configuration for that mode.

For the full Slack JSON and call sequence, see the CLI guide [Messaging Channels and Plugins](../../../cli/tasks/channels-plugins.md#cli-message-connections). For Go and Python examples, see the SDK guide [Connect Messaging Channels](../../../sdk/ai-studio/智能体/连接消息通道.md).

Preserve `id`, `association_version` and `config_version`, using recently read versions for changes. Inspect `desired_state`, `observed_state`, `last_receive_at`, `last_error_code` and verify an actual external message and reply in the selected target.

The capability list describes supported combinations, not credential, network or receiver readiness. For `managed_stream`, let the receiver establish the connection and read its state. Do not call the callback-only `/test` operation. Callback verification checks channel configuration and enables the connection. The Telegram branch registers a Webhook with the provider: `callback_url` must use the deployment's absolute HTTPS URL and match the detail's `callback_path`. A rejected channel test may return HTTP 200 with `ok:false`; inspect that business result and read the connection again.

When updating `managed_stream`, submit only secret fields that the platform allows, without resubmitting account identity: app_token/bot_token for Slack, app_secret for Feishu, and secret for WeCom. Changing an App ID or Bot ID requires the account association flow. Read state again after disabling. An established connection does not prove that messages have been sent or received.
