🎼个人主页：【Y小夜】

😎作者简介：一位双非学校的大三学生，编程爱好者，

专注于基础和实战分享，欢迎私信咨询！

🎆入门专栏：🎇【MySQL，Javaweb，Rust，python】

🎈热门专栏：🎊【Springboot，Redis，Springsecurity，Docker，AI】 

感谢您的点赞、关注、评论、收藏、是对我最大的认可和支持！❤️

目录

🎈基本背景

🎈OAuth 授权：

🎃建立应用：

​编辑🎃生成JWT：

 🎃生成token：

🎈创建基本的会话、消息、对话：

 🎃创建会话：

 🎃查看会话列表：

 🎃创建消息：

🎃查看消息列表：

 🎃创建对话：

🎈  在工作流的某个节点的特殊交互

---

🎈基本背景

        相信大家都或多或少了解过扣子平台，这里我就不做概念介绍了，emmmmm，那我这里就给大家先讲一下我这篇文章的简单概要吧。

1.提前工作：建设好一个bot，然后这个bot去调用一个工作流，并且需要这个bot已经发布了。

2.首先，我先给大家讲一下不同用户在调用不同对话如何实现之间的隔离，简单来说，是通过代码，生成一个JWT，再通过JWT生成一个 access_token，用户可以使用这个token调用bot。

3.其次，基于API实现创建会话、消息、对话。

4.第三，如何实现工作流节点的特殊交互。

🎈OAuth 授权：

详细参考：参考官方文档：扣子

提示：创建OAuth 应用只有管理员和超级管理员才能设置。

🎃建立应用：

首先打开，之后创建一个应用，

然后点击创建key，会得到一个公钥和一个私钥，私钥需要下载到本地。

🎃生成JWT：

首先我们调试一下代码（代码实例是官方的，改几个参数即可）

# You must run `pip install PyJWT cryptography` to install the PyJWT and the cryptography packages in order to use this script.
#!/usr/bin/env python3
import sys
import time
import uuid
import jwt
# 替换为你的实际 Coze App 私钥
signing_key = '''
-----BEGIN PRIVATE KEY-----
xxxxxxxxxxxxxxxxxx
-----END PRIVATE KEY-----
'''
payload = {
    'iat': int(time.time()),
    'exp': int(time.time()) + 600,
    "jti": str(uuid.uuid4()),
    'aud': 'api.coze.cn',  
    'iss': '1127900106117'  # 替换为你的实际 Coze App ID
    'session_name': '用户的唯一标识'
}
headers = {
    'kid': '_v0VjcMlLdQc3tRTD3jC5Xz29TUnKQOhtuD5k-gpyf4'  # 替换为你的实际 Coze App 公钥指纹
}
# Create JWT with headers
encoded_jwt = jwt.encode(payload, signing_key, algorithm='RS256', headers=headers)
print(f"JWT: {encoded_jwt}")

session_name参数很重要，虽然不是必填的，但是是用户的唯一标识，所以这里可以当作必填的。

运行代码后，然后就可以得到一个JWT了

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZZd2ZsdFR1OWZBbWtwWFhSdnR5UmREc3RONVMzZWNFcDFqVzB6dVQyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuTsQobtCAdkkZTg8gav9EnN1QN_1xq0w8BzuuhS7wCeY8UbaskkTK9GnO4eU9tEINmVw-2CrfB-kNbEHlEDwXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****

 🎃生成token：

        然后通过API调用，使用JWT令牌得到一个access_token（15分钟后过期），并且这个JWT令牌只能使用一次，想要产生新的token，就需要先生成新的JWT令牌。

curl --location --request POST 'https://api.coze.cn/api/permission/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZZd2ZsdFR1OWZBbWtwWFhSdnR5UmREc3RONVMzZWNFcDFqVzB6dVQyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuTsQobtCAdkkZTg8gav9EnN1QN_1xq0w8BzuuhS7wCeY8UbaskkTK9GnO4eU9tEINmVw-2CrfB-kNbEHlEDwXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****' \
--data '{
    "duration_seconds": 86399,
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}'

返回实例：

{
    "access_token": "czs_RQOhsc7vmUzK4bNgb7hn4wqOgRBYAO6xvpFHNbnl6RiQJX3cSXSguIhFDzgy****",
    "expires_in": 1721135859
}

这样通过这个token， 我们就可以通过API调用扣子的接口了。

🎈创建基本的会话、消息、对话：

emmm，首先还是先用通俗易懂的话给大家讲一下他们三个的区别，防止打击搞混（因为我刚开始学的时候就搞混了）。

会话：简单来说，创建一个新的会话，就等于在使用智能体的时候，点击了一次+号，或者一个新的窗口，用户可以做上下文的交互。

消息：不管是用户，还是智能体，他们的每条，都称为消息

对话：用户与智能体的一次交互过程，简单来说就是一问一答。

一个会话中有很多对话，一个对话中有一条或多条消息。

 🎃创建会话：

参考：扣子

接口：POST https://api.coze.cn/v1/conversation/create

入参：

bot_id	string（这个地方尽量带着，后续查看会话列表的时候其实是必填的）	会话对应的智能体 ID。（选择对应智能体的id）
meta_data	map（用户会话隔离也可以通过这种方式实现，如果实现用户之间的会话隔离，可以在这个地方传唯一id，然后，查各个用户会话的时候，在做过滤）	创建消息时的附加消息，获取消息时也会返回此附加消息。 自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。

 🎃查看会话列表：

入参：

bot_id

String

必填，智能体 ID，获取方法如下： 进入智能体的 开发页面，开发页面 URL 中 bot 参数后的数字就是智能体 ID。智能体 ID 为73428668*****。

调用语句：

​
curl -X GET 'https://api.coze.cn/v1/conversations?bot_id=7524906869631696923&' \

-H "Authorization: Bearer pat_hVSQtSDyoRsGamb8bpZvfglR75PoYBrPw5c21ZxblvpYJ0wuxX0TokM0yAU6AhDq" \

-H "Content-Type: application/json"

​

出参：

code : 0
msg : ""
data {2}
    has_more : false
    conversations {2}
        0 {4}
            meta_data {0}
            last_section_id : 7527545081117835310
            created_at : 1752643174
            id : 7527545081117835310
        1 {4}
            created_at : 1752633629
            id : 7527504098434990132
            meta_data {1}
                uuid : newid1234
            last_section_id : 7527504098434990132
detail {1}
    logid : 202507161419129B08A691FA22C5ACDB00

 🎃创建消息：

         创建一条消息，并将其添加到指定的会话中。消息在服务端的保存时长为 180 天，到期后自动删除。

参考：扣子

http拼接：

conversation_id

String

必填，Conversation ID，即会话的唯一标识。

入参：

role	String	必填，发送这条消息的实体。取值： user：代表该条消息内容是用户发送的。 assistant：代表该条消息内容是 Bot 发送的。
content_type	String	必填，消息内容的类型，支持设置为： text：文本 object_string：多模态内容，即文本和文件的组合、文本和图片的组合
content	String	必填，消息的内容，支持纯文本、多模态（文本、图片、文件混合输入）、卡片等多种类型的内容。

🎃查看消息列表：

这个是关键：

• 查看消息列表 API 用于查询指定会话（conversation）中的消息记录，不仅包括开发者在会话中手动插入的每一条消息和用户发送的 Query，也包括调用发起对话 API 得到的 type=answer 的智能体回复，但不包括 type=function_call、tool_response 和 follow-up 类型的对话中间态消息。
• 查看对话消息详情 API 通常用于非流式对话场景中，查看某次对话（chat）中 type=answer 的智能体回复及 type=function_call、tool_response 和 follow-up 类型类型的对话中间态消息。不包括用户发送的 Query。

消息在服务端的保存时长为 180 天，期满后，消息将自动从会话的消息记录中删除。

curl -X POST 'https://api.coze.cn/v1/conversation/message/list?conversation_id=7527504098434990132&' \ -H "Authorization: Bearer 权限码" \ -H "Content-Type: application/json"

入参：

conversation_id

String

Conversation ID，即会话的唯一标识

出参：

 🎃创建对话：

这里是我们每次调用的核心：

调用此接口发起一次对话，支持添加上下文和流式响应。 

参考：扣子

http拼接：

conversation_id

String

标识对话发生在哪一次会话中。 会话是 Bot 和用户之间的一段问答交互。一个会话包含一条或多条消息。对话是会话中对 Bot 的一次调用，Bot 会将对话中产生的消息添加到会话中。 可以使用已创建的会话，会话中已存在的消息将作为上下文传递给模型。 对于一问一答等不需要区分 conversation 的场合可不传该参数，系统会自动生成一个会话 一个会话中，只能有一个进行中的对话，否则调用此接口时会报错 4016。

入参：

bot_id	String	必填，要进行会话聊天的智能体 ID。（ 确保当前使用的访问密钥已被授予智能体所属空间的 chat 权限。 ）
user_id	String（备注：似乎没什么用处）	必填，标识当前与智能体对话的用户，由使用方自行定义、生成与维护。user_id 用于标识对话中的不同用户，不同的 user_id，其对话的上下文消息、数据库等对话记忆数据互相隔离。如果不需要用户数据隔离，可将此参数固定为一个任意字符串，例如 123，abc 等。 出于数据隐私及信息安全等方面的考虑，不建议使用业务系统中定义的用户 ID。
stream	boolean	是否流式返回，true：采用流式响应。false：（默认）采用非流式响应。
additional_messages	array<obj>（这里基本是必填的，因为你要去用用户身份，问问题）	对话的附加信息。你可以通过此字段传入历史消息和本次对话中用户的问题。数组长度限制为 100，即最多传入 100 条消息。 若未设置 additional_messages，智能体收到的消息只有会话中已有的消息内容，其中最后一条作为本次对话的用户输入，其他内容均为本次对话的上下文。 若设置了 additional_messages，智能体收到的消息包括会话中已有的消息和 additional_messages 中添加的消息，其中 additional_messages 最后一条消息会作为本次对话的用户输入，其他内容均为本次对话的上下文。
auto_save_history	boolean	是否保存本次对话记录。 true：（默认）会话中保存本次对话记录，包括 additional_messages 中指定的所有消息、本次对话的模型回复结果、模型执行中间结果。 false：会话中不保存本次对话记录，后续也无法通过任何方式查看本次对话信息、消息详情。在同一个会话中再次发起对话时，本次会话也不会作为上下文传递给模型。 非流式响应下（stream=false），此参数必须设置为 true，即保存本次对话记录，否则无法查看对话状态和模型回复。
enable_card	设置问答节点返回的内容是否为卡片形式。默认为 false。（但API调用的时候似乎没什么用）	设置问答节点返回的内容是否为卡片形式。默认为 false。 true：问答节点返回卡片形式的内容。 false：问答节点返回普通文本形式的内容。

curl -X POST 'https://api.coze.cn/v3/chat?conversation_id=7527504098434990132&' \
-H "Authorization: 授权码" \
-H "Content-Type: application/json" \
-d '{
  "workflow_id": "7524907732639678527",
  "bot_id": "7524906869631696923",
  "user_id": "123",
  "stream": false,
  "additional_messages": [
    {
      "role": "user",
      "type": "question",
      "content_type": "text",
      "content": "你好"
    }
  ]
}'

🎈  在工作流的某个节点的特殊交互

这里就是结论，给大家说出来：通过API调用Bot时，是无法获取到工作流 interrupt节点，因为data为空，询问客服，现阶段仅支持API调用异步或流式工作流打印工作流节点信息，可以通过envent_id恢复工作流，就可以得到节点信息，但是API调用bot暂不支持得到节点信息。建议对策：让某些我们需要的节点，去输出内部规定的一些规则，从而可以得到运行到哪个节点，然后做一些特殊逻辑的内部交互。