跳到主要内容

使用 Coze 接收通知

机器人支持通过 Coze 方式将接收到的用户消息或事件回调至 Coze 服务，便于业务方快速集成大模型能力，实现智能回复、AI 助手等功能。

认证方式​

集成 Coze 时采用 Token 认证方式，需要在机器人配置中填写 Coze 平台的服务访问令牌（Service Access Token）。

详细参考：Coze 认证管理

集成类型​

coze_agentchat​

单 Agent 对话模式，基于 Coze Chat V3 API。

API 端点：https://api.coze.cn/v3/chat

主要参数：

  • bot_id：Bot 的唯一标识符（对应配置中的 agentId）
  • user_id：发送消息的用户标识
  • additional_messages：消息数组
  • stream：是否启用流式响应
  • conversation_id：会话 ID，用于维持对话上下文
  • custom_variables：自定义变量，包含机器人和消息上下文信息

coze_agentchatflow​

工作流对话模式，基于 Coze Workflow Chat API。

API 端点：https://api.coze.cn/v1/workflows/chat

主要参数：

  • workflow_id：工作流的唯一标识符（对应配置中的 workflowId）
  • bot_id：Bot 的唯一标识符（对应配置中的 agentId）
  • additional_messages：消息数组
  • parameters：工作流参数对象，包含自定义变量和上下文信息
  • conversation_id：会话 ID

回调参数说明​

机器人回调时传递的数据结构和字段说明，请参考：机器人回调数据

参数传递方式​

在 Coze 集成中，参数传递方式根据集成类型而不同：

coze_agentchat：

  • 参数通过 custom_variables 对象传递
  • 示例：custom_variables.bot_name、custom_variables.data_fromUserId

coze_agentchatflow：

  • 参数通过 parameters 对象传递
  • 示例：parameters.bot_name、parameters.data_fromUserId

会话管理​

  • 会话创建：用户首次对话时创建新会话
  • 会话延续：后续对话基于上下文进行，具备聊天记忆能力
  • 会话有效期：1 天，超期后自动开启新会话

回调请求示例​

coze_agentchat​

HTTP
POST https://api.coze.cn/v3/chat
Authorization: Bearer {token}
Content-Type: application/json

{
    "bot_id": "{agent_id}",
    "user_id": "abc-123",
    "stream": true,
    "auto_save_history": true,
    "conversation_id": "748348012449138",
    "additional_messages": [
        {
            "role": "user",
            "content": "北京今天的天气怎么样",
            "content_type": "text"
        }
    ],
    "custom_variables": {
        "bot_name": "智能客服机器人",
        "data_fromUserId": "user123",
        "data_channelType": "PERSON"
    }
}

coze_agentchatflow​

HTTP
POST https://api.coze.cn/v1/workflows/chat
Authorization: Bearer {token}
Content-Type: application/json

{
    "workflow_id": "{workflow_id}",
    "additional_messages": [
        {
            "role": "user",
            "type": "question",
            "content_type": "text",
            "content": "北京今天的天气怎么样"
        }
    ],
    "parameters": {
        "bot_name": "智能客服机器人",
        "data_fromUserId": "user123",
        "data_channelType": "PERSON"
    },
    "bot_id": "{agent_id}",
    "conversation_id": "748348012449138"
}

注意事项​

  • 认证：请求头中设置 Authorization: Bearer {token}
  • 参数配置：
    • coze_agentchat 需要配置 agentId
    • coze_agentchatflow 需要配置 agentId 和 workflowId
  • 会话管理：系统自动存储会话 ID，时效 1 天
  • 消息类型：仅支持文本消息（RC:TxtMsg）