扣子

扣子扣子编程扣子罗盘教程资源

文档反馈

低代码项目

动态

快速开始

智能体

工作流

应用

资源

发布

模型

多人协作

开发工具

API 参考

鉴权

智能体和应用

工作空间

文件夹

企业/组织

会话与消息

对话

工作流

文件

智能音视频

知识库

数据库

插件

变量

设置用户变量的值

获取用户变量的值

渠道

用量限额

账单与权益

回调

错误码

API 教程

API 常见问题

SDK 参考

音视频

Coze CLI

推广与变现

常见问题

设置用户变量的值

为智能体或应用中的用户变量设置变量值。

接口说明

当智能体或应用中已创建并开启用户变量时，你可以通过该 API 设置变量值，未开启的用户变量无法设置变量值。
设置用户变量值后，你可以调用获取用户变量值 API 查询是否设置成功。

限制说明

仅支持为已发布 API、ChatSDK 的智能体或应用设置用户变量的值。

基础信息

请求方式	PUT
请求地址	`https://api.coze.cn/v1/variables`
权限	`updateVariable` 确保调用该 API 使用的访问令牌开通了 `updateVariable` 权限，详细信息参考鉴权方式。
接口说明	为智能体或应用中的用户变量设置变量值。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	解释请求正文的方式。

Body

参数	类型	是否必选	示例	说明
app_id	String	可选	7448857477636685850	如果需要为应用设置用户变量的值时，填入对应的应用ID。你可以通过应用的业务编排页面 URL 中获取应用 ID，也就是 URL 中 project-ide 参数后的一串字符，例如 `https://www.coze.cn/space/739174157340921**/project-ide/743996105122521/workflow/744102227704147` 中，应用的 ID 为 `743996105122521**`。说明 `app_id` 和 `bot_id` 应至少填写一个，否则会报错。
bot_id	String	可选	7493151027400097829	需要为智能体设置用户设置变量的值时，填入对应的智能体 ID。你可以通过智能体的编排页面获取智能体 ID，开发页面 URL 中 bot 参数后的数字就是智能体 ID。例如`https://www.coze.com/space/341**/bot/73428668*`，bot ID 为`73428668***`。
connector_id	String	可选	1024	智能体或应用的发布渠道 ID 列表。目前支持如下渠道： API：（默认）1024 ChatSDK：999
connector_uid	String	必选	7432567	用户 ID，用于为指定的用户设置变量的值。用户 ID 对应执行工作流 API 中 `ext` 字段指定的 user_id 或发起对话 API 中的 user_id。
data	Array of KVItem	必选	[{"keyword":"name","value":""},{"keyword":"age","value":""}]	用户变量的数组，不能为空。

KVItem

参数	类型	是否必选	示例	说明
value	String	必选	18	用户变量的值。
keyword	String	必选	age	用户变量的名称。说明 keyword 必须为智能体或应用中已创建并开启的用户变量，不能设置为系统变量。

返回参数

参数	类型	示例	说明
code	Long	0	调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。
msg	String	""	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	{ "logid": "20250416125552EE59A23A87A***" }	返回详情。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

curl --location --request PUT 'https://api.coze.cn/v1/variables' \
--header 'Authorization: Bearer pat_Q8LmOJU9mRCUzNCdnq6DMakFsmr***' \
--header 'Content-Type: application/json' \
--data '{
    "bot_id":"749315102740009***",
    "connector_id":"1024",
    "connector_uid":"7432567",
    "data":[
        {
            "keyword":"name",
            "value":"小王"
        },
        {
            "keyword":"age",
            "value":"18"
        }
    ]

}'

返回示例

{
    "code": 0,
    "msg": "",
    "detail": {
        "logid": "20250416125552EE59A23***"
    }
}

错误码

如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示 API 调用失败。此时 msg 字段中包含详细错误信息，你可以参考错误码文档查看对应的解决方法。

文档对您有帮助吗?