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 與非官方介面的三條路徑。要了解結構化聯絡人訊息的產品背景，可閱讀加入聯絡人/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 日。