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 日。