Privy enables users to login with SMS or WhatsApp. Configure your app following this guide and make sure to read our recipe on enabling SMS or WhatsApp.
Developers can enable either SMS or WhatsApp, but cannot utilize both. Once your account is enabled for SMS with your chosen provider, it cannot be switched.

​
Configuring your application

Through your app’s Privy configuration, you can set the default country code for phone numbers. This is useful if your application primarily serves users from a specific country. The default country can be set in your PrivyProvider, like so:
<PrivyProvider
  appId="your-privy-app-id"
  config={{
    intl: {
      defaultCountry: "US",
    },
    ...insertTheRestOfYourPrivyProviderConfig
  }}
>
  {children}
</PrivyProvider>
To authenticate your users with a one-time passcode (OTP) sent to their phone number via either SMS or WhatsApp, use the useLoginWithSms hook.
To authenticate your users with Privy’s out of the box UIs, check out UI components here.

​
Send Code

sendCode: ({phoneNumber: string, disableSignup?: boolean}) => Promise<void>

​
Parameters

​
phoneNumber
string
required
The phone number of the user to log in. Must follow specific formatting conventions (see below).
​
disableSignup
boolean
Whether to disable the ability to sign up with the phone number.

​
Returns

​
void
Promise<void>
A promise that resolves when the code is sent.

​
Formatting the phone number

The sendCode method requires a phoneNumber string param that must follow these formatting conventions:
  • By default, the implicit phone number country code is +1/US.
  • Explicitly prepending a (+)1 to the phone number will still be read as a US phone number.
  • For non-US phone numbers, append a +${countryCode} to the beginning of the input value.
  • Non-numerical values in the string are ignored, except for a leading + that denotes a custom country code.

​
Login with Code

loginWithCode: ({ code: string }) => Promise<void>;

​
Parameters

​
code
string
required
The one-time passcode sent to the user’s phone number.

​
Returns

​
void
Promise<void>
A promise that resolves when the user is logged in.

​
Usage

import { useState } from "react";
import { useLoginWithSms } from "@privy-io/react-auth";

export default function LoginWithSms() {
  const [phoneNumber, setPhoneNumber] = useState("");
  const [code, setCode] = useState("");
  const { state, sendCode, loginWithCode } = useLoginWithSms();

  return (
    <div>
      {/* Prompt your user to enter their phone number */}
      <input onChange={(e) => setPhoneNumber(e.currentTarget.value)} value={phoneNumber} />
      {/* Once a phone number has been entered, send the OTP to it on click */}
      <button onClick={() => sendCode({ phoneNumber })}>Send Code</button>

      {/* Prompt your user to enter the OTP */}
      <input onChange={(e) => setCode(e.currentTarget.value)} value={code} />
      {/* Once an OTP has been entered, submit it to Privy on click */}
      <button onClick={() => loginWithCode({ code })}>Log in</button>
    </div>
  );
}

​
Tracking Flow State

Track the state of the OTP flow via the state variable returned by the useLoginWithSms hook.
type OtpFlowState =
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'sending-code'}
  | {status: 'awaiting-code-input'}
  | {status: 'submitting-code'}
  | {status: 'done'};
​
status
'initial' | 'error' | 'sending-code' | 'awaiting-code-input' | 'submitting-code' | 'done'
The current state of the OTP flow.
​
error
Error | null
The error that occurred during the OTP flow.

​
Callbacks

You can optionally pass callbacks into the useLoginWithSms hook to run custom logic after a successful login or to handle errors that occur during the flow.

​
onComplete

onComplete?: ((params: {
    user: User;
    isNewUser: boolean;
    wasAlreadyAuthenticated: boolean;
    loginMethod: LoginMethod | null;
    loginAccount: LinkedAccountWithMetadata | null;
}) => void) | undefined

​
Parameters

​
user
User
The user object corresponding to the authenticated user.
​
isNewUser
boolean
Whether the user is a new user or an existing user.
​
wasAlreadyAuthenticated
boolean
Whether the user entered the application already authenticated.
​
loginMethod
LoginMethod | null
The method used by the user to login.
​
loginAccount
LinkedAccountWithMetadata | null
The account corresponding to the loginMethod used.

​
onError

onError: (error: Error) => void

​
Parameters

​
error
Error
The error that occurred during the login flow.

​
Resources

React starter repo

Get started with React and Privy.

Next.js starter repo

Get started with Next.js and Privy.

Whitelabel starter repo

Get started with a whitelabel Privy integration.