RootAuth supports passwordless sign-in and sign-up with WhatsApp. After users select WhatsApp sign-in, they enter a phone number and receive an OTP in WhatsApp. Once the code is verified, RootAuth automatically signs them in or creates an account.
This feature uses the WhatsApp Business API (Cloud API) to send verification-code template messages. It does not use the OAuth authorization code flow.
Path: Sign in to the RootAuth Console → open the target application → select Configuration in the top navigation → Application Management - Authentication Configuration → Providers.
1. Before You Start
Before configuring WhatsApp sign-in, prepare the following:
- Create a WhatsApp Business account in Meta for Developers and obtain the Phone Number ID.
- Create an OTP verification-code message template in Meta, have it approved, and obtain the template name.
- Generate a permanent Meta Access Token with the whatsapp_business_messaging permission.
- Obtain the WhatsApp Business Account ID, which is used to retrieve the verification-code templates available to the business account.
2. Enable WhatsApp in the RootAuth Console
Find WhatsApp in the Providers list and select Enable. Initially, the provider displays only the Enable button.
2.1 Configure Credentials
Selecting Enable or Manage opens the WhatsApp configuration dialog. This provider supports only Custom credentials and cannot be switched to another credential mode.
Turn on the switch at the top, then complete the following configuration:
| Setting | Description |
|---|---|
| Access Token | Required. The permanent Meta Access Token. The input supports showing or hiding the value. |
| WhatsApp Business Account ID | Required. Used to retrieve verification-code templates available to this WhatsApp Business account. |
| Phone Number ID | Required. The WhatsApp Business phone number ID, for example 123456789012345. |
| Verification-code template name | Required dropdown. Enter the Access Token and Business Account ID first, then select a template returned by the backend. Only authentication templates whose message body type is BODY can be selected. |
The verification-code template name cannot be selected until you enter the Access Token and Business Account ID. The backend may return multiple templates, but templates that are not authentication templates cannot be selected.
2.2 Calling Codes and Sign-In Mode
WhatsApp sign-in calling codes do not depend on the phone-number sign-in settings in Login Control:
- Hosted integration: Uses the default calling-code list provided by RootAuth.
- API integration: The application builds its own calling-code selector and submits the calling code with the phone number.
The sign-in mode is fixed as Available for sign-in and sign-up and cannot be turned off.
2.3 Account Linking
Account linking is off by default. When enabled, RootAuth automatically uses Automatic linking and does not show a confirmation dialog:
- If the full phone number matches an existing account, RootAuth links the WhatsApp identity and signs the user in to that account.
- If no existing account matches, RootAuth creates a new account and links the WhatsApp phone number.
When account linking is off, WhatsApp phone numbers and standard system phone numbers are managed separately. Even if the numbers are the same, accounts registered through different methods remain independent and are not linked automatically.
2.4 Save and Disable
After all required fields pass validation, select Save. When enabled, the provider card displays the Enabled and Custom credentials labels, and the button changes to Manage.
When the top switch is turned off, the WhatsApp entry no longer appears on end-user sign-in pages. Saved credentials are retained for later reuse. While the switch is off, the configuration form and save action are unavailable.
3. Integration Methods
WhatsApp sign-in supports two integration methods:
| Method | Description |
|---|---|
| Hosted integration | Use RootAuth-hosted sign-in and sign-up pages. When WhatsApp is enabled, the third-party sign-in area displays the WhatsApp entry and includes calling-code selection, phone-number input, code sending, and verification. |
| API integration | Build the frontend form, calling-code selector, and user interaction in your application, then use the RootAuth API to send and verify codes and complete sign-in. |
For detailed integration instructions, see the Developer Integration Guide.
4. How Users Sign In with WhatsApp
After WhatsApp is enabled, the sign-in and sign-up pages display a WhatsApp icon. Users select it, choose a calling code, enter a phone number, and complete code delivery and verification.
4.1 Phone Number Format and Calling-Code List
RootAuth uses the full phone number as the WhatsApp identity, in the format {country_code} {phone_number}, for example +86 13800138000.
RootAuth-hosted pages support the following country and region calling codes:
| Code | Country or region | Code | Country or region | Code | Country or region |
|---|---|---|---|---|---|
| +86 | China mainland | +852 | Hong Kong SAR, China | +853 | Macao SAR, China |
| +886 | Taiwan, China | +81 | Japan | +82 | South Korea |
| +65 | Singapore | +60 | Malaysia | +66 | Thailand |
| +62 | Indonesia | +63 | Philippines | +84 | Vietnam |
| +91 | India | +92 | Pakistan | +880 | Bangladesh |
| +94 | Sri Lanka | +977 | Nepal | +95 | Myanmar |
| +855 | Cambodia | +856 | Laos | +976 | Mongolia |
| +673 | Brunei | +971 | United Arab Emirates | +966 | Saudi Arabia |
| +90 | Turkey | +972 | Israel | +974 | Qatar |
| +965 | Kuwait | +973 | Bahrain | +968 | Oman |
| +962 | Jordan | +961 | Lebanon | +964 | Iraq |
| +98 | Iran | +44 | United Kingdom | +49 | Germany |
| +33 | France | +39 | Italy | +34 | Spain |
| +31 | Netherlands | +32 | Belgium | +41 | Switzerland |
| +43 | Austria | +46 | Sweden | +47 | Norway |
| +45 | Denmark | +358 | Finland | +351 | Portugal |
| +353 | Ireland | +48 | Poland | +420 | Czechia |
| +36 | Hungary | +30 | Greece | +7 | Russia |
| +380 | Ukraine | +40 | Romania | +359 | Bulgaria |
| +385 | Croatia | +421 | Slovakia | +386 | Slovenia |
| +372 | Estonia | +371 | Latvia | +370 | Lithuania |
| +352 | Luxembourg | +354 | Iceland | +375 | Belarus |
| +381 | Serbia | +1 | United States and Canada | +55 | Brazil |
| +52 | Mexico | +54 | Argentina | +56 | Chile |
| +57 | Colombia | +51 | Peru | +58 | Venezuela |
| +593 | Ecuador | +591 | Bolivia | +598 | Uruguay |
| +595 | Paraguay | +61 | Australia | +64 | New Zealand |
| +27 | South Africa | +234 | Nigeria | +20 | Egypt |
| +254 | Kenya | +212 | Morocco | +233 | Ghana |
| +255 | Tanzania | +256 | Uganda | +251 | Ethiopia |
| +213 | Algeria | +216 | Tunisia | +244 | Angola |
| +260 | Zambia | +263 | Zimbabwe |
4.2 Send and Verify the Code
- The user selects a calling code and enters a phone number.
- Before requesting a code, the user must complete human verification.
- RootAuth sends a verification-code template message to the phone number through the WhatsApp Business API.
- The user views the code in the WhatsApp app and enters it on the sign-in page.
- After successful verification, RootAuth automatically completes sign-in or sign-up.
5. Account Linking and Matching
RootAuth uses the full phone number, including calling code, as the unique identifier for the WhatsApp provider, for example +86 13800138000.
- Account linking enabled: When the full phone number matches an existing account, RootAuth signs the user in and links the WhatsApp identity. If it does not match, RootAuth creates a new account and links it.
- Account linking disabled: WhatsApp sign-in and standard phone-number sign-in or sign-up are separate entry points. Even if the phone numbers are the same, they are not automatically linked to the same account.
WhatsApp phone numbers are stored separately as whatsapp_phone, with the calling code and phone number stored independently. This field is separate from the application's standard phone field.
6. Link or Unlink a WhatsApp Account
Applications can use the API to let signed-in users link or unlink WhatsApp:
- Link WhatsApp: A signed-in user submits a phone number and completes WhatsApp OTP verification. RootAuth then links the full phone number to the current account.
- Unlink WhatsApp: When a signed-in user calls the unlink API, RootAuth removes the WhatsApp phone-number link from the current account.
The RootAuth Console does not provide an administrator interface for manually linking or unlinking WhatsApp. Applications should implement user-initiated linking and unlinking through the API.
7. View a User's WhatsApp Authentication Method
After a user signs in, signs up, or links WhatsApp, open the user in User Management and view the WhatsApp record in Authentication methods.
| Field | Description |
|---|---|
| Authentication method | WhatsApp, displayed with the WhatsApp icon. |
| Identifier | Displays the WhatsApp phone number with its calling code. |
| Last used | The most recent time the user signed in with WhatsApp. |
After an application links WhatsApp through the API, this authentication method appears. After it is unlinked, the record is removed from the user details page.
8. Audit Logs
RootAuth records the following WhatsApp events in Audit Logs → User Behavior Logs:
| Event type | Description |
|---|---|
| WhatsApp sign-up | A user creates a new account through WhatsApp OTP. |
| WhatsApp sign-in | A user signs in to an existing account through WhatsApp OTP. |
| Link WhatsApp | A signed-in user links WhatsApp through the application. |
| Unlink WhatsApp | A signed-in user unlinks WhatsApp through the application. |
9. Disable WhatsApp Sign-In
To disable WhatsApp sign-in, open the WhatsApp management dialog and turn off the switch at the top.
After WhatsApp sign-in is disabled:
- The WhatsApp entry no longer appears on sign-in and sign-up pages.
- Saved WhatsApp Business API credentials are retained.
- Existing users' WhatsApp links are not removed.
- You can reuse the original configuration if you enable WhatsApp again later.
;}.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)