WhatsApp ユーザー名と事業者スコープのユーザー ID(BSUID):Cloud API の Webhook で変わること
WhatsApp のユーザー名では、電話番号の代わりに名前を表示できます。そのため 2026 年 4 月上旬以降、Cloud API のメッセージ Webhook には、事業者スコープのユーザー ID(BSUID、例:US.13491208655302741918)が user_id と from_user_id に含まれるようになりました。ユーザー名を持ち、30 日間この番号とのメッセージや通話がなく、連絡先にも登録されていないユーザーの場合、wa_id と from は省略されます。
easyCoexistence は、Coexistence を通じて WhatsApp Business アプリの番号を Cloud API に接続し、Meta が送信したとおりに messages と smb_message_echoes の Webhook をエンドポイントへ転送します。
BSUID が Cloud API の Webhook に現れ始めた時期(ユーザー名がユーザーに届く前)。
API が BSUID 宛てのメッセージを受け付け始めた時期。宛先は to ではなく recipient に設定します。
電話番号ごとの遡及期間。この期間内にユーザーとメッセージや通話があれば、Webhook にその番号が残ります。
BSUID の国コードとピリオドの後に続く英数字の大部分。
Messages API のエラー:Business-scoped User ID (BSUID) recipients are not supported for this message.
BSUID の変更を電話番号なしで報告するシステムメッセージタイプ。変更前の BSUID は previous_user_id に入ります。
WhatsApp ユーザー名と BSUID とは何ですか?
ユーザー名は、WhatsApp ユーザーが設定できる任意の一意な名前で、電話番号の代わりにアプリに表示されます。Meta は 2026 年に段階的にユーザー名を展開しています。BSUID は、事業者がユーザーを区別できるように Meta が追加したバックエンド識別子です。自動的に生成され、事業者ポートフォリオとユーザーの組み合わせごとに一意で、ISO 3166 の 2 文字の国コード、ピリオド、最大 128 文字の英数字で構成されます。どの事業者もユーザーがユーザー名を採用するかを管理できないため、Meta はパートナーと直接連携する事業者にこれへの対応を求めています。
どのフィールドに新しい識別子が入りますか?
電話番号を保持していたフィールドの隣に新しいプロパティが追加されます。対象は messages、status、system、user_preferences の各 Webhook です。親フィールドは、Meta が親 BSUID に登録した事業者ポートフォリオにのみ表示されます。親 BSUID は、登録済みのポートフォリオ間で機能します:
電話番号が省略されるのはいつですか?
ユーザーがユーザー名を持ち、Meta の 3 つの条件のどれも満たさない場合です。事業者の電話番号が過去 30 日以内にそのユーザーの番号へメッセージまたは通話した、あるいはその期間内にその番号からメッセージまたは通話を受けた、またはユーザーがポートフォリオの連絡先に登録されている場合、番号は Webhook に残ります。30 日間の遡及期間は電話番号ごとに数えられるため、同じポートフォリオ内の別の番号は、同じユーザーについて BSUID のみを受け取ることがあります。ユーザー名を持たないユーザーは、電話番号と BSUID の両方を含んだまま届きます。
受信メッセージはどう見えますか?
以前と同様ですが、BSUID が電話番号の横に、あるいは電話番号の代わりに入ります。番号を共有できないユーザー名持ちのユーザーの Meta の例では、contacts に profile.name、profile.username、user_id が入り、メッセージには以前 from があった場所に from_user_id が入ります:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
"contacts": [{
"profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
"user_id": "US.13491208655302741918"
}],
"messages": [{
"from_user_id": "US.13491208655302741918",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
"timestamp": "1749416383",
"type": "text",
"text": { "body": "Does it come in another color?" }
}]
}
}]
}]
}ステータス Webhook はどう変わりますか?
送信済み、配信済み、既読のステータスには、ユーザーの名前、user_id、番号を共有できる場合の wa_id を含む contacts 配列が追加されます。配信済みと既読では username も追加されます。ステータスでは recipient_user_id が BSUID を保持し、BSUID 宛てに送信して番号を共有できない場合は recipient_id が省略されます。失敗したステータスには contacts 配列がなく、電話番号宛てに送信した場合は recipient_user_id も省略されるため、失敗はメッセージ ID で紐付けてください。
ユーザーはどのように保存し、照合すべきですか?
まず BSUID で、電話番号が届いた場合はそれを 2 つ目のキーとして使ってください。BSUID は国コードとピリオドを含めて文字列全体を保存してください。一部でも変更されたリクエストは Meta が拒否するためです。ポートフォリオが登録済みの場合は親 BSUID も保存してください。既存のレコードは、wa_id が届いている間は wa_id で結合し、BSUID を横に保持してください。後からユーザー名を採用したユーザーは、番号なしで戻ってくることがあるためです。Meta の FAQ も、CRM やそれにデータを渡すツールで同じ結合を行うよう求めています。
ユーザーが電話番号を変更したらどうなりますか?
その人の BSUID は再生成され、変更は messages フィールドにシステムメッセージとして届きます。Meta には購読すべき user_id_update フィールドがないためです。system.type は、新しい番号を共有できる場合は user_changed_number、BSUID の変更のみ報告できる場合は user_changed_user_id になります。system.user_id には新しい BSUID、system.previous_user_id には古い BSUID が入り、これでレコードを引き継げます。両方のタイプを処理してください。
BSUID だけで知られるユーザーにどう返信しますか?
/<BUSINESS_PHONE_NUMBER_ID>/messages に、recipient を BSUID に設定し、to を省略して送信します。両方がある場合は to が優先され、返信は電話番号宛てになります。レスポンスの contacts エントリには wa_id ではなく input と user_id が入ります。ワンタップ、ゼロタップ、コピーコード認証テンプレート以外のすべてのメッセージタイプで使えますが、これらは電話番号が必要です。BSUID に届くのは同じ事業者ポートフォリオ内の番号のみです。エラーコード 131062 は、そのメッセージタイプが BSUID の宛先を受け付けないことを意味します。
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"recipient": "US.13491208655302741918",
"type": "text",
"text": { "body": "Yes, it also comes in blue." }
}電話番号の提供を利用者に求めるには?
REQUEST_CONTACT_INFO ボタンを使います。ユーティリティまたはマーケティングのテンプレートに追加するか、type が request_contact_info のインタラクティブメッセージとして送信します。ボタンをタップしたユーザーはスレッド内で番号を共有し、origin が contact_request、番号は phones[].wa_id に入った contacts Webhook が届きます。手動で共有された連絡先は origin が other で、vCard が届きます。Meta は 2026 年 7 月上旬にこのボタンを提供開始しており、ラベルはカスタマイズできません。
連絡先とは何ですか?
Meta が事業者ポートフォリオごとにホストするストアで、統合作業は不要です。事業者の電話番号がユーザーの電話番号にメッセージを送る、通話する、またはそこから受信すると、その番号と BSUID が記録されます。記録された情報は、ユーザー名の有無にかかわらず、後続の Webhook に電話番号を補うために使われます。開始後のやり取りのみが対象です。Meta Business Suite の「ビジネス設定」「ビジネス情報」からオフにでき、保存されたデータは削除されます。また GET または DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book で、bsuid を指定して 1 件を確認または削除できます。
Coexistence 連携では何を変更すべきですか?
Coexistence 番号だけが受け取る 3 つの Webhook の処理も変わります。history では、各スレッドに wa_id、user_id、username を含む context オブジェクトが追加され、そのメッセージには from_user_id が追加されます。smb_message_echoes には contacts 配列が追加されます。message_echoes[].to は省略されることがあり、その場合は to_user_id が BSUID を保持します。WhatsApp Business アプリで行われた編集や取り消しも同じ形式で届きます。smb_app_state_sync では、連絡先の phone_number が省略され、その横に user_id と username が入ります。エコーとインポートしたチャットは、番号に加えて user_id でも照合してください。
ユーザーがユーザー名を採用する前にどうテストできますか?
App ダッシュボードの Meta テストツールを使います。「Use cases」「Connect with customers through WhatsApp」「Customize」「Configuration」の順に進み、messages Webhook の横にある「Test」リンクをクリックすると、サンプルがエンドポイントに送られます。受信メッセージとステータスを、次の 4 つのシナリオでカバーします:
- ユーザー名のないユーザー:BSUID と電話番号のフィールドがあり、username はありません。
- 番号が利用できないユーザー名持ちのユーザー:username と BSUID があり、電話番号のフィールドはありません。
- 番号が利用できるユーザー名持ちのユーザー:username、BSUID、電話番号があります。
- 親 BSUID に登録されたポートフォリオ:ポートフォリオ自身の BSUID の横に親 BSUID があります。
easyCoexistence は BSUID をどう扱いますか?
Meta が送信したとおりに受け渡します。set_webhook_destination で設定した番号は、messages と smb_message_echoes の Webhook を Meta から直接受け取ります。user_id、from_user_id、to_user_id、username も含まれます。自動化または転送を有効にすると、easyCoexistence は Meta が送った値をそのまま転送します。BSUID に返信するには、コードで get_api_credentials を使います。これは番号の電話番号 ID、送信エンドポイント、利用可能な場合は独自のトークンを返します。send_message と send_template ツールは、国際形式の数字で電話番号を受け取ります。
よくある間違い
- wa_id だけでコンタクトを照合しないでください。30 日間この番号と接触がないユーザー名持ちのユーザーは、user_id と from_user_id だけで届くため、wa_id を必須とするハンドラーはそのメッセージを取りこぼします。
- BSUID の国コードを削らないでください。Meta は国コードとピリオドを含む値全体を求めており、一部でも変更されたリクエストは失敗します。
- user_id_update フィールドを待たないでください。Meta にはそのフィールドがありません。BSUID の変更は、type が user_changed_number または user_changed_user_id のシステムメッセージとして messages に届きます。
- smb_message_echoes を to だけで照合しないでください。to フィールドは省略されることがあるため、to_user_id も照合しないと、アプリで入力された返信を見落とします。
BSUID のフィールドも含まれます。get_api_credentials は、recipient を指定して返信するためにコードが必要とする情報を提供します。すべての接続は 24 時間体制で監視されます。料金は接続ごとに月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 までです。最初の 3 日間は無料です。
よくある質問
ユーザー名のないユーザーにも BSUID はありますか?
はい。Meta は、ユーザーがユーザー名を持っているかどうかにかかわらず、messages Webhook に user_id を設定します。そのため、ほとんどのユーザーは電話番号と BSUID の両方を受け取ります。
Coexistence の番号には事業者ユーザー名を設定できますか?
はい。2026 年 6 月 29 日以降、事業者は Meta Business Suite、WhatsApp Manager、WhatsApp Business アプリ、または Username API で事業者ユーザー名を採用または変更できます。事業者の電話番号は非表示になりません。business_username_updates が各ステータス変更を報告します。
BSUID は事業者ポートフォリオをまたいで機能しますか?
いいえ。BSUID は 1 つのポートフォリオとユーザーに属し、別のポートフォリオの番号からはメッセージを送信できません。Meta が登録した管理対象の事業者には親 BSUID が与えられます。親 BSUID は国コードの後に ENT が付き、登録済みのポートフォリオ間で機能します。
easyCoexistence の WhatsApp 番号の料金はいくらですか?
接続ごとに月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 までです。最初の 3 日間は無料です。Meta 自身のメッセージ料金は、WhatsApp Business Account に設定された支払い方法に引き続き請求されます。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日