WhatsApp usernames at business-scoped user IDs (BSUID): ano ang nagbabago sa Cloud API webhooks
Ang WhatsApp usernames ay nagbibigay-daan sa mga user na magpakita ng pangalan sa halip na kanilang numero ng telepono, kaya mula unang bahagi ng Abril 2026, ang mga mensahe sa Cloud API webhooks ay may dala na ring business-scoped user ID (BSUID), gaya ng US.13491208655302741918, sa user_id at from_user_id. Para sa user na may username na walang mensahe o tawag sa numero sa loob ng 30 araw at wala sa contact book, iniiwan ang wa_id at from.
Ikinokonekta ng easyCoexistence ang numero ng WhatsApp Business app sa Cloud API sa pamamagitan ng Coexistence at idinadaan ang mga webhook ng messages at smb_message_echoes sa inyong endpoint gaya ng pagpapadala ng Meta, kasama ang BSUID fields, habang ang get_api_credentials ay nagbibigay sa inyong code ng kailangan para mag-reply gamit ang recipient.
Kailan nagsimulang lumitaw ang mga BSUID sa Cloud API webhooks, bago pa maabot ng usernames ang mga WhatsApp user.
Kailan nagsimulang tanggapin ng API ang mga mensaheng ipinapadala sa BSUID, na itinatakda sa recipient sa halip na to.
Lookback, kada numero ng negosyo, kung saan anumang mensahe o tawag sa user ay nagpapanatili ng kanilang numero sa webhooks.
Karamihan sa alphanumeric na karakter pagkatapos ng dalawang-letrang country code at tuldok ng BSUID.
Error ng Messages API: Business-scoped User ID (BSUID) recipients are not supported for this message.
System message type para sa pagbabago ng BSUID na iniulat nang walang numero ng telepono, kasama ang lumang BSUID sa previous_user_id.
Ano ang WhatsApp usernames at BSUID?
Ang username ay opsyonal at natatanging pangalan na maaaring itakda ng isang WhatsApp user, na lumalabas sa app sa halip na numero ng telepono; unti-unting inilulunsad ng Meta ang usernames sa 2026. Ang BSUID ay backend identifier na idinagdag ng Meta para makilala pa rin ng mga negosyo ang kanilang mga user: awtomatikong nabubuo, natatangi sa bawat pares ng Business Portfolio at user, at isinusulat bilang two-letter country code ng user ayon sa ISO 3166, tuldok, at hanggang 128 alphanumeric na karakter. Kinakailangan ng Meta na suportahan ito ng mga partner at direktang naka-integrate na negosyo, dahil walang negosyong nagkokontrol kung gagamitin ng mga user ang usernames.
Aling mga field ang nagdadala ng bagong identifier?
Mga bagong property sa tabi ng mga dating naglalaman ng numero ng telepono, sa messages, status, system, at user_preferences webhooks. Lumilitaw lamang ang parent fields para sa Business Portfolio na naka-enroll ng Meta sa parent BSUIDs, na gumagana sa lahat ng naka-enroll na portfolio:
Kailan iniiwan ang numero ng telepono?
Kapag may username ang user at wala sa tatlong kondisyon ng Meta ang natutugunan. Nananatili ang numero ng telepono sa webhooks kung nag-message o tumawag ang numero ng negosyo sa numero ng user sa nakalipas na 30 araw, nakatanggap ng mensahe o tawag mula dito sa loob ng panahong iyon, o nasa contact book ng portfolio ang user. Binibilang ang 30-day lookback kada numero ng negosyo, kaya maaaring BSUID lamang ang matanggap ng pangalawang numero sa parehong portfolio para sa parehong user. Ang mga user na walang username ay patuloy na dumarating na may kasamang numero ng telepono at BSUID.
Ano ang itsura ng papasok na mensahe ngayon?
Katulad ng dati, na may BSUID sa tabi ng numero ng telepono o kapalit nito. Sa halimbawa ng Meta ng user na may username na hindi maibabahagi ang numero, ang contacts ay naglalaman ng profile.name, profile.username at user_id, at ang mensahe ay may from_user_id sa lugar ng dating from:
{
"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?" }
}]
}
}]
}]
}Paano nagbabago ang status webhooks?
Ang sent, delivered at read na status ay nakakakuha ng contacts array na may pangalan ng user, user_id, wa_id kapag maibabahagi ang numero, at username sa delivered at read. Sa statuses, dala ng recipient_user_id ang BSUID, at inaalis ang recipient_id kapag nagpadala kayo sa BSUID at hindi maibabahagi ang numero. Ang failed status ay walang contacts array at hindi kasama ang recipient_user_id kapag ang mensahe ay ipinadala sa numero ng telepono, kaya ikabit ang mga failure sa message id.
Paano dapat i-store at i-match ang mga user?
Sa BSUID muna, kasama ang numero ng telepono bilang pangalawang key sa tuwing dumarating ito. I-store ang buong BSUID bilang string, kasama ang country code at tuldok, dahil tinatanggihan ng Meta ang mga request na binabago ang alinmang bahagi nito, at i-store din ang parent BSUID kung naka-enroll ang inyong portfolio. I-join ang umiiral na record sa wa_id habang dumarating pa ito, at panatilihin ang BSUID sa tabi nila, dahil ang user na magkakaroon ng username sa hinaharap ay maaaring bumalik na walang numero. Humihingi ang FAQ ng Meta ng parehong joins sa mga CRM at sa mga tool na pinapakainan nila.
Ano ang mangyayari kapag binago ng user ang kanyang numero ng telepono?
Muling bubuuin ang kanilang BSUID, at dadating ang pagbabago sa messages field bilang system message, dahil walang user_id_update field ang Meta na maaaring i-subscribe. Ang system.type ay user_changed_number kapag maibabahagi sa iyo ang bagong numero, o user_changed_user_id kapag tanging pagbabago ng BSUID lamang ang maiuulat; hawak ng system.user_id ang bagong BSUID at ng system.previous_user_id ang luma, na siyang paraan para mailipat ang record. Hawakan ang dalawang uri.
Paano sasagot sa user na BSUID lamang ang alam?
Magpadala sa /<BUSINESS_PHONE_NUMBER_ID>/messages na may recipient na nakatakda sa BSUID at walang to; kapag parehong nakalagay, mananaig ang to at mapupunta ang reply sa numero ng telepono. Ang contacts entry ng response ay may input at user_id sa halip na wa_id. Anumang uri ng mensahe ay gumagana maliban sa one-tap, zero-tap at copy code authentication templates, na nangangailangan ng numero ng telepono, at ang mga numero lamang sa parehong Business Portfolio ang makaabot sa BSUID. Ibig sabihin ng error 131062 na hindi tumatanggap ng BSUID recipients ang uri ng mensahe.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"recipient": "US.13491208655302741918",
"type": "text",
"text": { "body": "Yes, it also comes in blue." }
}Paano humingi ng numero ng telepono sa user?
Gamit ang REQUEST_CONTACT_INFO button, idinagdag sa utility o marketing template o ipinadala bilang interactive na mensahe ng uri na request_contact_info. Kapag pinindot ito ng user, ibabahagi niya ang numero sa thread, at darating ang contacts webhook na may origin na contact_request at ang numero sa phones[].wa_id; ang contact na ibinahagi nang manu-mano ay darating na may origin na other at vCard. Inilabas ng Meta ang button noong unang bahagi ng Hulyo 2026, at hindi maaaring baguhin ang label nito.
Ano ang contact book?
Isang store na hino-host ng Meta para sa bawat Business Portfolio, nang walang integration work: kapag nag-message, tumawag, o nakatanggap ng mensahe o tawag ang numero ng negosyo mula sa numero ng telepono ng user, ire-record ang numerong iyon at ang BSUID at gagamitin para punan ang mga susunod na webhook ng numero ng telepono, may username man o wala. Tanging interaksyon pagkatapos ng paglulunsad nito ang binibilang. Maaari itong i-off sa Meta Business Suite, Business settings, Business info, na magbubura ng laman nito, at ang GET o DELETE sa /<BUSINESS_PHONE_NUMBER_ID>/contact_book na may bsuid ay sumusuri o nag-aalis ng isang entry.
Ano ang dapat baguhin ng isang Coexistence integration?
Ang pangangasiwa nito sa tatlong webhook na tanging nakukuha ng isang Coexistence na numero, na nagbabago rin. Sa history, bawat thread ay nakakakuha ng context object na may wa_id, user_id at username, at ang mga mensahe nito ay nakakakuha ng from_user_id. Sa smb_message_echoes, idinaragdag ang contacts array, at maaaring iwan ang message_echoes[].to habang dala ng to_user_id ang BSUID; ganoon din dumarating ang mga edit at revoke na ginawa sa WhatsApp Business app. Sa smb_app_state_sync, maaaring iwan ang phone_number ng contact, kasama ang user_id at username sa tabi nito. I-match ang echoes at na-import na chat sa user_id bukod sa numero.
Paano makakapagsubok bago gamitin ng mga user ang usernames?
Gamit ang test tool ng Meta sa App Dashboard: sa ilalim ng Use cases, Connect with customers through WhatsApp, Customize, Configuration, ang Test link sa tabi ng messages webhook ay nagpapadala ng sample sa inyong endpoint. Sakop nito ang papasok na mensahe at status sa apat na sitwasyon:
- Isang user na walang username: mga field ng BSUID at numero ng telepono, at walang username.
- Isang user na may username na hindi maibabahagi ang numero: username at BSUID, na walang mga field ng numero ng telepono.
- Isang user na may username na maibabahagi ang numero: username, BSUID at numero ng telepono.
- Isang portfolio na naka-enroll sa parent BSUIDs: isang parent BSUID sa tabi ng sariling BSUID ng portfolio.
Paano hinahawakan ng easyCoexistence ang mga BSUID?
Ipinapasa nito ang mga ito gaya ng pagpapadala ng Meta. Ang numerong naka-route sa inyong endpoint gamit ang set_webhook_destination ay tumatanggap ng messages at smb_message_echoes webhooks nang direkta mula sa Meta, kasama ang user_id, from_user_id, to_user_id at username, at kapag naka-on ang automations o forwarding, ipinapasa ng easyCoexistence ang value na ipinadala ng Meta nang hindi binabago. Para mag-reply sa BSUID, gagamitin ng inyong code ang get_api_credentials, na nagbabalik ng ID ng numero ng telepono, ang send endpoint nito at, kapag available, sarili ninyong token; ang send_message at send_template tools ay tumatanggap ng numero ng telepono sa international digits.
Mga karaniwang pagkakamali
- Pag-key ng contacts sa wa_id lamang. Ang user na may username na walang contact sa numero sa loob ng 30 araw ay dumarating na may user_id at from_user_id lamang, at ang handler na nangangailangan ng wa_id ay makaliligtaan ang mensahe.
- Pag-trim ng country prefix ng BSUID. Gusto ng Meta ang buong value, kasama ang country code at tuldok, at ang request na may binagong bahagi ay pumapalya.
- Paghihintay sa user_id_update field. Wala ito sa Meta: ang pagbabago ng BSUID ay dumarating sa messages bilang system messages ng uri na user_changed_number o user_changed_user_id.
- Pag-match ng Coexistence echoes sa to lamang. Sa smb_message_echoes, maaaring iwan ang to field, kaya hindi makikita ang reply na na-type sa app maliban kung match din ang to_user_id.
Bawat koneksyon ay naka-monitor 24/7. US$ 9 hanggang US$ 0.75 kada koneksyon kada buwan, bumababa habang dumarami ang mga koneksyon, at libre ang unang 3 araw.
Mga madalas itanong
Nakakakuha rin ba ng BSUID ang mga user na walang username?
Oo. Nagtatakda ang Meta ng user_id sa messages webhooks kahit may username ang user o wala, kaya karamihan ng user ay dumarating na may kasamang numero ng telepono at BSUID.
Maaari bang magkaroon ng username ng negosyo ang isang numero ng Coexistence?
Oo. Mula Hunyo 29, 2026, maaaring magtakda o magpalit ng username ang negosyo sa Meta Business Suite, WhatsApp Manager, WhatsApp Business app o sa Username API; hindi nito itinatago ang numero ng negosyo, at iniuulat ng business_username_updates ang bawat pagbabago ng status.
Gumagana ba ang BSUID sa iba't ibang Business Portfolio?
Hindi. Ang BSUID ay kabilang sa isang portfolio at user, at hindi ito maaabot ng numero sa ibang portfolio. Ang mga managed na negosyong naka-enroll ng Meta ay nakakakuha ng parent BSUIDs, na may ENT pagkatapos ng country code, at gumagana ang mga ito sa lahat ng naka-enroll na portfolio.
Magkano ang gastos ng easyCoexistence para sa isang numero ng WhatsApp?
US$ 9 hanggang US$ 0.75 kada koneksyon kada buwan, depende sa dami ng mga koneksyon, at libre ang unang 3 araw. Nananatili sa payment method ng iyong WhatsApp Business Account ang sariling singil ng Meta sa mensahe.
Magpatuloy sa pagbabasa
Handa na po ba kayong magsimula?
I-set up ang WhatsApp Coexistence sa loob ng ilang minuto, hindi buwan. Patuloy na gumagana ang app sa telepono.
Magsimula ng Libreng TrialNa-verify noong