WhatsApp 用戶名與業務範圍用戶 ID(BSUID):Cloud API Webhook 有何改變
WhatsApp 用戶名讓用戶以名稱取代電話號碼顯示,因此自 2026 年 4 月初起,Cloud API 訊息 Webhook 亦會在 user_id 與 from_user_id 中附上業務範圍用戶 ID(BSUID),例如 US.13491208655302741918。若某用戶設有用戶名,30 天內與該號碼沒有任何訊息或通話往來,且不在通訊錄內,則 wa_id 與 from 會被省略。
easyCoexistence 透過 Coexistence 將 WhatsApp Business 應用程式號碼連接至 Cloud API,並按 Meta 的發送方式,將其 messages 及 smb_message_echoes Webhook(包括 BSUID 欄位)路由至你的端點;get_api_credentials 則為你的程式碼提供回覆所需的資料,讓你以 recipient 回覆。
BSUID 開始出現於 Cloud API Webhook 的時間,早於用戶名推出予 WhatsApp 用戶的時間。
API 開始接受發送予 BSUID 之訊息的時間,此時在 recipient 而非 to 中設定。
回溯期,以每個業務電話號碼計算:期間內只要與用戶有任何訊息或通話,其號碼便會保留於 Webhook 中。
BSUID 的兩位字母國家代碼及句點之後,大多為英數字元。
訊息 API 錯誤:此訊息不支援以業務範圍用戶 ID(BSUID)為收件人。
系統訊息類型,用於在沒有電話號碼的情況下回報 BSUID 的變更,舊 BSUID 位於 previous_user_id 中。
什麼是 WhatsApp 用戶名與 BSUID?
用戶名是 WhatsApp 用戶可以設定的選用唯一名稱,會在應用程式中取代電話號碼顯示;Meta 在 2026 年逐步推出用戶名。BSUID 是 Meta 新增的後台識別碼,讓業務仍能辨別各用戶:由系統自動生成,每個 Business Portfolio 與用戶的配對各不相同,格式為 ISO 3166 兩位字母國家代碼、句點,加上最多 128 個英數字元。Meta 要求合作夥伴及直接整合的業務支援此識別碼,因為沒有任何業務能控制其用戶是否採用用戶名。
哪些欄位承載新的識別碼?
在 messages、status、system 及 user_preferences Webhook 中,新屬性與原本存放電話號碼的欄位並列。父級欄位只會出現在獲 Meta 登記使用父級 BSUID 的 Business Portfolio 中,這些父級 BSUID 可跨已登記的 Business Portfolio 通用:
電話號碼何時會被省略?
當用戶設有用戶名,且 Meta 的三項條件皆不成立時。若業務電話號碼在過去 30 天內曾向該用戶的號碼發送訊息或撥打電話、曾在該期間收到其訊息或來電,或該用戶在通訊錄內,電話號碼便會保留於 Webhook 中。30 天回溯期以每個業務電話號碼計算,因此同一 Business Portfolio 中的第二個號碼,可能只會收到該用戶的 BSUID。未設用戶名的用戶,仍會同時附上電話號碼與 BSUID。
收到的訊息現在是什麼樣子?
與以往相近,BSUID 會附在電話號碼旁,或取代其位置。在 Meta 的範例中,若某用戶設有用戶名且其號碼無法分享,contacts 會包含 profile.name、profile.username 與 user_id,而訊息則以 from_user_id 取代過去 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?" }
}]
}
}]
}]
}狀態 Webhook 有何改變?
已發送、已送達及已讀狀態會新增 contacts 陣列,包括用戶名稱、user_id、號碼可分享時的 wa_id,以及已送達及已讀狀態中的 username。在狀態中,recipient_user_id 承載 BSUID;若你是發送至 BSUID 而號碼無法分享,則會省略 recipient_id。失敗狀態沒有 contacts 陣列,若訊息是發送至電話號碼,則會省略 recipient_user_id,因此應以訊息 id 將失敗記錄與原訊息配對。
應如何儲存及配對用戶?
先以 BSUID 為主,並在電話號碼送達時以之作為第二個鍵。請以字串形式完整儲存 BSUID,包括國家代碼及句點,因為 Meta 會拒絕任何改動其部分內容的請求;若你的 Business Portfolio 已獲登記,亦應儲存父級 BSUID。在 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 項目會載有 input 及 user_id,而非 wa_id。除 one-tap、zero-tap 及 copy code 驗證範本外,任何訊息類型皆可使用,這些範本需要電話號碼;而且只有同一 Business Portfolio 中的號碼才能觸達 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 按鈕,將其加入實用類或行銷範本,或以 request_contact_info 類型的互動訊息發送。用戶點擊後會在對話中分享其號碼,並發出 contacts Webhook,其中 origin 為 contact_request,號碼位於 phones[].wa_id;手動分享的聯絡人則以 origin 為 other 並附 vCard 送達。Meta 於 2026 年 7 月初開放此按鈕,其標籤無法自訂。
什麼是通訊錄?
這是 Meta 為每個 Business Portfolio 代為保存的儲存空間,無需任何整合工作:業務電話號碼一旦與用戶的電話號碼發生訊息往來、通話或接收其來電,該號碼與 BSUID 便會被記錄,用以在日後 Webhook 中補上電話號碼,無論用戶是否設有用戶名。只有通訊錄推出後的互動才會計算。可在「Business settings」的「Business info」中關閉,此舉會刪除其內容;GET 或 DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book 並附 bsuid,則可查核或刪除單一項目。
Coexistence 整合應作出哪些改動?
其對三種僅 Coexistence 號碼才會收到的 Webhook 的處理方式,同樣會改變。history 中,每個對話新增一個 context 物件,內含 wa_id、user_id 及 username,其訊息則新增 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。配對 echo 及匯入的對話時,請同時以 user_id 與號碼配對。
在用戶採用用戶名之前,如何測試?
使用 Meta 在應用程式控制台中的測試工具:依次進入 Use cases、Connect with customers through WhatsApp、Customize、Configuration,然後點擊 messages Webhook 旁的 Test 連結,即可向你的端點發送範例。它涵蓋四種情境的收到訊息及狀態:
- 用戶沒有用戶名:包含 BSUID 及電話號碼欄位,不含用戶名。
- 用戶有用戶名,但號碼無法取得:包含用戶名及 BSUID,不含電話號碼欄位。
- 用戶有用戶名,且號碼可取得:包含用戶名、BSUID 及電話號碼。
- Business Portfolio 已登記父級 BSUID:除該 Business Portfolio 自身的 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 的變更會以 user_changed_number 或 user_changed_user_id 類型的系統訊息,在 messages 中送達。
- 只以 to 配對 Coexistence 的 echo。在 smb_message_echoes 中,to 欄位可被省略,因此若不同時配對 to_user_id,在應用程式中輸入的回覆便會被忽略。
每個連接均全天候 24/7 監察。每個連接每月 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 可否跨 Business Portfolio 使用?
不可。BSUID 只屬於一個 Business Portfolio 及用戶,其他 Business Portfolio 的號碼無法向其發送訊息。獲 Meta 登記的受管理業務會取得父級 BSUID,其在國家代碼之後會附 ENT,可跨其已登記的 Business Portfolio 使用。
easyCoexistence 每個 WhatsApp 號碼收費多少?
每個連接每月 US$ 9 至 US$ 0.75,視乎你的連接數量而定,首 3 天免費。Meta 本身的訊息費用仍由你的 WhatsApp Business Account 付款方式支付。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期