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

WhatsApp は、エンドユーザー向けのオプションのプライバシー機能として ユーザー名 を導入しています。ユーザーがユーザー名を採用すると、その電話番号が Webhook ペイロードに表示されなくなる可能性があります。

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

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

これらは、2 つの別々のタイムラインを持つ 2 つの別々の変更です。

変更	機能	利用可能から
BSUID	新しい `userId` フィールドは、電話番号とともにすべての受信 Webhook に表示されます	2026年5月末(全お客様)
Usernames	電話番号は、ユーザーがユーザー名を採用しており、ビジネスとの最近の履歴がない場合、Webhook から省略される場合があります	2026 年 7 月 7 日 (第 1 波および第 2 波の国);2026年9月(その他の地域)

ロールアウトは、2026 年 7 月 7 日のウェーブ 1 から始まり、続いて 2026 年 7 月 20 日にウェーブ 2、2026 年 9 月にその他の地域で展開されます。

波	国
ウェーブ 1: 2026 年 7 月 7 日	アルジェリア、アゼルバイジャン、ガーナ、リビア、ネパール
ウェーブ 2: 2026 年 7 月 20 日	ドミニカ共和国、シンガポール、コロンビア、ペルー、マレーシア
ウェーブ 3: 2026 年 9 月	世界の他の地域。2026 年 7 月 7 日までに統合を準備してください。

手記

インバウンド 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 の更新は、ユーザーが電話番号を完全に変更したときに発生します。
常に存在: 2026 年 5 月末以降、ユーザーがユーザー名を持っているかどうかに関係なく、すべてのインバウンド Webhook の contact.userId に BSUID が含まれます。

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

親 BSUID [#parent-bsuids]

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

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

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

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

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

ビジネスユーザー名 [#business-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 マネージャー、Meta Business Suite、または API を通じて、WhatsApp が予約したユーザー名を申請することができます。ブランディングに合った別のユーザー名を採用することもできます。承認されたユーザー名は、お住まいの地域でユーザー名機能が利用可能になると有効になります。

手記

NTT CPaaSを通じてビジネスユーザー名を採用するための正確なプロセスは最終決定中です。プロセスが確認され次第、詳細が続きます。

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

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

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

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

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

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

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

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

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

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

大事な

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

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

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

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

すべての変更は、ユーザー名が起動するまで追加されます。グローバルロールアウト前に、既存のペイロードからフィールドは削除されません。

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

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 に常に電話番号が含まれていると想定しないでください。このフィールドを E.164 番号として検証または解析するコードは、更新する必要があります。ユーザー名の起動後、BSUID が含まれる場合があります。

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

電話番号に送信

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]

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フィールドはオプションであり、ユーザーが設定した場合にのみ表示されます。

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

API サーフェス	畑	形容	利用可能から
MO ウェブフック	`from`	電話番号(利用可能な場合)。電話番号が利用できない場合の BSUID。	ウェーブ 1: 2026 年 7 月 7 日。第 2 波: 2026 年 7 月 20 日。グローバル:2026年9月
MO ウェブフック	`contact.phoneNumber`	ユーザーの電話番号。利用できない場合は省略されます。	2026年5月末
MO ウェブフック	`contact.userId`	BSUIDです。常に存在します。	2026年5月末
MO ウェブフック	`contact.parentUserId`	親 BSUID。承認済みのマルチポートフォリオ設定のみ。	2026年5月末
MO ウェブフック	'連絡先.ユーザー名'	ユーザーの WhatsApp ユーザー名。ユーザーが設定した場合にのみ表示されます。	2026年5月末
MTリクエスト	「に」	電話番号または BSUID を受け入れます。最大長: 150 文字。	ウェーブ 1: 2026 年 7 月 7 日。第 2 波: 2026 年 7 月 20 日。グローバル:2026年9月
DLR Webhook	「に」	元のメッセージの送信に使用された識別子を反映します。電話番号に送信する場合は電話番号、BSUID に送信する場合は BSUID。	ウェーブ 1: 2026 年 7 月 7 日。第 2 波: 2026 年 7 月 20 日。グローバル:2026年9月
DLR Webhook	「コンタクト」	`phoneNumber`、`userId`、`parentUserId`、`username`、および `name` を持つオブジェクト。送信済み、配信済み、および読み取りステータスにのみ表示されます。	2026年5月末

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

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

新しいボタンタイプREQUEST_CONTACT_INFOを「ユーティリティ」テンプレートと「マーケティング」テンプレートに追加できます。ユーザーがタップすると、メッセージスレッドで仮想連絡先カード(電話番号を含む)が共有され、WhatsAppはその番号を含む連絡先Webhookをトリガーします。

以下は、REQUEST_CONTACT_INFOボタンのあるテンプレート作成ペイロードを示しています。WhatsApp はラベルを設定し、カスタマイズを許可しないため、ボタン自体にパラメーターは必要ありません。

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}

ユーザーがボタンをタップすると、WhatsApp はユーザーの電話番号を含む連絡先 Webhook を配信します。この Webhook から電話番号を読み取り、CRM に保存し、後続の送信メッセージで使用して、今後電話番号の可視性を維持します。

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

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

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

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

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

Date (日付)	イベント
2026年4月上旬	コンタクトブックが発売されました。新しいインタラクションからの電話と BSUID のペアを自動的に保存します。
2026年5月上旬	`REQUEST_CONTACT_INFO`ボタンは、ユーティリティおよびマーケティングテンプレートで使用できます。
2026年5月末	ID フィールドは、すべての NTT CPaaS Webhook (`contact.userId`、`contact.username`、`contact.parentUserId`) に存在します。
2026年7月7日	ウェーブ 1: アルジェリア、アゼルバイジャン、ガーナ、リビア、ネパールでユーザー名の採用が開始されます。`to` フィールドは BSUID を受け入れます。
2026年7月20日	ウェーブ 2: ドミニカ共和国、シンガポール、コロンビア、ペルー、マレーシアでユーザー名の採用が開始されます。
2026年9月	ウェーブ 3: 残りのすべての市場でグローバルに展開します。

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

支える [#support]

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