ユーザー名とビジネススコープのユーザー ID [#usernames-and-bsuid]

WhatsApp は、エンドユーザー向けのオプションのプライバシー機能として ユーザー名 を導入しています。ユーザーがユーザー名を採用すると、その電話番号が Webhook ペイロードに表示されなくなる可能性があります。企業はユーザー名を採用することもできます。ビジネス電話番号のユーザー名を予約するには、ビジネスユーザー名をご覧ください。

ユーザーの電話番号 (フォーム、メール、以前の会話などを通じて収集された番号など) が既にある場合は、以前と同様にその番号に送信メッセージを送信できます。この変更は、ユーザー名を採用したユーザーが事前に電話ベースのやり取りを行わずに連絡した場合にのみ、受信 Webhook に影響します。認証テンプレート (ワンタップ、ゼロタップ、コードのコピー) は影響を受けず、引き続き電話番号が必要です。

中断のないメッセージングを確保するために、Metaは同時に**ビジネススコープのユーザーID(BSUID)**を展開しています。これらは安定した匿名の識別子であり、電話番号がなくてもユーザーに連絡して認識できます。

これらは 2 つの別々の変更です。

変更	機能
BSUID	`userId`フィールドは、電話番号の横にすべての受信 Webhook に表示されます
Usernames	電話番号は、ユーザーがユーザー名を採用しており、ビジネスとの最近の履歴がない場合、Webhook から省略される場合があります

Meta は、ユーザー名のサポートを地域全体で段階的に展開しています。タイムラインはMetaによって管理されており、変更される可能性があります。

手記

インバウンド Webhook の from フィールドには、大多数のユーザーの電話番号が記載されています。準備するには、電話番号インデックスと一緒にcontact.userIdの保存を開始し、fromに常に電話番号が含まれていると想定するコードを更新します。完全なリストについては、インテグレーション要件を参照してください。

BSUIDとは [#what-is-a-bsuid]

ビジネススコープのユーザーID(BSUID)は、ビジネスポートフォリオ内のWhatsAppユーザーの一意で安定した識別子です。

形式: ISO 3166 alpha-2 国コード + ピリオド + 最大 128 文字の英数字。例: US.13491208655302741918。BSUID と電話番号を区別するには、値が 2 文字で始まり、その後にピリオドが続くかどうかを確認します。
範囲: ビジネスポートフォリオごとに一意です。同じユーザーでも、やり取りするビジネスごとに異なる BSUID があります。
安定性: ユーザーが電話番号を変更しない限り、同じままです。その場合、Meta は新しい BSUID を生成し、古い値と新しい値を含む「ユーザー_id_update」Webhook を送信して、レコードを更新できるようにします。
IDの変更とは異なります: IDの変更は、ユーザーが同じ電話番号を維持したままWhatsAppを再インストールしたり、デバイスを変更したりしたときに発生します。BSUID の更新は、ユーザーが電話番号を完全に変更したときに発生します。
常に存在: すべてのインバウンド Webhook には、ユーザーがユーザー名を持っているかどうかに関係なく、contact.userId に BSUID が含まれます。

BSUID が Webhook に自動的に表示され始めます。お客様側で設定は必要ありません。

親 BSUID [#parent-bsuids-what-is-a-bsuid]

ほとんどの企業では、親 BSUID は必要ありません。これらは、複数のリンクされたポートフォリオを管理し、Metaにリクエストを送信し、明示的な承認を得たビジネスのみが利用できます。親 BSUID は、リンクされたすべてのポートフォリオで機能し、contact.parentUserIdに表示されます。これは、同じユーザーが所有する複数の電話番号とやり取りし、すべての電話番号に 1 つの識別子が必要な場合に便利です。

ビジネスが単一のポートフォリオを運営している場合、このフィールドは適用されません。

ユーザー名とは [#what-are-usernames]

WhatsApp ユーザーは誰でも、ビジネスにメッセージを送るときに、電話番号の代わりにアプリに表示されるオプションのユーザー名を設定できます。ユーザーがユーザー名を採用すると、最近やり取りしていない企業から電話番号が隠される可能性があります。

ユーザー名は完全にオプションです。採用しないユーザーは影響を受けません。その電話番号は、以前とまったく同じように Webhook に引き続き表示されます。

ビジネスユーザー名 [#business-usernames-what-are-usernames]

企業はユーザー名を採用することもできます。ビジネスユーザー名は、WhatsApp全体で1つのビジネス電話番号にマッピングされます。1 つの電話番号に一度に 1 つのユーザー名しか持つことができず、2 つの WhatsApp 電話番号 (消費者または企業) が同じユーザー名を共有することはできません。

手記

ビジネスユーザー名を採用しても、WhatsAppまたはWhatsApp Businessクライアントでビジネス電話番号が非表示になることはありません。

ビジネスユーザー名は、次の形式ルールに従う必要があります。

英語の文字 (a-z)、数字 (0-9)、ピリオド (.)、アンダースコア (_) 文字のみを含める必要があります。
英語以外の文字 (ñ、é、ü など) は機能せず、要求が失敗します。
長さは 3 文字から 35 文字にする必要があります。
少なくとも 1 つの英語文字 (a-z、A-Z) が含まれている必要があります。
ピリオドで開始または終了したり、ピリオドが 2 つ連続したりしてはなりません。
wwwで始まることはできません。
ドメインで終わることはできません (たとえば、.com、.org、.net、.edu、.gov)。
WhatsAppは、ユーザー名を比較するときに大文字と小文字を無視しますが、ピリオドとアンダースコアの文字は無視しません。たとえば、myIDとmyidは同じユーザー名ですが、myid、my.id、my_idはすべて異なります。

企業は、WhatsApp ManagerまたはMeta Business Suiteで希望のユーザー名を予約して申請できます。予約済みユーザー名はビジネスアカウントにリンクされたままであり、その地域で機能がリリースされると有効になります。ユーザー名は先着順なので、早めに予約して希望のハンドルを確保してください。ほとんどの場合、Facebook または Instagram アカウントと同じユーザー名を申請できます。

ユーザー名は電話番号に固有です。ビジネスに複数の電話番号がある場合は、それぞれに異なるユーザー名が必要です(すべての電話番号で同じ表示名を使用できます)。

ユーザー名はいつでも変更または削除できます。変更または削除後、古いユーザー名は 60 日間保持されるため、再利用できます。

ビジネスユーザー名の予約、変更、削除の手順については、WhatsApp ユーザー名の予約と管理方法の記事を参照してください。

WhatsApp は、チャットウィンドウにビジネスプロフィール情報を次の順序で表示します (優先度が最も高い順位)。

保存した連絡先名
確認済みのビジネス名または公式ビジネスアカウント名
ユーザー名
電話番号

ビジネス用電話番号は、常にビジネスプロフィールに表示されます。

電話番号の可視性 [#phone-number-visibility]

ユーザーの電話番号が利用可能な場合、Webhook ペイロードには電話番号と BSUID の両方が含まれます。電話番号が利用できない場合は、BSUID のみを受け取ります。

次のいずれかに該当する場合、ユーザーの電話番号は Webhook ペイロードに含まれます。

過去 30 日以内に相手の電話番号にメッセージを送ったり、電話をかけたりした。
過去 30 日以内に相手の電話番号からメッセージまたは電話を受け取った。
ユーザーは連絡先帳にあります。

これらのいずれも当てはまらず、ユーザーがユーザー名を採用している場合は、電話番号の代わりに BSUID を受け取ります。

電話番号を含めるかどうかは、次の 2 つのメカニズムによって決まります。

30 日間のウィンドウ (勤務先の電話番号ごと): 30 日間のルックバックは、勤務先の電話番号ごとに評価されます。1 つのビジネス電話番号からユーザーにメッセージを送った場合、ポートフォリオ内の別のビジネス電話番号の Webhook には、そのユーザーの電話番号は自動的に含まれません。電話番号は、その他の番号も過去 30 日以内にユーザーとやり取りした場合にのみ表示されます。
コンタクトブック(ビジネスポートフォリオごと): コンタクトブックは、ポートフォリオ内のビジネス電話番号がユーザーとやり取りするたびに、電話番号とBSUIDのペアを自動的に保存します。デフォルトでオンになっており、セットアップは不要です。ペアが保存されると、ユーザーが後でユーザー名を採用した場合でも、電話番号はポートフォリオ内のすべての電話番号の Webhook に常に含まれます。連絡先帳は、2026 年 4 月初旬以降に発生したやり取りのみをキャプチャします。履歴データは保存されません。

大事な

これは、ユーザー名を持ち、ビジネスとの最近の履歴がないユーザーからの会話にのみ影響します。アクティブなユーザー(過去 30 日間にメッセージを交換したユーザー)は影響を受けません。

ユーザー名を採用した後に電話番号を失った場合、その電話番号は永続的ではありません。特定のビジネス電話番号 (アウトバウンドキャンペーン、インバウンド返信) からのインタラクションは、その番号の Webhook の可視性を復元し、ポートフォリオ全体の可視性のためにユーザーをコンタクトブックに追加します。ユーザー名ユーザーに電話番号をリクエストするで説明されているREQUEST_CONTACT_INFOボタンを使用して、会話で直接電話番号をリクエストすることもできます。

電話番号の可視性を最大限に高めるには、定期的に連絡先リストに送信メッセージを送信します。電話番号への送信メッセージは 30 日間のウィンドウをリセットし、連絡先帳に入力され、ユーザがユーザ名を採用した後でも電話番号が表示されたままになります。

API ペイロードの変更 [#api-payload-changes]

すべての変更は加算です。現在のペイロードからフィールドは削除されません。

受信メッセージ Webhook (MO) [#inbound-message-webhook-api-payload-changes]

NTT CPaaSは、ユーザーからメッセージを送信すると、これをWebhook URLに配信します。

電話番号あり

json

2 "results": [

3 {

4 "from": "441234567890",

5 "to": "440987654321",

6 "integrationType": "WHATSAPP",

7 "receivedAt": "2026-03-30T12:00:00.000+0000",

8 "messageId": "ABGGFlA5Fpa",

9 "message": {

10 "type": "TEXT",

11 "text": "Hello, I need help with my order"

12 },

13 "contact": {

14 "name": "John Smith",

15 "phoneNumber": "441234567890",

16 "userId": "US.1349120865530274191",

17 "parentUserId": "US.ENT.9876543210987654321",

18 "username": "john.smith"

19 }

20 }

21 ]

22}

手記

contact.parentUserId フィールドと contact.username フィールドはオプションです。parentUserIdは、マルチポートフォリオの設定についてMetaから明示的に承認されているビジネスにのみ表示されます。「ユーザー名」は、ユーザーが設定した場合にのみ表示されます。電話番号が利用可能かどうかに関係なく、両方のフィールドが表示されます。

電話番号が利用できません

json

2 "results": [

3 {

4 "from": "AR.13491208655302741918",

5 "to": "440987654321",

6 "integrationType": "WHATSAPP",

7 "receivedAt": "2026-06-15T12:00:00.000+0000",

8 "messageId": "ABGGFlA5Fpa",

9 "message": {

10 "type": "TEXT",

11 "text": "Hello, I need help with my order"

12 },

13 "contact": {

14 "name": "Jane Doe",

15 "userId": "AR.13491208655302741918",

16 "username": "jane.doe"

17 }

18 }

19 ]

20}

電話番号が利用できない場合、from と contact.userId は同じ BSUID 値を持ちます。contact.userId は、読み取るのに信頼性が高いフィールドです。電話機が存在するかどうかに関係なく、常に BSUID を搭載します。すべてのAPIサーフェスのフィールドの完全なリストについては、サマリーテーブルを参照してください。

大事な

from は電話番号または BSUID として扱います。このフィールドを E.164 番号として検証または解析するコードは、両方のケースを処理するために更新する必要があります。

送信メッセージ要求 (MT) [#outbound-message-request-api-payload-changes]

電話番号に送信

json

1POST /whatsapp/1/message/text

4 "from": "440000000000",

5 "to": "441234567890",

6 "content": {

7 "text": "Your order #1234 has been shipped!"

8 }

BSUIDに送信

json

1POST /whatsapp/1/message/text

4 "from": "440000000000",

5 "to": "US.1349120865530274191",

6 "content": {

7 "text": "Your order #1234 has been shipped!"

8 }

「宛先」フィールドには、電話番号または BSUID のいずれかが受け入れられます。フィールドの最大長は 150 文字です。要求形式に他の変更を加える必要はありません。

手記

BSUID は、ワンタップ、ゼロタップ、コピーコード認証テンプレートを除く、任意のメッセージタイプに対して送信できます。電話番号が必要です。サポートされていない型を BSUID に送信しようとすると、エラーコード131062が返されます: 「ビジネススコープのユーザー ID (BSUID) 受信者は、このメッセージではサポートされていません。」

電話番号に送信されるアウトバウンドキャンペーンは、以前と同じように機能します。電話番号への送信と、対応する配信レポート Webhook の電話番号の受信を続行します。

配信レポート Webhook (DLR) [#delivery-report-webhook-api-payload-changes]

NTT CPaaS は、メッセージのステータスが変化すると、これを DLR Webhook に配信します。

ペイロードの例

json

2 "results": [

3 {

4 "bulkId": "BULK-ID-123",

5 "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",

6 "to": "441234567890",

7 "sentAt": "2026-03-30T12:00:00.000+0000",

8 "doneAt": "2026-03-30T12:00:02.000+0000",

9 "messageCount": 1,

10 "contact": {

11 "name": "John Smith",

12 "phoneNumber": "441234567890",

13 "userId": "US.1349120865530274191",

14 "parentUserId": "US.ENT.9876543210987654321",

15 "username": "john.smith"

16 },

17 "status": {

18 "groupId": 3,

19 "groupName": "DELIVERED",

20 "id": 5,

21 "name": "DELIVERED_TO_HANDSET",

22 "description": "Message delivered to handset"

23 }

24 }

25 ]

26}

contact オブジェクトは、インバウンド Webhook と同じ構造に従います。これは、送信済み、配信済み、および読み取り済み ステータスイベントにのみ含まれます。失敗した配信レポートには含まれません。DLR に含まれる識別子は、元のメッセージの送信方法によって異なります。

電話番号に送信: DLR には、電話番号と BSUID の両方が含まれます。
電話番号がわかっている BSUID に送信: DLR には、電話番号と BSUID の両方が含まれます。
BSUID に送信されましたが、電話番号は不明です。 DLR には BSUID のみが含まれています。

手記

contact.parentUserIdフィールドは省略可能であり、マルチポートフォリオ設定が承認されているビジネスにのみ表示されます。contact.usernameフィールドはオプションであり、ユーザーが設定した場合にのみ表示されます。

Seen レポート Webhook [#seen-report-webhook-api-payload-changes]

NTT CPaaSは、送信したメッセージをユーザーが閲覧したときに、これをWebhookに配信します。

ペイロードの例

json

2 "results": [

3 {

4 "messageId": "1215f543ab19-345f-adbd-12ad31451ed25f35",

5 "from": "385919998888",

6 "to": "41793026731",

7 "sentAt": "2026-03-30T12:00:00.000+0000",

8 "seenAt": "2026-03-30T12:00:02.000+0000",

9 "applicationId": "example-application-id",

10 "entityId": "example-entity-id",

11 "contact": {

12 "name": "John Smith",

13 "phoneNumber": "41793026731",

14 "userId": "US.1349120865530274191",

15 "parentUserId": "US.ENT.9876543210987654321",

16 "username": "john.smith"

17 }

18 }

19 ]

20}

contact オブジェクトは、受信レポートと配信レポートの Webhook と同じ構造に従います。含まれる識別子は、配信レポート Webhook (DLR) で説明されているのと同じルールを使用して、元のメッセージの送信方法によって異なります。

手記

すべてのフィールド変更の概要 [#field-changes-summary-api-payload-changes]

次の表は、すべての API サーフェスでユーザー名と BSUID の影響を受けるすべてのフィールドを示しています。

API サーフェス	フィールド	説明
MO ウェブフック	`from`	電話番号(利用可能な場合)。電話番号が利用できない場合の BSUID。
MO ウェブフック	`contact.phoneNumber`	ユーザーの電話番号。利用できない場合は省略されます。
MO ウェブフック	`contact.userId`	BSUIDです。常に存在します。
MO ウェブフック	`contact.parentUserId`	親 BSUID。承認済みのマルチポートフォリオ設定のみ。
MO ウェブフック	'連絡先.ユーザー名'	ユーザーの WhatsApp ユーザー名。ユーザーが設定した場合にのみ表示されます。
MTリクエスト	「に」	電話番号または BSUID を受け入れます。最大長: 150 文字。
DLR Webhook	「に」	元のメッセージの送信に使用された識別子を反映します。電話番号に送信する場合は電話番号、BSUID に送信する場合は BSUID。
DLR Webhook	「コンタクト」	`phoneNumber`、`userId`、`parentUserId`、`username`、および `name` を持つオブジェクト。送信済み、配信済み、および読み取りステータスにのみ表示されます。
確認された Webhook	「コンタクト」	`phoneNumber`、`userId`、`parentUserId`、`username`、および `name` を持つオブジェクト。表示されたイベントにプレゼントします。

ユーザー名ユーザーに電話番号をリクエストする [#request-phone-number]

ユーザーがユーザー名を採用していて、その電話番号が利用できない場合、WhatsApp は会話スレッドで直接リクエストする方法を 2 つ提供します。

自由形式のインタラクティブメッセージ: アクティブな 24 時間セッション中にリクエストを送信します。テンプレートの承認は必要ありません。
テンプレートボタン: 「ユーティリティ」または「マーケティング」テンプレートにREQUEST_CONTACT_INFOボタンを追加します。これを使用して、セッションウィンドウ外のユーザーにリーチします。

どちらの場合も、ユーザーには連絡先カードを共有するように求めるプロンプトが表示されます。タップすると、WhatsApp は電話番号を含む連絡先の Webhook を配信します。電話番号を CRM に保存し、後続のアウトバウンドメッセージで使用します。

完全な Webhook ペイロード構造については、受信メッセージ API リファレンスを参照してください。

自由形式の対話型要求 [#free-form-interactive-request-request-phone-number]

アクティブな 24 時間セッション 中にこのオプションを使用すると、事前に承認されたテンプレートを必要とせずにユーザーの電話番号を要求できます。

POSTリクエストを/whatsapp/1/message/interactive/request-contact-infoに送信します。

json

2 "from": "{{sender}}",

3 "to": "{{destination}}",

4 "messageId": "{{$uuid}}",

5 "content": {

6 "body": {

7 "text": "Some text"

8 }

9 },

10 "callbackData": "callback data"

11}

from: ご登録いただいたWhatsApp送信者番号です。
to: ユーザーの電話番号または BSUID。
content.body.text: 連絡先共有プロンプトの上に表示されるメッセージテキスト。
callbackData: 配信レポートの Webhook で返されるオプションのデータ。

テンプレートボタンの要求 [#template-button-request-request-phone-number]

このオプションを使用して、24 時間のセッション期間外 の電話番号をリクエストします。「ユーティリティ」または「マーケティング」テンプレートにREQUEST_CONTACT_INFOボタンを追加します。WhatsApp はボタンラベルを自動的に設定し、カスタマイズをサポートしていません。

次に、REQUEST_CONTACT_INFOボタンが付いたテンプレート作成ペイロードを示します。

json

2 "name": "order_share_contact",

3 "language": "en",

4 "category": "UTILITY",

5 "structure": {

6 "body": {

7 "text": "Your order has been shipped! Share your contact info so we can reach you with delivery updates."

8 },

9 "buttons": [

10 {

11 "type": "REQUEST_CONTACT_INFO"

12 }

13 ]

14 }

15}

インテグレーション要件 [#integration-requirements]

ユーザー名と BSUID をサポートするには、次のように統合を更新します。

**BSUID の Webhook を解析します。
- from は電話番号または BSUID として扱います。すべての受信メッセージに対してcontact.userIdを読み取ります。
**BSUIDを保管します。
- 顧客レコードにuserIdフィールドを追加し、電話番号と一緒に安定したWhatsApp識別子として使用します。
処理 'ユーザー_id_update' **イベント。
- ユーザーが電話番号を変更すると、Metaは古いユーザーIDと新しいユーザーIDでこのイベントを送信します。それに応じてレコードを更新します。
**必要に応じてBSUIDに送信します。
- ユーザー名のみのユーザーに返信する場合は、「宛先」フィールドにuserIdを使用します。
**認証制限を考慮してください。
- ワンタップ、ゼロタップ、およびコピーコード認証テンプレートには電話番号が必要であり、BSUID は使用できません。OTP（ワンタイムパスワード）を必要とする可能性のあるユーザーに電話番号が登録されていることを確認します。

ロールアウトのタイムライン [#timeline]

BSUID、ID フィールド (contact.userId、contact.username、contact.parentUserId)、連絡先帳、および REQUEST_CONTACT_INFO テンプレートボタンはすでに使用可能です。

ユーザー名の採用は、地域全体で徐々に展開されています。ロールアウトのタイムラインはMetaによって管理されており、変更される可能性があります。

詳細については、Metaのビジネススコープのユーザー IDドキュメントを参照してください。

支える [#support]

API 統合に関する質問や、ユーザー名や BSUID に関連する不正行為の報告については、 NTT CPaaS サポートにお問い合わせください。

関連ページ

WhatsApp統合を管理する
WhatsApp 送信者のメッセージング制限、品質評価、メッセージングウィンドウを設定します。

追加機能
ID 変更検出、連絡先管理、その他の高度な WhatsApp 機能を調べてください。

受信メッセージ
Webhookペイロード構造など、顧客からのWhatsAppメッセージを受信して処理する方法を学びます。