RootAuth 支持通过 WhatsApp 完成免密登录和注册。用户选择 WhatsApp 登录后，输入手机号并在 WhatsApp 应用中接收 OTP 验证码；验证通过后，RootAuth 自动完成登录或注册。
本功能使用 WhatsApp Business API（Cloud API）发送验证码模板消息，不采用 OAuth 授权码模式。
路径：登录 RootAuth 控制台 → 进入目标应用 → 点击顶部导航栏的「配置」→「应用管理 - 认证配置」→ 选择「提供方」。
1. 开始前准备
配置 WhatsApp 登录前，请先完成以下准备：
- 已在 Meta 开发者后台创建 WhatsApp Business 账号，并获取 Phone Number ID。
- 已在 Meta 后台创建并通过审批的 OTP 验证码消息模板，并获取验证码模板名称（Template Name）。
- 已生成 Meta 永久访问令牌（Access Token），且令牌具备 whatsapp_business_messaging 权限。
- 已获取 WhatsApp Business 业务账户编号（WhatsApp Business Account ID），用于获取该业务账户下的验证码模板。
2. 在 RootAuth 后台开启 WhatsApp
在「提供方」列表中找到 WhatsApp，点击右侧「启用」。初始状态下，列表仅显示「启用」按钮。
2.1 配置凭证
点击「启用」或「管理」后，会打开 WhatsApp 配置弹窗。该提供方仅支持自定义凭证模式，不能切换为其他凭证模式。
打开顶部开关后，填写以下基础配置：
| 配置项 | 说明 |
|---|---|
| Access Token | Meta 永久访问令牌，必填。输入框支持显示或隐藏内容。 |
| WhatsApp Business 业务账户编号 | WhatsApp Business Account ID，必填。用于读取该业务账户下可用的验证码模板。 |
| Phone Number ID | WhatsApp Business 电话号码编号，必填。例如：123456789012345。 |
| 验证码模板名称 | 必填下拉项。请先填写 Access Token 和业务账户编号，再选择后端返回的模板。仅可选择身份验证类型的模板，且模板正文类型必须为 BODY。 |
验证码模板名称在填写 Access Token 和业务账户编号前不可选择。后端可能返回多个模板，但非身份验证类型的模板不可选择。
2.2 区号与登录模式
WhatsApp 登录的区号不依赖「登录控制」中的手机号登录配置：
- Hosted 接入：使用 RootAuth 提供的默认区号列表。
- API 接入：应用自行开发区号选择器，并将区号与手机号一并提交。
登录模式固定为「可用于登录注册」，不可关闭。
2.3 账号绑定
「账号绑定」默认关闭。打开后，系统自动使用自动关联模式，不会显示确认弹窗：
- 若完整手机号匹配现有账号，自动关联 WhatsApp 身份并登录该账号。
- 若未匹配现有账号，创建新账号并绑定 WhatsApp 手机号。
关闭账号绑定后，WhatsApp 手机号与系统普通手机号分别管理。即使手机号相同，通过不同方式注册的账号也相互独立，不会自动关联。
2.4 保存与关闭
所有必填项校验通过后，点击「保存」。启用成功后，列表卡片显示「已启用」和「自定义凭证」标签，右侧按钮变为「管理」。
关闭顶部开关后，终端登录页不再展示 WhatsApp 入口；已保存的凭证会保留，后续重新开启时可以继续使用。开关关闭时，弹窗内的配置表单和保存操作不可用。
3. 接入方式
WhatsApp 登录支持两种接入方式：
| 接入方式 | 说明 |
|---|---|
| Hosted 接入 | 使用 RootAuth 托管的登录/注册页面。启用 WhatsApp 后，第三方登录区域会展示 WhatsApp 入口，并内置区号选择、手机号输入、验证码发送与校验交互。 |
| API 接入 | 应用自行实现前端表单、区号选择和交互界面，并调用 RootAuth API 完成验证码发送、校验和登录。 |
具体的接入指引，请参考开发集成文档。
4. 用户如何使用 WhatsApp 登录
启用后，登录/注册页会展示 WhatsApp 图标。用户点击图标后，依次选择区号、输入手机号、完成验证码发送和校验。
4.1 手机号格式与区号列表
系统使用完整手机号作为 WhatsApp 身份标识，格式为 {country_code} {phone_number}，例如：+86 13800138000。
RootAuth Hosted 页面支持以下国家/地区区号：
| 区号 | 国家/地区 | 区号 | 国家/地区 | 区号 | 国家/地区 |
|---|---|---|---|---|---|
| +86 | 中国大陆 | +852 | 中国香港 | +853 | 中国澳门 |
| +886 | 中国台湾 | +81 | 日本 | +82 | 韩国 |
| +65 | 新加坡 | +60 | 马来西亚 | +66 | 泰国 |
| +62 | 印度尼西亚 | +63 | 菲律宾 | +84 | 越南 |
| +91 | 印度 | +92 | 巴基斯坦 | +880 | 孟加拉国 |
| +94 | 斯里兰卡 | +977 | 尼泊尔 | +95 | 缅甸 |
| +855 | 柬埔寨 | +856 | 老挝 | +976 | 蒙古 |
| +673 | 文莱 | +971 | 阿联酋 | +966 | 沙特阿拉伯 |
| +90 | 土耳其 | +972 | 以色列 | +974 | 卡塔尔 |
| +965 | 科威特 | +973 | 巴林 | +968 | 阿曼 |
| +962 | 约旦 | +961 | 黎巴嫩 | +964 | 伊拉克 |
| +98 | 伊朗 | +44 | 英国 | +49 | 德国 |
| +33 | 法国 | +39 | 意大利 | +34 | 西班牙 |
| +31 | 荷兰 | +32 | 比利时 | +41 | 瑞士 |
| +43 | 奥地利 | +46 | 瑞典 | +47 | 挪威 |
| +45 | 丹麦 | +358 | 芬兰 | +351 | 葡萄牙 |
| +353 | 爱尔兰 | +48 | 波兰 | +420 | 捷克 |
| +36 | 匈牙利 | +30 | 希腊 | +7 | 俄罗斯 |
| +380 | 乌克兰 | +40 | 罗马尼亚 | +359 | 保加利亚 |
| +385 | 克罗地亚 | +421 | 斯洛伐克 | +386 | 斯洛文尼亚 |
| +372 | 爱沙尼亚 | +371 | 拉脱维亚 | +370 | 立陶宛 |
| +352 | 卢森堡 | +354 | 冰岛 | +375 | 白俄罗斯 |
| +381 | 塞尔维亚 | +1 | 美国、加拿大 | +55 | 巴西 |
| +52 | 墨西哥 | +54 | 阿根廷 | +56 | 智利 |
| +57 | 哥伦比亚 | +51 | 秘鲁 | +58 | 委内瑞拉 |
| +593 | 厄瓜多尔 | +591 | 玻利维亚 | +598 | 乌拉圭 |
| +595 | 巴拉圭 | +61 | 澳大利亚 | +64 | 新西兰 |
| +27 | 南非 | +234 | 尼日利亚 | +20 | 埃及 |
| +254 | 肯尼亚 | +212 | 摩洛哥 | +233 | 加纳 |
| +255 | 坦桑尼亚 | +256 | 乌干达 | +251 | 埃塞俄比亚 |
| +213 | 阿尔及利亚 | +216 | 突尼斯 | +244 | 安哥拉 |
| +260 | 赞比亚 | +263 | 津巴布韦 |
4.2 发送和校验验证码
- 用户选择区号并输入手机号。
- 点击「获取验证码」前，需要先通过人机验证。
- RootAuth 通过 WhatsApp Business API 向该手机号发送验证码模板消息。
- 用户在 WhatsApp 客户端查看验证码并回填。
- 验证码校验通过后，RootAuth 自动完成登录或注册。
5. 账号绑定与关联逻辑
RootAuth 使用完整手机号（区号加号码）作为 WhatsApp 提供方下的唯一标识，例如 +86 13800138000。
- 开启账号绑定：完整手机号匹配已有账号时，自动登录并绑定 WhatsApp 身份；未匹配时，创建新账号并绑定。
- 关闭账号绑定：WhatsApp 登录和普通手机号注册/登录被视为独立入口，即使手机号相同也不会自动关联为同一账号。
WhatsApp 手机号会独立存储为 whatsapp_phone，并分别记录区号和号码；该字段与应用普通手机号字段 phone 相互独立。
6. 绑定与解绑 WhatsApp 账号
应用可以通过 API 让已登录用户主动绑定或解绑 WhatsApp：
- 绑定 WhatsApp：已登录用户提交手机号并完成 WhatsApp OTP 验证后，RootAuth 将完整手机号绑定到当前账号。
- 解绑 WhatsApp：已登录用户调用解绑接口后，RootAuth 清除当前账号的 WhatsApp 手机号绑定记录。
RootAuth 控制台不提供管理员手动绑定或解绑 WhatsApp 的操作入口。应用应通过 API 实现用户主动绑定和解绑。
7. 查看用户的 WhatsApp 认证方式
用户通过 WhatsApp 登录、注册或绑定 WhatsApp 后，可在「用户管理」中打开对应用户详情，在「认证方式」区域查看 WhatsApp 记录。
| 字段 | 说明 |
|---|---|
| 认证方式 | WhatsApp，并显示 WhatsApp 图标。 |
| 标识 | 显示 WhatsApp 手机号，区号与号码拼接展示。 |
| 最后使用时间 | 最近一次使用 WhatsApp 登录的时间。 |
应用通过 API 绑定 WhatsApp 后，该认证方式会出现；解绑后，该条目会从用户详情中移除。
8. 审计日志
RootAuth 会在「审计日志」→「用户行为日志」中记录以下 WhatsApp 相关事件：
| 事件类型 | 说明 |
|---|---|
| WhatsApp 注册 | 用户通过 WhatsApp OTP 创建新账号。 |
| WhatsApp 登录 | 用户通过 WhatsApp OTP 登录已有账号。 |
| 绑定 WhatsApp | 已登录用户通过应用完成 WhatsApp 绑定。 |
| 解绑 WhatsApp | 已登录用户通过应用完成 WhatsApp 解绑。 |
9. 关闭 WhatsApp 登录
如需关闭 WhatsApp 登录，进入 WhatsApp 管理弹窗，关闭顶部开关。
关闭后：
- 登录/注册页不再展示 WhatsApp 入口。
- 已保存的 WhatsApp Business API 凭证会保留。
- 已有用户的 WhatsApp 绑定记录不会被删除。
- 后续重新开启时，可以继续使用原有配置。
;}.cls-2{fill:%230868f7;}.cls-3{fill:url(%23未命名的渐变_44);}.cls-4{fill:%23333;}%3c/style%3e%3clinearGradient%20id='未命名的渐变_8'%20x1='33.73'%20y1='100.61'%20x2='-0.03'%20y2='-1.06'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%237ae9fb'/%3e%3cstop%20offset='0.67'%20stop-color='%232b90f8'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3clinearGradient%20id='未命名的渐变_44'%20x1='27.86'%20y1='18.67'%20x2='68.36'%20y2='22.22'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%235ac7f2'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3c/defs%3e%3cpath%20class='cls-1'%20d='M29,28.74V81.91l-9.51-3.68v0L8.52,74A7.17,7.17,0,0,1,4,67.32V24.54A3.76,3.76,0,0,1,9.08,21Z'/%3e%3cpath%20class='cls-2'%20d='M68.09,78.07a13.15,13.15,0,0,1-17.9,12.06L29,81.91h0V28.74L50.19,37A13.17,13.17,0,0,0,68.08,25.3h0Z'/%3e%3cpath%20class='cls-3'%20d='M68.08,25.3a13.19,13.19,0,0,1-6.73,10.87A13.09,13.09,0,0,1,50.19,37L29,28.74V6A3.76,3.76,0,0,1,34.1,2.52l25.59,9.91A13.22,13.22,0,0,1,68.08,25.3Z'/%3e%3cpath%20class='cls-4'%20d='M129.06,81.76a4.33,4.33,0,0,1-3.19-1.31,4.4,4.4,0,0,1-1.31-3.24V56.86H97.65V77.21a4.36,4.36,0,0,1-1.35,3.2A4.68,4.68,0,0,1,93,81.76a4.32,4.32,0,0,1-3.19-1.31,4.37,4.37,0,0,1-1.32-3.24V27.27A4.58,4.58,0,0,1,89.83,24a4.59,4.59,0,0,1,7.82,3.27V48.15h26.91V27.27A4.58,4.58,0,0,1,125.91,24a4.59,4.59,0,0,1,7.82,3.27V77.21a4.37,4.37,0,0,1-1.36,3.2A4.65,4.65,0,0,1,129.06,81.76Z'/%3e%3cpath%20class='cls-4'%20d='M163.77,81.66c-6.57,0-11.76-1.92-15.44-5.7s-5.54-9.07-5.54-15.74a26.76,26.76,0,0,1,2.09-10.43,17.72,17.72,0,0,1,6.67-8.06,19.15,19.15,0,0,1,10.68-2.95,19,19,0,0,1,10.46,2.8,18.7,18.7,0,0,1,6.55,7.36,22.53,22.53,0,0,1,2.36,10.28A4.51,4.51,0,0,1,177,63.77H152.23a10.8,10.8,0,0,0,3.49,6.65c2,1.68,4.88,2.52,8.66,2.52a22.25,22.25,0,0,0,7.54-1.21c.74-.3,1.55-.67,2.37-1.07a3.75,3.75,0,0,1,1.84-.4,4.09,4.09,0,0,1,3,1.15,4,4,0,0,1,1.12,3,4.38,4.38,0,0,1-2.58,3.82,32.34,32.34,0,0,1-6.36,2.61A28.67,28.67,0,0,1,163.77,81.66ZM172.4,55.9a9.72,9.72,0,0,0-1.63-4.56A9.9,9.9,0,0,0,167,48a10.38,10.38,0,0,0-4.64-1.14,12,12,0,0,0-4.77,1.06,9.54,9.54,0,0,0-4.89,5.66,11.78,11.78,0,0,0-.51,2.3Z'/%3e%3cpath%20class='cls-4'%20d='M193,81.64a4.49,4.49,0,0,1-4.51-4.55V27.28A4.58,4.58,0,0,1,189.84,24a4.48,4.48,0,0,1,3.28-1.36A4.36,4.36,0,0,1,196.35,24a4.46,4.46,0,0,1,1.31,3.31V77.09a4.34,4.34,0,0,1-1.35,3.2A4.67,4.67,0,0,1,193,81.64Z'/%3e%3cpath%20class='cls-4'%20d='M263.79,81.71a5.7,5.7,0,0,1-4.2-1.74,5.76,5.76,0,0,1-1.73-4.19V27.37a4.58,4.58,0,0,1,1.35-3.27A4.59,4.59,0,0,1,267,27.37V72.53h24a4.58,4.58,0,0,1,3.27,7.82A4.66,4.66,0,0,1,291,81.71Z'/%3e%3cpath%20class='cls-4'%20d='M424.48,81.74a4.71,4.71,0,0,1-2.71-.88,5.43,5.43,0,0,1-1-1l-.07-.09-12.41-17-5.41,5v9.44a4.31,4.31,0,0,1-1.36,3.19,4.66,4.66,0,0,1-3.3,1.36A4.29,4.29,0,0,1,395,80.42a4.36,4.36,0,0,1-1.32-3.23V27.37A4.58,4.58,0,0,1,395,24.1a4.52,4.52,0,0,1,6.58.12,4.54,4.54,0,0,1,1.24,3.15V56.31l17.72-16.38.05,0a4.8,4.8,0,0,1,2.94-1.11,4.4,4.4,0,0,1,3.27,1.2,4.57,4.57,0,0,1,1.2,3.27,4.44,4.44,0,0,1-.77,2.33,7.45,7.45,0,0,1-1.43,1.65l-11,9.64,13.34,17.68a5,5,0,0,1,1,2.71,4.12,4.12,0,0,1-1.36,3.24A4.64,4.64,0,0,1,424.48,81.74Z'/%3e%3cpath%20class='cls-4'%20d='M317.93,81.76a21.5,21.5,0,1,1,21.17-21.5A21.37,21.37,0,0,1,317.93,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,317.93,47.66Z'/%3e%3cpath%20class='cls-4'%20d='M212.18,101.22a4.12,4.12,0,0,1-3.05-1.26,4.17,4.17,0,0,1-1.26-3.1V43.34a4.37,4.37,0,0,1,1.3-3.14,4.26,4.26,0,0,1,3.13-1.3,4.19,4.19,0,0,1,3.1,1.26,4.32,4.32,0,0,1,1.26,3.16,20.77,20.77,0,0,1,13-4.54,21.51,21.51,0,0,1,0,43,20.51,20.51,0,0,1-13-4.57V96.86a4.15,4.15,0,0,1-1.3,3.06A4.5,4.5,0,0,1,212.18,101.22Zm17.43-53.63c-6.23,0-12.93,4.11-12.93,12.72a12.73,12.73,0,0,0,25.46,0A12.71,12.71,0,0,0,229.61,47.59Z'/%3e%3cpath%20class='cls-4'%20d='M365.76,81.76a21.5,21.5,0,1,1,21.18-21.5A21.37,21.37,0,0,1,365.76,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,365.76,47.66Z'/%3e%3c/svg%3e)