更新日志 June 28, 2026

UnifyPort API 更新：会话标签、联系人消息与请求追踪 — UnifyPort

v1 稳定版发布三周后，UnifyPort API 迎来首批功能更新：用于组织 WhatsApp 对话的会话标签、联系人名片消息类型、贯穿每个调用的请求追踪机制，以及一系列让 webhook 事件参考文档更加实用的开发者体验改进。

以下是本次更新的完整内容，包含真实的端点和字段名称。

会话标签 — 4 个新端点

现在可以创建、列出、更新和删除会话标签，并批量为会话打标签或取消标签。这与 WhatsApp 原生暴露的标签系统一致——UnifyPort 通过 Conversations 类别下的四个端点将其统一呈现。

列出标签

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

返回分页的标签列表，每个标签包含 id 和 name：

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

创建或更新标签

POST /v1/accounts/{account_id}/conversations/labels/upsert

label_id 为空时创建，传入已有 label_id 时重命名：

{
  "label_id": "",
  "name": "VIP"
}

删除标签

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

为会话打标签或取消标签

POST /v1/accounts/{account_id}/conversations/labels

action 为 add 或 remove；conversation_ids 至少包含一个 ID：

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

四个端点目前仅支持 WhatsApp。其他渠道返回 501 unsupported_by_provider。对应的错误码——list_conversation_labels_failed、upsert_label_failed、delete_label_failed、set_label_members_failed——已在错误参考文档中列出。

联系人（vCard）消息类型

POST /v1/messages 现在接受 message.type: "contact"，携带结构化的 contacts 数组。UnifyPort 自动生成 vCard——你只需发送结构化 JSON，对方收到的是标准联系人名片。

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

每张名片必须包含 name。phones[].number、emails[].address、organization 和 title 为可选字段。可以在数组中发送单张或多张名片——WhatsApp 将单张映射为 contact 类型，多张映射为 contact_array。

空的 contacts 数组或缺少 name 的名片返回 400 invalid_request。非 WhatsApp 渠道在支持上线前返回 400 unsupported_message_type。

请求追踪 — request_id 与 X-Request-Id

每个 API 响应——无论成功还是错误——现在都携带顶层 request_id 字段，并以 X-Request-Id 响应头返回相同的值。在报告问题或调试失败调用时，引用此 ID 即可。

对于客户端侧的请求关联，发送自定义的 X-Request-Id 请求头，它会在响应中以 client_request_id 回显。这让你无需维护额外的映射层即可将出站 API 调用与内部请求 ID 关联起来。

真实 webhook 载荷示例

API 参考文档现在包含从实际设备 webhook 解析器（Telegram 和 WhatsApp）提取的真实载荷结构。

message.received 按内容类型展示载荷——文本、图片、语音、文档和位置——让你能看到每种变体的精确字段结构，而非猜测一个空的 data: {} 占位符。

group.updated 按变更类型展示载荷：

重命名 — changes[].kind: "renamed"，携带新的群组 name
成员增减 — changes[].kind: "member_added" 或 "member_removed"，携带参与者 ID 的 members[] 数组
管理员提升/降级 — changes[].kind: "promoted" 或 "demoted"，携带 members[]

单个 group.updated 事件可以携带多个变更——例如，一次快照中同时包含重命名和成员添加。

三个新开发者工具

工具页面新增三个浏览器端工具，全部在客户端运行：

HMAC 签名生成器 — 在浏览器中生成和验证 HMAC-SHA1/SHA256/SHA512 签名；调试 webhook signing_secret 验证时非常实用
Unix 时间戳转换器 — Unix 时间戳与人类可读日期互转，自动识别秒级和毫秒级
JSON 格式化工具 — 格式化、压缩和校验 JSON，支持语法高亮和一键复制 JSON Path

破坏性变更：移除两个字段

POST /v1/messages 参考文档中移除了两个未实现的字段，以匹配实际 API 表面：

idempotency_key — 已移除。该字段在文档中存在但从未在设备 API 中实现。
provider_data.reply_to — 已从文档表面移除。provider_data 对象现在以 parse_mode 作为示例字段。

如果你的代码中使用了 idempotency_key 或 provider_data.reply_to，请检查你是否依赖了实际上从未生效的行为。这两个字段均未被 API 处理。

下一步

会话标签和联系人消息首先支持 WhatsApp，因为 WhatsApp 的上游 API 原生支持这些功能。随着其他渠道增加等效能力——或者归一化层能够弥合差异——这些功能将以相同的端点表面在更多渠道上线。501 unsupported_by_provider 响应是有意为之：它明确告诉你哪个渠道尚未支持某项功能，而非静默丢弃请求。

完整的 API 参考文档已上线：unifyport.ai/docs。