WhatsAppのユーザー名とBSUIDの取り扱い

このガイドでは、WhatsAppのユーザー名およびBSUIDに対応するために、Vonage Messages APIの連携設定に加える必要がある変更点について順を追って説明します。

前提条件

「メッセージ」機能が有効になっている、アクティブなVonageアプリケーション
WhatsApp Businessアカウント（WABA）およびMetaとVonageに連携されたWhatsAppの電話番号
着信メッセージおよびステータスコールバック用に設定されたWebhookエンドポイント

「メッセージ送信リクエスト」を更新する

電話番号に加えて、あるいは電話番号の代わりに、BSUID を使用してメッセージを送信できるようになりました。この to このフィールドでは、WhatsAppの受信者として電話番号またはBSUIDのいずれかを入力できるようになりました。

電話番号のみに送信（従来の動作、変更なし）：

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "14155550123", "from": "14155559876", "text": "Hello!" }'

BSUIDのみに送信：

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "message_type": "text", "to": "US.13491208655302741918", "from": "14155559876", "text": "Hello!" }'

重要：BSUIDを使用する際は、必ず完全な値（国コードのプレフィックス、ピリオド、およびすべての英数字）を指定してください。BSUIDの一部を省略または変更すると、リクエストは失敗します。

更新された「メッセージ送信」の応答を処理する

メッセージ送信時の応答に変更はありません。詳細については、メッセージ送信 API 仕様.

ステータス更新のコールバック（Webhook）ハンドラーを更新する

送信済み、配信済み、および既読の送信メッセージに対するステータスコールバックには、現在、 whatsapp.recipient オブジェクトと、ある profile 新しいフィールドを持つオブジェクト。

ステータスコールバックのペイロードを更新しました：

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "status": "read",
  "channel": "whatsapp",
  "profile": {
    "name": "John Smith",
    "username": "johnSmith"
  },
  "usage": { "currency": "EUR", "price": "0" },
  "whatsapp": {
    "pricing": {
      "type": "regular",
      "pricing_model": "CBP",
      "category": "service"
    },
    "recipient": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    },
    "conversation": {
      "id": "1234567890",
      "origin": { "type": "marketing" }
    }
  }
}

新規および変更されたフィールド：

フィールド	説明
`profile.username`	ユーザーが設定している場合は、そのユーザーのWhatsAppユーザー名。送信済みステータスの場合、またはユーザーにユーザー名がない場合は省略されます。
`whatsapp.recipient.user_id`	ユーザーのBSUID。配信済みおよび既読の状態では常に存在します。
`whatsapp.recipient.parent_user_id`	ユーザーの親BSUID。貴社が親BSUIDを有効にしている場合にのみ表示されます。
`whatsapp.recipient.wa_id`	ユーザーの電話番号。メッセージがBSUID宛てに送信され、電話番号を含めることができない場合は省略されます。

について failed ステータスコールバック、 recipient_user_id メッセージが電話番号宛てに送信された場合は、この部分は省略されます。

受信メッセージ（Webhook）ハンドラーを更新する

受信メッセージのWebhookには、現在、 whatsapp.sender オブジェクトと更新された profile オブジェクトがある。

受信メッセージのコールバックペイロードを更新しました：

{
  "channel": "whatsapp",
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
  "to": "447700900000",
  "from": "447700900001",
  "timestamp": "2025-02-03T12:14:25Z",
  "profile": {
    "name": "Jane Smith",
    "username": "janeSmith"
  },
  "message_type": "text",
  "text": "Hello from Vonage!",
  "whatsapp": {
    "sender": {
      "user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844830",
      "wa_id": "447700900000"
    }
  }
}

について from このフィールドには、利用可能な場合、ユーザーの電話番号が表示されます。電話番号が利用できない場合は、代わりにBSUIDが表示されます。

新規および変更されたフィールド：

フィールド	説明
`profile.username`	ユーザーが設定している場合、そのユーザーのWhatsAppユーザー名。ユーザーがユーザー名を設定していない場合は省略されます。
`whatsapp.sender.user_id`	ユーザーのBSUID。常に存在します。
`whatsapp.sender.parent_user_id`	ユーザーの親BSUID。貴社が親BSUIDを有効にしている場合にのみ表示されます。
`whatsapp.sender.wa_id`	ユーザーの電話番号。ユーザーがユーザー名を採用しており、上記の条件により電話番号を含めることができない場合は、省略されます。

ユーザーの電話番号をリクエストする（任意）

統合機能でユーザーの電話番号が必要となる場合（認証や確認などの目的など）、会話の中で直接その番号をリクエストすることができます。これを行うには、事前に承認済みの 定型メッセージ または、以下の方法を通じて 対話型メッセージ.

オプション 1：連絡先情報の入力を求めるボタン付きテンプレートメッセージ

まず、以下を含むWhatsAppテンプレートを作成し、承認を得る必要があります。 REQUEST_CONTACT_INFO ボタンは、以下の WhatsApp テンプレート管理API. 承認されたら、Vonage Messages API を使用してテンプレートを送信してください：

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "template", "template": { "name": "YOUR_TEMPLATE_NAME", "language": { "policy": "deterministic", "code": "en" }, "components": [ { "type": "BODY", "parameters": [] }, { "type": "buttons", "buttons": [ { "type": "REQUEST_CONTACT_INFO", "text": "Share Contact Info" } ] } ] } } }'

オプション 2：連絡先情報の入力を求めるボタン付きの対話型メッセージ

また、事前に承認済みのテンプレートを使用することなく、対話型メッセージを利用して、進行中の会話ウィンドウ内で電話番号をリクエストすることも可能です：

curl -X POST https://api.nexmo.com/v1/messages \ -H "Authorization: Bearer $VONAGE_JWT" \ -H "Content-Type: application/json" \ -d '{ "from": "YOUR_WABA_NUMBER", "to": "USERS_NUMBER", "channel": "whatsapp", "message_type": "custom", "custom": { "type": "interactive", "interactive": { "type": "request_contact_info", "body": { "text": "Please share your phone number with us to continue." }, "action": { "name": "request_contact_info" } } } }'

詳細情報

WhatsAppのユーザー名とBSUIDについて

ナビゲーション