配置和测试消息通道¶
消息通道实例保存一个第三方平台连接及其凭据。建议先测试尚未保存的配置，再创建实例并测试已保存凭据。两次测试解决的问题不同：前者避免保存明显错误的配置，后者确认服务器实际保存并使用的凭据可用。
开始之前¶
请准备 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. 保存前测试（仅企业微信邮箱）¶
下面测试一组尚未保存的企业微信邮箱配置。测试不会创建可长期引用的通道实例：
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. 创建通道实例¶
创建飞书通道实例时，使用飞书的通道类型和凭据：
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. 测试已保存实例¶
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。