WhatsApp 联系人 API：添加联系人与发送 vCard 的区别

添加 WhatsApp 联系人和发送联系人名片是两个不同的 API 任务。如果要修改已连接账号的联系人列表，应调用 POST /v1/accounts/{account_id}/contacts/add；如果要在聊天中发送一张或多张结构化联系人名片，应调用 POST /v1/messages，并设置 message.type: "contact"。发送名片不能替代通讯录操作。

要点速览

• 添加联系人会改变已连接消息账号的联系人列表。
• 发送联系人是在用户或群聊中投递联系人资料。
• 添加操作至少需要 phone_number 或 username 其中之一。
• 发送操作要求 message.contacts 非空，而且每张名片都必须有 name。
• 这两个操作目前都面向 WhatsApp，但路由和不支持时的错误码并不相同。

添加联系人与发送 vCard 怎么选

目标	路由	必填输入	结果
把某人保存到已连接账号的联系人列表	POST /v1/accounts/{account_id}/contacts/add	phone_number 或 username	返回包含 id、conversation_id 等标识的联系人对象
在聊天中分享联系人资料	POST /v1/messages	account_id、to，以及至少一张带姓名的联系人名片	返回包含 message_id 的已接受消息结果

第一条路由管理账号状态，第二条路由发送聊天内容。跨境客服团队可能需要先保存客户，便于后续识别；销售交接流程则可能只需把客户经理的名片发给对方。确实需要两者时，也应该明确执行两次调用。

如果你还在评估接入方式，可先阅读 Cloud API、BSP 与非官方接口的对比。要了解结构化联系人消息如何加入 UnifyPort，可查看联系人/vCard 消息相关 API 更新。

方案一：把联系人加入已连接账号

添加联系人 API 文档给出的请求如下：

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/contacts/add \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "8600000000000",
    "whatsapp_options": {
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "sync_to_device_contacts": false
    }
  }'

phone_number 和 username 至少提供一个。WhatsApp 专用的姓名与设备同步选项必须放在 whatsapp_options 内，不要把 first_name、full_name 或 sync_to_device_contacts 移到顶层。

成功响应会返回联系人对象。后续要发送消息或执行联系人列表操作时，应保存响应中的 conversation_id，不要根据手机号自行拼接该标识。

当需求是“保存这个人”“加入已连接账号通讯录”或“添加后取得规范的联系人及会话标识”时，选择这条路由。未实现此操作的平台会返回 501 unsupported_by_provider。

方案二：发送一张或多张 vCard 名片

发送联系人消息文档使用统一消息路由：

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_8c21d0",
    "to": {
      "id": "8613912345678@s.whatsapp.net",
      "type": "user"
    },
    "message": {
      "type": "contact",
      "contacts": [
        {
          "name": "Jane Doe",
          "phones": [{ "number": "+8613800000000", "type": "CELL" }],
          "emails": [{ "address": "jane@example.com" }],
          "organization": "ACME",
          "title": "PM"
        }
      ]
    }
  }'

UnifyPort 会根据结构化 JSON 生成 vCard，无需自行拼装 BEGIN:VCARD 文本。vCard 格式由 RFC 6350 标准化，而此 API 接受的字段范围以当前文档为准。

每张名片必须有 name；phones[].number、emails[].address、organization 和 title 为可选字段。数组可以包含一张或多张名片。空数组或缺少 name 会返回 400 invalid_request；非 WhatsApp 账号会对该消息类型返回 400 unsupported_message_type。

当需求是“分享客户经理资料”“发送供应商名片”或“在会话里提供多个升级联系人”时，应选择这项操作。不要默认所有渠道都支持联系人名片，请先查看平台消息能力矩阵。

同时需要两者时的安全流程

1. 只有在账号联系人列表确实需要变化时，才调用 /contacts/add。
2. 保存返回的标识，尤其是 conversation_id。
3. 通过 /v1/messages 单独发送负责人名片。
4. 分别记录两次 API 结果。添加成功不代表名片消息已被接受；消息被接受也不代表通讯录已更新。
5. 根据具体操作处理 unsupported_by_provider、unsupported_message_type 和 invalid_request。

这样拆分也更利于重试。若消息发送需要重试，不应自动重复已经成功的通讯录变更。

限制与取舍

这两项联系人能力目前在 UnifyPort 中都属于 WhatsApp 专用支持。如果产品要同时覆盖 Telegram、LINE、TikTok、Zalo 和 X，应查看能力矩阵并准备文本降级方案，而不是假设结构化名片能跨平台通用。

API 会生成结构化名片，但名片如何展示或是否保存，仍由接收端应用和用户决定。处理个人资料时也应遵循最小必要原则，只发送对方真正需要的电话、邮箱、组织和职位字段。

常见问题

发送 WhatsApp vCard 会把联系人加入已连接账号的通讯录吗？

不会。UnifyPort 将其定义为两个独立操作：/contacts/add 管理联系人列表，/v1/messages 配合 message.type: "contact" 发送聊天消息。

一次请求可以发送多张联系人名片吗？

可以。在 message.contacts 中放入多个对象即可，每个对象都必须包含 name。

添加联系人时必须提供 phone_number 吗？

不一定。请求至少需要 phone_number 或 username 其中之一。

可以通过 LINE 或 Telegram 发送这种结构化联系人消息吗？

当前文档中的结构化发送操作只支持 WhatsApp；其他平台会返回 400 unsupported_message_type。

需要自己生成 vCard 字符串吗？

不需要。提交文档规定的结构化 JSON，由 UnifyPort 生成 vCard。

下一步

如果目标是在聊天中分享资料，请从发送联系人消息 API开始；如果真正需要管理通讯录，请使用添加联系人 API。

来源

• UnifyPort：发送联系人（vCard）消息
• UnifyPort：添加联系人
• UnifyPort：统一消息发送支持矩阵
• RFC Editor：RFC 6350 vCard 格式规范

来源及平台支持状态核对日期：2026 年 8 月 14 日。