PHP 如何对接 Coze 扣子 API 实现自动化智能体工作流？-php教程-PHP中文网

coze api对接工作流必须使用bot token而非个人access token。bot token在bot编辑页「api配置」中生成，仅对所属bot生效，请求头需带authorization: bearer {bot_token}；调用/v1/workflow/run接口时须传入扁平结构的workflow_id和input参数，且所有消息请求必须携带有效conversation_id以维持上下文。

php 如何对接 coze 扣子 api 实现自动化智能体工作流？

Coze API 的认证方式必须用 Bot Token，不是个人 Access Token

Coze 官方明确区分了 Bot 和用户权限：对接工作流必须用 Bot 的 bot_token，它在 Bot 设置页的「API 配置」里生成；用个人账号的 access_token 会返回 403 Forbidden 或 {"error_code":10001,"msg":"Invalid token"}。Bot Token 默认只对所属 Bot 的对话、消息、工作流生效，不能跨 Bot 调用。

实操建议：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

进入 Coze 后台 → Bot → 编辑目标 Bot → 左侧菜单「API 配置」→ 开启「启用 API」→ 复制生成的 bot_token
请求时必须在 Header 中携带：Authorization: Bearer {bot_token}，注意 Bearer 后带空格
PHP 中推荐用 curl_setopt($ch, CURLOPT_HTTPHEADER, [...]) 设置，避免拼接 URL 带 token（不安全且易被日志泄露）

发送消息给 Bot 必须指定 conversation_id，否则会创建新会话

Coze 的 /v1/chat/messages 接口要求每次请求必须传 conversation_id，即使只想发起一次对话。不传或传空字符串，API 会返回 {"error_code":20001,"msg":"conversation_id is required"}；传错 ID 则可能触发权限错误或找不到上下文。

实操建议：

首次调用前先用 /v1/bot/{bot_id}/conversations 创建会话，获取 conversation_id；该接口需 POST 空 body，响应中取 data.id
后续所有消息都复用这个 conversation_id，Coze 才能维持上下文和工作流状态
PHP 中建议把 conversation_id 存到 session 或数据库，避免每次重新创建——否则工作流里的「等待用户输入」节点会失效

触发工作流要用 /v1/workflow/run，且 payload 结构不能套娃

Coze 工作流（Workflow）不是靠发消息自动触发的，必须显式调用 /v1/workflow/run 接口，并传入正确结构的 workflow_id 和输入参数。常见错误是把消息体直接塞进 input 字段，导致返回 {"error_code":30001,"msg":"Invalid input"}。

实操建议：

Workflow ID 在工作流编辑页 URL 中可见，形如 https://www.coze.com/workflow/{workflow_id}
payload 必须是扁平结构：{"workflow_id":"xxx","input":{"param1":"val1","param2":123}}，不能写成 {"input":{"data":{"param1":"val1"}}}
PHP 发送时用 json_encode() 并设 Header Content-Type: application/json；不要用 http_build_query()，否则 Coze 解析失败
如果工作流绑定了 Bot，run 成功后会自动在对应 conversation_id 中生成消息，无需再调 /messages

PHP cURL 请求必须处理 Coze 的分块响应和重定向限制

Coze API 对长响应（比如工作流返回大量文本或文件）采用 Transfer-Encoding: chunked，而 PHP 默认 cURL 不自动拼接分块，容易只读到第一段；另外部分接口（如上传文件）会返回 307 重定向，但 Coze 的签名机制要求重定向后仍保持原始 Authorization Header，cURL 默认不透传。

实操建议：

务必设置 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true)，否则 curl_exec() 返回 true 而非响应体
禁用自动重定向：curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false)，自己捕获 307 并手动重发，带上原 Authorization Header
对大响应，加 curl_setopt($ch, CURLOPT_ENCODING, "") 启用 gzip 解压，避免乱码
调试时用 curl_getinfo($ch, CURLINFO_HEADER_OUT) 检查发出的 Header 是否含 Authorization，这是最常被忽略的点