在 WhatsApp 發送驗證碼(OTP)
如要在 WhatsApp 發送驗證碼(OTP),商家須建立一個驗證訊息範本。這是 Meta 的固定格式「<code> is your verification code.」,附有複製代碼或一鍵按鈕。商家的後端再透過 Cloud API 發送,並將驗證碼同時填入內文與按鈕兩處。驗證碼最多可達 15 個字符,而可選的到期提示可設為 1 至 90 分鐘。
easyCoexistence 透過 Coexistence 將您的 WhatsApp Business 號碼連接至 Meta 的 Cloud API,並為您的後端提供發送驗證訊息範本所需的一切:Send 端點、存取權杖,以及透過您的 AI 使用的 create_template 與 get_template_status。
驗證訊息範本接受的最長參數;其內容或參數均不得包含 URL、媒體或表情符號。
code_expiration_minutes 的範圍,會在訊息中加入「This code expires in N minutes.」一行。
驗證訊息範本的預設存活時間(TTL);可設為 30 秒至 15 分鐘。
將驗證訊息範本發送至商業範圍用戶 ID 而非電話號碼時所回傳的錯誤。
驗證訊息只會送達用戶的主要 WhatsApp 裝置;已連結的裝置則只會看到提示。
Coexistence 號碼的固定吞吐量,即短時間內大量登入驗證碼的上限。
什麼是 WhatsApp 驗證訊息範本?
這是 Meta 唯一允許用於一次性密碼及驗證碼的格式:若應用程式透過 WhatsApp 提供驗證碼,就必須使用此範本;實用訊息範本或行銷訊息範本均不得載有密碼。內文為固定格式「<code> is your verification code.」,另可加上兩行可選文字:「For your security, do not share this code.」及「This code expires in <N> minutes.」由您選擇的是按鈕。WhatsApp 會停用此類訊息的轉寄功能;在 iOS 26 及更新版本上,驗證碼亦會作為鍵盤建議顯示,您無需另行設定。
如何建立驗證訊息範本?
您可在 WhatsApp Manager 的 Template Library 中選取,或透過 API 提交;您的 AI 可使用 create_template 並將類別設為 AUTHENTICATION 完成。您無須提供內文:Meta 會按您的設定,以所選語言生成內文,並在建立時將 OTP 按鈕轉為 URL 按鈕。每種語言各需一個範本。連接器的 create_template 不會傳遞 message_send_ttl_seconds,因此除非您透過 Meta 的 API 另行更改,否則將套用 10 分鐘的預設存活時間。
{
"connection_id": "<from list_numbers>",
"name": "login_code",
"language": "en_US",
"category": "AUTHENTICATION",
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{ "type": "BUTTONS", "buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
]}
]
}您的後端如何發送驗證碼?
每個驗證碼都向號碼的 /messages 端點發送一次請求,所用的存取權杖來自 get_api_credentials,或來自控制台中的「Plug in your own system」卡片。同一驗證碼需同時填入內文參數,以及索引值為 0 的 URL 按鈕參數,而收件人必須是電話號碼。發送前,後端會生成驗證碼,並儲存其雜湊值、到期時間及嘗試次數計數器;之後再將用戶輸入的內容與該雜湊值比對。
POST https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/messages
Authorization: Bearer <ACCESS_TOKEN>
{
"messaging_product": "whatsapp",
"to": "5511987654321",
"type": "template",
"template": {
"name": "login_code",
"language": { "code": "en_US" },
"components": [
{ "type": "body",
"parameters": [{ "type": "text", "text": "482913" }] },
{ "type": "button", "sub_type": "url", "index": "0",
"parameters": [{ "type": "text", "text": "482913" }] }
]
}
}為何驗證碼由後端產生,而非由自動化處理?
因為負責登入的系統必須生成、記住並核對驗證碼,只有該系統知道何時需要驗證碼。自動化回應的是客戶發來的訊息,而登入畫面從不會向您的號碼寫入訊息。範本本身亦排除了自動化:OTP 按鈕以按鈕變數承載驗證碼,而「Send a template」步驟只會填入內文變數,因此無法發送驗證訊息範本。您的 AI 可透過 send_template 發送,此方法會將按鈕元件傳送至 Meta,但那只供測試之用,並不適用於登入流程。
什麼令 WhatsApp OTP 流程更安全?
Meta 的最佳做法與格式的限制指向同一份清單。以下各項均無需後端及 Cloud API 以外的任何東西:
- 在發送首個驗證碼前,與用戶確認 WhatsApp 號碼,並說明驗證碼將透過 WhatsApp 送達。
- 將存活時間設為不超過驗證碼的到期時間,避免延遲送達時顯示已失效的驗證碼。
- 限制每個號碼的嘗試次數及重新發送次數,並於首次使用後令驗證碼失效。
- 不要將 WhatsApp 驗證碼作為帳戶復原的唯一驗證因素:已重新分配的電話號碼仍可連上舊的 WhatsApp 帳戶。
- 監察狀態 Webhook;若驗證碼未能送達,則改用 SMS 或電郵。
若號碼同時在 WhatsApp Business 應用程式中運作,情況有何不同?
發送方式與任何 Cloud API 號碼相同,每秒最多 20 則訊息。Meta 會將透過 API 發送的訊息同步至應用程式的聊天中,因此在 Coexistence 號碼上,您發送的驗證碼亦會出現在商業手機的這些聊天中;請將該手機交由可信任的人保管,或改用另一個號碼發送驗證碼。Meta 的最佳做法亦要求每間商家使用自己的號碼發送驗證訊息範本,不得與其他商家共用。驗證屬付費範本類別,按收件人所在國家以每則已送達訊息收費;部分市場另設有 authentication-international 費率。easyCoexistence 不作任何加價。
設定方法
- Connect the numberConnect your WhatsApp Business number to easyCoexistence through Meta's Coexistence flow, or use a separate number reserved for codes.
- Create the authentication templateAsk your AI to submit login_code with create_template, category AUTHENTICATION, a copy-code button and an expiry, then check get_template_status for APPROVED.
- Store the credentials on your serverCall get_api_credentials or open "Plug in your own system" in the dashboard, and put the Send endpoint and access token in your backend's secrets.
- Build generate, send and verifyGenerate the code, store its hash with an expiry, send the template with the code in the body and button, then check the user's entry against the hash.
- Handle failuresRead failed statuses from the number's webhook, then offer SMS or email and show the user which number the code went to.
常見錯誤
- 將驗證碼寫入實用訊息範本,例如「Your code is {{1}}」。Meta 只允許在驗證訊息範本中使用密碼;若發現實用或行銷範本載有密碼,便會拒絕。
- 只在內文中發送驗證碼。複製代碼按鈕需要與其參數相同的值;Meta 要求請求中同時包含兩次驗證碼。
- 為舊的驗證訊息範本保留 30 天的存活時間。手機離線一小時後收到的將是已過期的驗證碼;請將其設為不超過驗證碼的到期時間。
- 將驗證碼發送至商業範圍用戶 ID。驗證訊息範本只會發送至電話號碼,Meta 會回傳錯誤 131062。
號碼全天候 24 小時受監察,若有任何會中斷登入驗證碼的連線問題,我們會以電郵通知您。每個號碼每月 US$ 9 起,最低降至 US$ 0.75,號碼越多越便宜,並提供首 3 天免費試用。
常見問題
WhatsApp OTP 是否比 SMS 驗證碼便宜?
費用因國家而異:Meta 按收件人所在國家的費率,為每則已送達的驗證訊息收費,部分市場另有特別費率;而 SMS 價格則因電訊商及路由而異。轉換前,請比較 Meta 的費率表與您的 SMS 供應商在主要國家的收費。
這與 WhatsApp 的兩步驗證 PIN 相同嗎?
不相同。兩步驗證是保護商家自身 WhatsApp 號碼的六位數 PIN。驗證訊息範本則是向您的客戶發送驗證碼,讓您的應用程式或網站確認對方的身分。
用戶是否需要同意才會收到驗證碼?
需要。Meta 的政策規定,商家須先獲得許可才可向他人發送訊息;其 OTP 指引建議提供多種渠道供選擇,例如 WhatsApp、SMS 或電郵。在登入畫面上、號碼旁選擇 WhatsApp,即構成該許可。
代理商可否以同一號碼為多個客戶發送驗證碼?
不可以。Meta 的最佳做法要求每間商家為驗證訊息範本擁有自己的 WhatsApp Business 帳戶及電話號碼;與其他商家共用一個號碼違反 Meta 的條款及政策。請為每位客戶各自連接一個號碼。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期