チュートリアル August 14, 2026

WhatsApp連絡先API：連絡先の追加とvCard送信の違い

WhatsAppの連絡先追加と連絡先カードの送信は、別々のAPI処理です。接続済みアカウントの連絡先一覧を変更するなら POST /v1/accounts/{account_id}/contacts/add、チャット内で1件以上の構造化された連絡先カードを送るなら POST /v1/messages と message.type: "contact" を使います。カード送信はアドレス帳の更新を兼ねません。

要点

連絡先を追加すると、接続済みメッセージングアカウントの連絡先一覧が変わります。
連絡先を送信すると、ユーザーまたはグループのチャットに連絡先情報が届きます。
追加処理では phone_number または username の少なくとも一方が必要です。
送信処理では message.contacts を空にできず、各カードに name が必要です。
現在、UnifyPortでは両方ともWhatsApp向けですが、ルートと非対応時のエラーは異なります。

連絡先追加とvCard送信の選び方

目的	ルート	必須入力	結果
接続済みアカウントの連絡先一覧に相手を保存する	`POST /v1/accounts/{account_id}/contacts/add`	`phone_number` または `username`	`id` や `conversation_id` を含む連絡先オブジェクト
チャット内で連絡先情報を共有する	`POST /v1/messages`	`account_id`、`to`、名前付きカードを1件以上含むcontactメッセージ	`message_id` を含む受付済みメッセージ結果

前者はアカウントの状態を管理し、後者はチャットコンテンツを送信します。サポートでは顧客を後から識別するために保存し、引き継ぎでは担当者のカードだけを顧客へ送る、といった使い分けができます。両方必要な場合も、2回の明示的な呼び出しとして扱います。

WhatsApp全体の接続方式を検討中なら、Cloud API、BSP、非公式インターフェースの比較も確認してください。構造化された連絡先メッセージが追加された経緯は、連絡先/vCardを含むAPIアップデートで確認できます。

方法1：接続済みアカウントへ連絡先を追加する

連絡先追加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 を保存します。電話番号から識別子を組み立てず、APIレスポンスを正としてください。

「この人を保存する」「接続済みアカウントのアドレス帳へ入れる」「追加後に正規の連絡先IDと会話IDを取得する」という要件なら、この処理を選びます。未実装のプロバイダーでは 501 unsupported_by_provider が返ります。

方法2：1件以上の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 は任意です。配列には1件でも複数件でも入れられます。空配列、または name のないカードは 400 invalid_request、WhatsApp以外のアカウントでは 400 unsupported_message_type になります。

「担当者情報を共有する」「取引先のカードを送る」「チャット内で複数のエスカレーション先を渡す」という要件なら、この処理を選びます。LINEを含む他チャネルでも同じ構造が使えるとは限らないため、プロバイダー別メッセージ対応表を先に確認してください。

両方必要な場合の安全な手順

接続済みアカウントの連絡先一覧を本当に変える必要がある場合だけ /contacts/add を呼びます。
返された識別子、特に conversation_id を保存します。
担当者カードは /v1/messages で別途送信します。
2つのAPI結果を別々に記録します。追加成功はカード送信の受付を意味せず、カード送信の受付もアドレス帳更新を意味しません。
unsupported_by_provider、unsupported_message_type、invalid_request を発生元の処理ごとに分岐します。

この分離により再試行も明確になります。メッセージ送信だけを再試行するときに、成功済みの連絡先追加まで繰り返さない設計にできます。

制限と判断材料

現時点で、この2つの連絡先機能はUnifyPortではWhatsApp向けです。Telegram、LINE、TikTok、Zalo、Xにも同じ送信処理が必要なら、対応表を確認し、構造化カードを前提にせずテキストの代替表示を用意してください。

APIは構造化カードを生成しますが、受信側アプリでの表示や保存は受信者側の操作にも依存します。個人情報は必要最小限にし、電話番号、メールアドレス、組織名、役職のうち実際に必要な項目だけを送ってください。

よくある質問

WhatsAppでvCardを送ると、接続済みアカウントの連絡先にも追加されますか？

いいえ。連絡先一覧には /contacts/add、チャット内のカード送信には /v1/messages と message.type: "contact" を使います。

1回のリクエストで複数の連絡先カードを送れますか？

はい。message.contacts に複数のオブジェクトを入れます。すべてのオブジェクトに name が必要です。

連絡先追加では `phone_number` が必須ですか？

常に必須ではありません。phone_number または username の少なくとも一方が必要です。

LINEやTelegramでも同じ構造化連絡先メッセージを送れますか？

現在ドキュメント化されている送信処理はWhatsApp向けです。他プロバイダーでは 400 unsupported_message_type が返ります。

vCard文字列を自分で生成すべきですか？

不要です。ドキュメントの構造化JSONを送り、UnifyPortに生成させます。

次のステップ

チャットで情報を共有するなら連絡先メッセージ送信API、アドレス帳を管理するなら連絡先追加APIから始めてください。

出典

出典とプロバイダー対応状況は2026年8月14日に確認しました。