WhatsApp 號碼上線（Meta Cloud API）
連接一個號碼看似只需 10 次點擊，但實際上常因步驟順序、哪個投資組合擁有哪個資源，以及 Meta 螢幕顯示「已連接」卻收不到訊息而失敗。此技能提供安全順序，以及真實發生的阻擋情況與其修復方式。
下方使用的信心標籤： [official] = 取自 developers.facebook.com（表格中有網址）；[field] = 在真實上線中發生，且修復方式經現場確認；[unconfirmed] = 曾見過，但原因或修復方式從未被證實。切勿將 [field] 或 [unconfirmed] 當作 Meta 政策。
詞彙：絕不可混淆這四項
- 商務管理組合（Business Manager）：Meta 中的公司。
- WhatsApp 商業帳號 (WABA)：存在於商務管理組合內。在 UI 中，請使用訊息帳號 ID，而非「WhatsApp 帳號/存在」ID（後者會回傳「This API is not supported」）
[field]。 - 電話號碼：存在於 WABA 內。其電話號碼 ID 並非電話號碼本身。
- Meta 應用程式：存在於開發者帳號中，並連結至商務管理組合；它持有權杖、應用程式密鑰與 Webhook。
當您提到限制時，請指明是針對哪一項。
決定計畫的限制 [official]
- 一個新的商務管理組合最多可註冊 2 個電話號碼；當商家驗證通過或達到 2,000 則訊息限制後，上限會提高至 20。
- 訊息限制是以商務管理組合為單位，由其所有號碼共享：250 → 2,000 → 10,000 → 100,000 → 無限制。一個忙碌的號碼可能會用光所有人的配額。
- 註冊與取消註冊：每個號碼每 72 小時各 10 次請求；超過此限制會出現錯誤 133016，且該號碼將被封鎖 72 小時。除錯時請勿頻繁點擊「啟用」。
- 在 WhatsApp Manager 或應用程式儀表板中新增號碼並不會將其註冊至 Cloud API；仍需要進行註冊呼叫。
- 已用於 WhatsApp（手機應用程式）的號碼必須先刪除該帳號才能註冊。
- 刪除號碼：僅限商務管理組合管理員操作，無法透過 API 進行，若已連接則需要 2 步驟 PIN 碼，且若在過去 30 天內曾發送付費訊息則無法刪除。請將刪除視為不可逆。
開始之前（一次性收集）
客戶看到的商家名稱（必須完全一致）、法定名稱、國家、完整地址、電話、網站或 Facebook 粉絲專頁、電子郵件、標誌，以及要連接的號碼。該號碼不得安裝 WhatsApp（若有，請先在該手機上刪除 WhatsApp 帳號）。決定由誰建立並保管 6 位數 PIN 碼。
安全順序（每個步驟結束時都要讀回確認）
- 商務管理組合（business.facebook.com）：在新增號碼之前，完整填寫商家資訊（法定名稱、地址、電話、網站）。若為空白，則上線會失敗，出現「your business doesn't meet WhatsApp policy」（#2494070）
[field]。 - WhatsApp 帳號 + 號碼（商務管理組合設定 → 帳號 → WhatsApp 帳號 → 新增 → 新號碼）。顯示名稱 = 客戶的商家名稱，絕非代理商名稱。透過 SMS 或語音（適用於市話）驗證
[official]。讀回確認：號碼出現在 WABA 下方。 - Meta 應用程式（developers.facebook.com → 建立應用程式 → WhatsApp 使用案例），連結至擁有該 WABA 的相同商務管理組合。應用程式在一個商務管理組合、WABA 在另一個：一切顯示綠色，但沒有任何訊息送達；將應用程式移至 WABA 所屬的商務管理組合即可修復
[field]。設定 → 基本：回傳 200 的隱私權/條款/資料刪除 URL、類別、圖示。 - 系統使用者（在包含應用程式與 WABA 的商務管理組合中）：權杖需具備
whatsapp_business_messaging+whatsapp_business_management權限，且無到期日。由人類將權杖貼到儲存位置；切勿回顯。 - ID，由您讀取，而非由人輸入：
GET /{waba-id}/phone_numbers→ 電話號碼 ID。將電話號碼存入「Phone-number-ID」變數曾導致機器人故障[field]。 - 環境變數（在確切的託管專案中）。若多個客戶專案使用相同變數名稱：請說出專案名稱並在儲存前檢查標題。曾發生客戶的 ID 被存入另一個專案，導致其正式機器人指向錯誤號碼
[field]。 - Webhook（應用程式 → WhatsApp → 設定）：
https://<domain>/webhook加上驗證權杖；訂閱messages欄位（此欄位不一定預設開啟）。然後將 WABA 訂閱至應用程式：POST /{waba-id}/subscribed_apps。 - 註冊號碼：
POST /{phone-number-id}/register加上 6 位數 PIN 碼。若該號碼已有 2 步驟驗證，請使用現有的 PIN 碼[official]。讀回確認：GET /{phone-number-id}?fields=status,platform_type,name_status→ 應顯示CONNECTED和CLOUD_API。在此之前會顯示PENDING/NOT_APPLICABLE[field]。 - 發布應用程式，然後從個人手機發送「Hi」，確認機器人會回應。
- 帳單： 在發送範本之前，於 WhatsApp 帳號上設定付款方式、時區與幣別（否則會出現 131042）
[official]。 - 最終讀回： 號碼狀態、
GET /{waba-id}/subscribed_apps僅顯示此應用程式、Webhook URL 與欄位、debug_token顯示正確的應用程式與系統使用者權杖。
顯示名稱可能在號碼已正常運作時仍處於「審核中」狀態長達數天 [field]；請勿點擊「編輯」，因為編輯會重新啟動審核。
黃金規則
- 應用程式與 WABA 必須在同一個商務管理組合。若客戶自己的商務管理組合卡在審核中，一個經實測的替代方案是將號碼放入一個可運作的商務管理組合（您的）的 WABA 中，並將應用程式放在同一個商務管理組合，保持在 2 個號碼的限制內
[field]。官方的長期路徑是成為技術服務供應商並使用 Embedded Signup。 - 預設情況下，一個客戶一個應用程式。 應用程式的回呼 URL 是預設目的地。Meta 支援每個 WABA 和每個號碼的 Webhook 覆寫
[official]，但若您未測試過，請堅持一個客戶一個應用程式。 - 當託管網域變更時，請立即在 Meta 中更新 Webhook並讀回確認。網域變更曾無聲無息地讓機器人停止運作
[field]。 - 對於應保留在 Cloud API 上的號碼，切勿使用「繼續」路徑來安裝 WhatsApp Business 應用程式，因為這會將號碼從 API 中移除
[field]。 - 先嘗試不會造成損壞的方法。 取消註冊、刪除或移動號碼是最後手段，僅在 Meta 要求時才進行（請見上方限制）。
- 健康狀態檢查只有在 Meta 回報時才是綠色： 請從 Meta 讀取電話狀態。有效的權杖無法證明號碼的狀態
[field]。 - 重新導向至商務管理組合的 URL 並不能證明誰擁有某項資產。 請確認螢幕上的商務管理組合名稱
[field]。
故障排除
| 症狀 | 原因 | 修復方式 | 標籤 / 來源 |
|---|---|---|---|
| 一切顯示綠色，但收不到訊息 | 應用程式與 WABA 在不同商務管理組合 | 在 WABA 所屬的商務管理組合建立新應用程式；移除舊應用程式的 Webhook | [field] |
| 訊息重複 / 出現「app secret mismatch」警告 | 有兩個應用程式訂閱了同一個 WABA | 移除舊應用程式的 Webhook 與訂閱 | [field] |
| 部署後機器人停止運作 | Webhook 仍指向舊網域 | 更新 Webhook 並讀回確認 | [field] |
| 客戶分享 WABA 時出現「No se pudo asignar el socio」（指派合作夥伴） | 原因從未被證實（新的或未驗證的商務管理組合、帳號審核中） | 避免分享：在一個商務管理組合內建置（請見黃金規則） | 原因 [unconfirmed]，解決方案 [field] |
| 開發者上線時出現「Business doesn't meet WhatsApp policy」（#2494070） | 商家資訊不完整 / 新的商務管理組合 | 完整填寫商家資訊；改從 WhatsApp Manager 新增號碼 | [field] |
| 使用 WABA ID 時出現「This API is not supported」 | 使用了「WhatsApp 帳號」ID | 使用訊息帳號 ID | [field] |
狀態 PENDING，平台 NOT_APPLICABLE | 已新增但未註冊 | 使用 PIN 碼執行 POST /register | [official] + [field] |
| 133005 | 2 步驟 PIN 碼錯誤 | 使用號碼現有的 PIN 碼 | 錯誤碼 |
| 133006 | 號碼未驗證 | 透過 SMS/語音驗證，然後註冊 | 錯誤碼 |
| 133008 / 133009 | PIN 碼嘗試次數過多或過快 | 等待 details 中指定的時間 | 錯誤碼 |
| 133010 | 號碼未在平台上註冊 | 註冊該號碼 | 錯誤碼 |
| 133015 | 號碼最近被刪除，仍在刪除中 | 等待 5 分鐘 | 錯誤碼 |
| 133016 | 72 小時內註冊/取消註冊請求超過 10 次 | 停止；等待封鎖結束 | 註冊 |
| 133000 | 先前的取消註冊失敗 | 再次取消註冊，然後再註冊 | 錯誤碼 |
| 「Number already has WhatsApp」 | 號碼仍用於手機應用程式或其他帳號 | 先刪除該 WhatsApp 帳號 | 電話號碼 |
| 範本出現 131042 | 未設定付款方式、信用額度、時區或幣別，帳號被暫停 | 在 WhatsApp Manager 中修正帳單；向使用者顯示 Meta 的 error_data.details 文字，而非猜測 | 錯誤碼 |
| 僅對少數收件者出現 131042 | 根據 Meta 文字為帳號層級，但在一次現場檢查中，16 個範本中有 18 個成功送達 | 在認定為帳號層級或暫停任何操作之前，先計算同一時段內成功與失敗的數量 | [field] 經驗法則 |
| 131049 | 未送達以「維持健康的生態系統互動」 | 至少等待 24 小時再重新發送 | 錯誤碼 |
| 131026 | 收件者無法接收（沒有 WhatsApp、版本過舊、違反條款） | 透過其他方式聯繫 | 錯誤碼 |
| 131031 | WABA 因違反政策而受到限制 | 請參閱政策執行與健康狀態 API | 錯誤碼 |
| 無法將號碼連結至 Facebook 粉絲專頁以使用點擊 WhatsApp 廣告 | 顯示名稱仍在審核中（可能性很大） | 等待審核通過，然後前往粉絲專頁 → 連結的帳號 → WhatsApp | [unconfirmed] |
其他官方頁面：開始使用 · 訊息限制 · Webhook 覆寫。
未經確認（若出現請說明）
- 「No se pudo asignar el socio」的真正原因。
- 一個全新的、未經驗證的商務管理組合是否能夠建立 WABA。
- 在 WABA 之間移動號碼：Meta 的指南指出，對於新帳號模式的帳號，此功能不受支援；在實務上也從未成功完成。
- 顯示名稱審核的官方時間。兩個官方網址在 2026 年 11 月回傳 404。
誰做什麼
代理會執行所有它能做到的螢幕操作與 API 檢查。人類只提供機器無法提供的東西：來自手機的 SMS/語音驗證碼、PIN 碼、貼上密碼、身分驗證、付款。