# 配置和测试消息通道

消息通道实例保存一个第三方平台连接及其凭据。建议先测试尚未保存的配置，再创建实例并测试已保存凭据。两次测试解决的问题不同：前者避免保存明显错误的配置，后者确认服务器实际保存并使用的凭据可用。

## 开始之前

请准备 Product API Base URL、个人访问令牌、工作区 ID，以及第三方平台要求的应用 ID、密钥或 Token。为应用授予最小必要权限，并先在第三方平台完成应用创建。

当前通道 Provider 包括 `wecom`、`github`、`codex`、`feishu`、`slack`、`grafana`、`kubernetes` 和 `qq_mail`。不同 Provider 的 `channel_type`、`config` 和 `secrets` 不相同；以第三方应用和当前产品配置要求为准，不要把一个 Provider 的字段复制给另一个 Provider。

## 1. 保存前测试（仅企业微信邮箱）

下面测试一组尚未保存的企业微信邮箱配置。测试不会创建可长期引用的通道实例：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/channels/wecom/instances/test" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "wecom_mail",
    "name": "support-mail",
    "config": {
      "email": "<WECOM_MAIL_ADDRESS>"
    },
    "secrets": {
      "password": "<WECOM_MAIL_PASSWORD>"
    },
    "visibility": "workspace"
  }'
```

该接口仅接受 `wecom` Provider 的 `wecom_mail` 通道类型。检查 `data.ok`、`data.last_test_status` 和错误详情。返回连接成功只说明本次连接测试成功，不代表事件回调和业务消息链路已经配置完成。

## 2. 创建通道实例

创建飞书通道实例时，使用飞书的通道类型和凭据：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/channels/feishu/instances" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "feishu_app",
    "name": "support-feishu",
    "config": {
      "app_id": "<FEISHU_APP_ID>"
    },
    "secrets": {
      "app_secret": "<FEISHU_APP_SECRET>",
      "verification_token": "<FEISHU_VERIFICATION_TOKEN>"
    },
    "visibility": "workspace"
  }'
```

保存响应中的实例 ID、`credential_ref` 和 `callback_path`。`credential_ref` 用于把回调规则和这一个通道实例关联起来；不要用 Provider 名称代替它。

## 3. 测试已保存实例

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/channels/feishu/instances/$CHANNEL_INSTANCE_ID/test" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

该请求读取并测试服务端保存的凭据。响应除 `ok` 外，还可能包含错误阶段、Provider 错误码、错误分类和修复建议。连接测试不会发送业务消息，也不会模拟第三方事件。

## 查询、更新和停用

按 Provider 列出实例，再用实例 ID 读取详情。更新应用配置或轮换密钥后，应重新运行保存后测试。

`DELETE` 会停用实例及其凭据，而不是删除第三方平台中的应用。停用前检查智能体工具绑定和回调规则；否则已有配置会继续引用一个不可用的 `credential_ref`。

## 下一步

- [接收事件并触发自动化任务](receive-route-events.md)
- [创建和管理自动化任务](../automation/manage-tasks.md)
- [查询通道与回调 API](api-reference.md)