卡片相关 API
阅读提示:本文介绍豆包应用插件卡片相关的服务端 API。当前提供「刷新卡片实例」接口,用于在卡片下发后主动更新卡片数据。后续会陆续开放更多卡片操作接口。
接口列表
基本概念
refresh_key
refresh_key 是卡片的刷新标识。你需要在 Manifest 的实体 schema 中,通过 is_refresh_key: true 声明哪个字段作为刷新键;卡片下发时,该字段的值会作为卡片的 refresh_key。
服务端可以使用 refresh_key 调用「刷新卡片实例」接口,在不打扰用户的前提下,主动更新匹配卡片的展示内容。刷新操作按 refresh_key 匹配卡片实例,不区分用户和会话,同一个 refresh_key 下的所有卡片实例都会被刷新。
刷新卡片实例
按 refresh_key 全量刷新匹配的卡片实例。调用时可选择“直接数据刷新”或“工具结果刷新”两种模式;未传 refresh_mode 时,默认使用直接数据刷新。无论使用哪种方式,卡片的 widget_id 等身份信息均保持不变。
刷新方式
refresh_mode 只能是字符串 widget_data 或 tool_result。接口只接受文档列出的字段。
使用限制
- 单次请求最多刷新 10 个卡片实例。如果匹配到的卡片数量超过 10 个,请求将整体失败,不会部分执行。
- 刷新时使用的
refresh_key必须与卡片下发时的值完全一致。 - 传入
idempotency_key时,相同idempotency_key的重复请求会直接返回首次的处理结果,不会重复刷新。 - 传入
sequence时,服务端会按序列号大小判断请求新旧;小于等于已处理序列号的请求将被拒绝。 tool_result方式仅支持具有完整首次下发来源的引用卡片;Inline、LegacyPack、共享卡片或来源版本、工具、模板不可追溯的卡片不会刷新。tool_result方式会拒绝转换出零张或多张物理卡、转换后模板不匹配,或转换得到的刷新键与请求不一致的请求;这类请求不会部分更新 IM 卡片。
控制刷新体验
使用 reload_card 控制客户端处理最新卡片数据的方式:
reload_card=false 用于优先减少卡片刷新带来的界面重建,不保证卡片一定不会重建。接口成功仅表示服务端已完成本次刷新处理;客户端最终是否复用现有容器取决于设备和卡片的当前状态。
接口说明
-
业务场景:当卡片对应的业务数据发生变化时(例如订单状态更新、库存变化、进度推进),服务端可以调用本接口,将最新数据推送给所有持有该卡片的用户,无需用户重新发起对话。
-
前提条件:
- 已在豆包开发者平台完成应用创建,获取到
app_id和app_secret。 - 已通过“获取应用级 Access Token”接口获取有效的应用级 Access Token。
- 已在 Manifest 中通过
is_refresh_key: true声明了卡片的刷新键字段,且服务端已记录下发卡片时使用的refresh_key值。
- 已在豆包开发者平台完成应用创建,获取到
-
注意事项:
- 直接数据刷新(
widget_data)中,structured_content是卡片的完整新数据,将直接作为卡片的widget_data覆盖原有内容,不是增量更新。请确保传入的是完整、可直接渲染的卡片数据。 - 工具结果刷新(
tool_result)中,content可省略,省略时按空数组处理;传入时必须是合法的 JSON 数组。content和structured_content共同作为工具结果输入,最终写入模型上下文的内容由首次下发版本中的model_view规则生成,不直接透传请求字段。 - 刷新操作按
refresh_key匹配所有卡片实例,不区分用户和会话。 - 建议为每次刷新生成唯一的
idempotency_key,并在网络异常或超时后使用相同的idempotency_key重试,避免重复刷新。
- 直接数据刷新(
基本信息
请求头
请求参数
直接数据刷新(widget_data)请求体
tool_result 方式的字段约束
除上述通用字段外,tool_result 请求增加 refresh_mode: "tool_result",并使用以下约束:
服务端从历史卡中读取首次下发时的应用版本、工具和模板,开发者不能在本次请求中覆盖它们。转换成功后,每个卡片实例分别得到一对结果:用于 IM 渲染的 widget_data,以及按 model_view 投影后的模型上下文。IM 更新成功后,模型上下文才会异步写入该卡片的新版本;card_instance_refresh_key 关系保持不变。
请求示例
直接数据刷新(widget_data)请求示例
以下示例将完整的展示数据直接写入卡片;reload_card: false 表示客户端在条件允许时优先复用当前卡片容器:
tool_result 请求示例
下面示例假设首次下发卡片的工具 schema 以 structuredContent.entities 为实体根。实际字段必须以该工具的 Manifest 为准:
响应参数
data 字段说明
status 枚举:
errors 元素字段:
errors.code 枚举:
tool_result 方式还可能返回以下错误码:
响应示例
正常示例(全部成功)
正常示例(部分成功)
异常示例(参数错误)
异常示例(匹配数量超限)
错误码
当
code为0时,仅表示请求被服务端正常接收和处理。卡片刷新的实际结果请以data.status和data.errors为准。