For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/server-api/card.md.

卡片相关 API

阅读提示:本文介绍豆包应用插件卡片相关的服务端 API。当前提供「刷新卡片实例」接口,用于在卡片下发后主动更新卡片数据。后续会陆续开放更多卡片操作接口。

接口列表

接口方法路径说明
刷新卡片实例POST/api/card/v1/developer/refresh按 refresh_key 批量更新已下发卡片的展示数据

基本概念

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直接数据刷新(默认)将请求中的 structured_content 作为完整的新 widget_data,直接覆盖卡片当前展示数据。
tool_result工具结果刷新按卡片首次下发时记录的应用版本、工具和模板,重新解释工具结果,同时生成新的 widget_data 和模型上下文。

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客户端行为
不传或为 true客户端按常规方式处理最新卡片数据,可以重新加载或重建卡片。
false客户端会在条件允许时复用当前卡片容器,仅更新卡片数据。客户端不支持此能力,或卡片的标识、布局、尺寸、运行状态不满足复用条件时,仍会重建卡片。

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 重试,避免重复刷新。

基本信息

名称描述
HTTP Path/api/card/v1/developer/refresh
HTTP MethodPOST
Scope无需特殊 Scope
权限要求使用应用级 Access Token 鉴权,无需用户授权

请求头

名称类型必填描述
content-typestring是固定值 "application/json"
X-DB-AccessTokenstring是应用级 Access Token,通过“获取应用级 Access Token”接口获取

请求参数

直接数据刷新(widget_data)请求体

名称类型是否必填描述示例值
refresh_keystring是刷新键,用于匹配需要更新的卡片实例。该值来自 Manifest 中被 is_refresh_key: true 标记的字段,卡片下发时该字段的值即为 refresh_key。刷新时必须与下发时完全一致。order_123456
structured_contentobject条件必填当前规范字段。卡片的完整新数据,将直接作为卡片的 widget_data 覆盖原有内容。必须是合法的 JSON 对象。{"title":"订单已发货","status":"shipped"}
reload_cardboolean否是否按常规方式重新加载卡片。默认值为 true。传入 false 时,客户端会在条件允许时优先复用当前卡片容器并更新数据;不满足条件时仍会重建卡片。false
contentarray否内容数组,会被加入到模型上下文中对模型可见。如不需要模型感知刷新内容可不传。传入时必须是合法的 JSON 数组。[{"type":"text","text":"订单已发货"}]
sequenceinteger否序列号,必须为正整数。用于保证同一 refresh_key 下多次刷新的顺序,小于等于已处理序列号的请求将被拒绝。2
idempotency_keystring否幂等键。相同幂等键的重复请求会直接返回首次的处理结果,不会重复刷新。建议在网络异常重试时使用相同的幂等键。refresh_20260716_001

tool_result 方式的字段约束

除上述通用字段外,tool_result 请求增加 refresh_mode: "tool_result",并使用以下约束:

字段类型是否必填约束
refresh_modestring是固定为 tool_result。
structured_contentobject 或 array是原始工具结果的结构化部分,必须符合首次下发该卡的工具在 Manifest 中声明的 schema。不能将直接数据刷新的 widget_data 直接作为该字段传入。
contentarray否原始工具结果的内容部分;省略时按 [] 处理。
refresh_keystring是必须与转换后的工具结果中的刷新键一致;不能借本接口迁移历史卡的刷新键。

服务端从历史卡中读取首次下发时的应用版本、工具和模板,开发者不能在本次请求中覆盖它们。转换成功后,每个卡片实例分别得到一对结果:用于 IM 渲染的 widget_data,以及按 model_view 投影后的模型上下文。IM 更新成功后,模型上下文才会异步写入该卡片的新版本;card_instance_refresh_key 关系保持不变。

请求示例

直接数据刷新(widget_data)请求示例

以下示例将完整的展示数据直接写入卡片;reload_card: false 表示客户端在条件允许时优先复用当前卡片容器:

curl -X POST 'https://api.doubao-dev.com/api/card/v1/developer/refresh' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "refresh_key": "order_123456",
    "structured_content": {
      "title": "订单已发货",
      "status": "shipped"
    },
    "reload_card": false,
    "idempotency_key": "refresh_20260908_001"
  }'

tool_result 请求示例

下面示例假设首次下发卡片的工具 schema 以 structuredContent.entities 为实体根。实际字段必须以该工具的 Manifest 为准:

curl -X POST 'https://api.doubao-dev.com/api/card/v1/developer/refresh' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "refresh_key": "order_123456",
    "refresh_mode": "tool_result",
    "content": [
      {"type": "text", "text": "订单已发货"}
    ],
    "structured_content": {
      "entities": [
        {
          "entity_type": "order",
          "order_id": "order_123456",
          "status": "shipped"
        }
      ]
    },
    "idempotency_key": "refresh_20260908_002"
  }'

响应参数

名称类型是否必填描述示例值
codeinteger是响应状态码,0 表示成功,非 0 表示失败。0
msgstring是响应状态描述信息。success
log_idstring是日志 ID,用于问题排查时提供给技术支持。20260716120000ABCDEF123456
dataobject否响应数据对象,详见下方 data 字段说明。请求失败时可能为 null。-

data 字段说明

名称类型是否必填描述示例值
statusstring是刷新结果状态,取值见下方 status 枚举。success
matched_countinteger是匹配到的卡片实例数量。3
success_countinteger是刷新成功的卡片实例数量。3
failed_countinteger是刷新失败的卡片实例数量。0
errorsarray否错误明细列表,仅在存在失败实例时返回。每个元素包含错误码和该错误对应的实例数量。[{"code":"stale_sequence","count":1}]

status 枚举:

值说明建议处理
success所有匹配的卡片实例均刷新成功无需额外处理
partial_success部分卡片实例刷新成功,部分失败查看 errors 字段了解失败原因,对失败实例可稍后重试
failed所有匹配的卡片实例均刷新失败查看 errors 字段了解失败原因,修正后重试

errors 元素字段:

名称类型是否必填描述
codestring是错误码,取值见下方 errors.code 枚举。
countinteger是该错误对应的卡片实例数量。

errors.code 枚举:

值说明建议处理
invalid_argument请求参数不合法检查 refresh_key、structured_content 等字段是否符合要求
too_many_targets匹配的卡片数量超过单次刷新上限缩小 refresh_key 的匹配范围,或拆分刷新请求
request_processing相同 refresh_key 的刷新请求正在处理中稍后使用相同 idempotency_key 查询结果,或等待当前请求完成
stale_sequence序列号已过期,小于等于已处理的序列号使用更大的 sequence 值重新发起请求
widget_instance_message_not_found部分卡片实例对应的消息不存在或已不可用该实例无法刷新,可忽略或在后续对话中重新下发卡片
render_failed卡片数据渲染失败检查 structured_content 是否符合卡片模板的数据结构要求
im_update_failed卡片消息更新失败稍后重试,持续失败时联系技术支持并提供 log_id
internal_error服务内部错误稍后重试,持续失败时联系技术支持并提供 log_id

tool_result 方式还可能返回以下错误码:

错误码说明建议处理
unsupported_creation_mode历史卡不是支持的引用卡创建方式。重新下发支持该方式的卡片,或使用直接数据刷新(widget_data)。
source_version_missing / source_tool_missing / source_metadata_invalid无法恢复首次下发时的版本、工具或模板来源。不要使用 tool_result 刷新该历史卡。
route_unavailable / instance_unavailable历史卡或其消息路由不可用。重新下发卡片或稍后重试。
manifest_version_not_found / source_tool_not_found首次下发使用的 Manifest 版本或工具已不可用。恢复对应版本配置,或重新下发卡片。
source_rule_unavailable / source_rule_ambiguous无法唯一恢复首次下发时的卡片规则。检查首次下发版本的工具和模板配置。
no_card_after_transform / multiple_cards_not_supported工具结果按来源规则转换后不是恰好一张物理卡。调整工具结果,使其与被刷新的单张历史卡对应。
card_template_mismatch转换结果的模板与历史卡当前模板不一致。不要用该结果覆盖已切换模板的历史卡。
refresh_key_mismatch工具结果按来源规则得到的刷新键与请求不一致。使用与工具结果一致的刷新键;本接口不迁移刷新键。

响应示例

正常示例(全部成功)

{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "success",
        "matched_count": 3,
        "success_count": 3,
        "failed_count": 0
    }
}

正常示例(部分成功)

{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "partial_success",
        "matched_count": 3,
        "success_count": 2,
        "failed_count": 1,
        "errors": [
            {
                "code": "widget_instance_message_not_found",
                "count": 1
            }
        ]
    }
}

异常示例(参数错误)

{
    "code": 40001,
    "msg": "param error: refresh_key is required",
    "log_id": "20260716120001ABCDEF654321",
    "data": null
}

异常示例(匹配数量超限)

{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "failed",
        "matched_count": 12,
        "success_count": 0,
        "failed_count": 12,
        "errors": [
            {
                "code": "too_many_targets",
                "count": 12
            }
        ]
    }
}

错误码

HTTP 状态码错误码描述排查建议
2000请求成功请结合 data.status 判断刷新结果
20040001参数错误请检查请求参数是否完整、格式是否正确,确认 refresh_key、structured_content 均已正确填写
200500010003应用级 Access Token 已过期重新获取并缓存新的应用级 Access Token 后重试
200500010004应用级 Access Token 无效检查令牌是否属于当前应用和环境,重新获取后重试
200500000000服务暂时无法完成请求保留 log_id,稍后重试;持续失败时联系技术支持

当 code 为 0 时,仅表示请求被服务端正常接收和处理。卡片刷新的实际结果请以 data.status 和 data.errors 为准。