WhatsApp BSUID 遷移 7 月 7 日啟動 — 純收訊團隊嘅五項自查清單 — UnifyPort
Meta 正在改變 WhatsApp API 識別用戶嘅方式。由 2026 年 7 月 7 日（Wave 1）開始，每個 webhook payload 都會出現一個叫做 Business-Scoped User ID（BSUID）嘅新欄位——而啟用咗 WhatsApp 用戶名嘅用戶，電話號碼可能會完全消失。
如果你嘅客服佇列、CRM 整合或者 AI agent 管線透過 WhatsApp 收訊息，呢次遷移會影響到你嘅程式碼。影響幾大，取決於你嘅 WhatsApp 訊息係經邊條路徑到達後端。
呢篇文章係一份清單。五個要檢查嘅範疇、一個決策矩陣，同埋一個大部分細團隊真正想知嘅問題嘅明確答案：「7 月 7 號之前我使唔使做啲嘢？」
BSUID 究竟係咩
每個 WhatsApp 用戶都會獲得一個新識別碼：Business-Scoped User ID。格式係兩個字母嘅國家代碼、一個點、加上最多 128 個英數字元——例如 BR.1A2B3C4D5E6F7G8H9I0J。關鍵特性：同一個人同唔同嘅商戶互動，會得到唔同嘅 BSUID。你嘅系統入面用戶 Alice 嘅 BSUID，同另一間公司入面 Alice 嘅 BSUID 係唔一樣嘅。
Meta 嘅推出時間表：
| 階段 | 日期 | 範圍 |
|---|---|---|
| Wave 1 | 2026 年 7 月 7 日 | 首批市場 |
| Wave 2 | 2026 年 7 月 20 日 | 擴展推出 |
| 全球 | 2026 年 9 月 | 所有其餘市場 |
BSUID 已經喺 2026 年 3 月 31 日開始以新嘅 user_id 欄位出現喺 webhook payload 入面。但真正嘅破壞性變更喺 Wave 1 先嚟：一旦用戶啟用 WhatsApp 用戶名，wa_id 同 from 欄位入面嘅電話號碼可能會唔再出現。
自查清單：五個要檢查嘅範疇
1. Webhook payload 解析
有咩變化： 每個訊息 webhook 都會出現新嘅 user_id 欄位。對於啟用咗用戶名嘅用戶，之前包含電話號碼嘅 wa_id 同 from 欄位可能會改為包含 BSUID——或者完全缺失。
要檢查咩： 你嘅 webhook handler 係咪假設 from 一定係電話號碼？有冇用正則表達式匹配數字、拿佢做資料庫主鍵、或者傳俾電話號碼驗證函式庫？當 from 入面係 BR.1A2B3C4D5E... 而唔係 5511999887766 嘅時候，呢啲全部都會出事。
2. CRM 同聯絡人匹配
有咩變化： 如果你嘅 CRM 係用電話號碼做客戶記錄嘅主鍵，嚟自啟用咗用戶名嘅用戶嘅訊息可能完全唔帶電話號碼。你就搵唔到個客戶。
要檢查咩： 你嘅聯絡人資料庫能唔能夠同時儲存同匹配 BSUID 同電話號碼？Meta 提供咗 Contact Book API，保留咗舊有對話入面嘅電話號碼到 BSUID 嘅映射——但你要喺電話號碼從新 webhook 中消失之前就調用佢。
3. 對話歷史同串接
有咩變化： 如果你係用電話號碼嚟串接對話（例如「顯示 +5511999887766 嘅所有訊息」），同一個人嘅訊息會開始以 BSUID 識別碼到達。除非你已經將舊嘅電話號碼記錄同新嘅 BSUID 連結起嚟，否則對話歷史會一分為二。
要檢查咩： 你嘅訊息儲存係咪用電話號碼做對話串嘅主鍵？如果係，計劃做一次回填：喺 Wave 1 之前用 Contact Book 映射將現有嘅電話號碼記錄同佢哋嘅 BSUID 連結起嚟。
4. 範本同外發訊息定址
有咩變化： 發送範本訊息（外發）嘅時候，你最終需要用 BSUID 而唔係電話號碼嚟定址收件人——特別係對於已經啟用咗用戶名、電話號碼唔再暴露嘅用戶。
要檢查咩： 如果你會發送主動訊息（訂單確認、物流更新、預約提醒），你嘅發送邏輯係咪用電話號碼嚟解析收件人？你需要儲存最近一次收到嘅訊息入面嘅 BSUID，用嚟做之後嘅外發調用。
5. 資料儲存同合規
有咩變化： BSUID 係一種新嘅個人身份資料。佢哋係按商戶劃分嘅（所以唔能夠用嚟跨公司交叉比對用戶），但喺大部分私隱法規框架下仍然屬於 PII。
要檢查咩： 你嘅資料保留政策有冇涵蓋新嘅識別碼類型？如果你有 GDPR/PDPO 刪除流程會列舉用戶嘅所有已儲存識別碼，BSUID 需要包含喺入面。
你係行邊條路？
唔係每個團隊都需要處理全部五項清單。取決於你嘅 WhatsApp 訊息係點到達後端。
| 整合路徑 | 適用嘅清單項目 | 遷移工作量 |
|---|---|---|
| Cloud API（直接） | 全部五項 | 高——你直接解析 Meta 嘅原始 webhook，每個 payload 變更都直接影響你嘅程式碼 |
| BSP（Wati、360dialog 等） | 第 2、3、4、5 項 | 中——你嘅 BSP 可能會抽象化 webhook 格式，但你嘅 CRM 同發送邏輯仍然需要更新 |
| 非官方收訊介面 | 無 | 零——繼續睇落去 |
點解非官方收訊唔受影響
如果你嘅 WhatsApp 訊息係透過 UnifyPort 嘅非官方介面到達，BSUID 遷移完全唔會影響你嘅管線。原因係：UnifyPort 唔經 Meta 嘅 Cloud API 路由訊息。非官方路徑直接連接 WhatsApp——同一部行緊 WhatsApp 嘅手機一樣——所以你嘅 webhook 收到嘅訊息本身就唔係 Cloud API payload 格式。
你嘅 webhook 仍然收到一直以來嘅 message.received 事件：
{
"event": "message.received",
"account_id": "acct_3qPmRz",
"provider": "whatsapp",
"from": "user_88c1ae",
"text": "你好，訂單 #2241 寄咗未？",
"timestamp": 1751875200,
"message_id": "wa_msg_f4e29a"
}from 欄位係 UnifyPort 自己嘅標準化用戶識別碼——唔係電話號碼，亦唔係 BSUID。佢從來就唔係電話號碼，所以當 Meta 改變識別碼方案嘅時候，你唔需要做任何遷移。你嘅 CRM 匹配、對話串接同 webhook 解析全部繼續正常運作。
你 webhook 端點嘅 HMAC-SHA256 簽名驗證亦唔受影響——signing secret 同簽名格式都係 UnifyPort 嘅，唔係 Meta 嘅。
呢個禮拜要做咩
如果你用緊 Cloud API 或 BSP：由清單第 1 項（webhook 解析）開始。記錄一批收到嘅 webhook，檢查 user_id 欄位係咪已經存在——佢由 3 月 31 日起一直喺度推出。如果有，你就知道你嘅 payload 已經開始變。喺 7 月 7 日之前完成第 2 至 5 項。
如果你用緊非官方收訊路徑：乜都唔使變。BSUID 遷移係 Cloud API 嘅事，你嘅訊息根本唔經 Cloud API。繼續做嘢就得。