SMS - Privy docs

Privy enables users to login to your application with SMS or email. With Privy, your application can verify ownership of a user’s email address or phone number to send them notifications, campaigns, and more to keep them activated.

To authenticate your users with a one-time passcode (OTP) sent to their phone number, use the useLoginWithSms hook.

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).

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.

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

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.

The method used by the user to login.

The account corresponding to the loginMethod used.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the login flow.

To authenticate your users with a one-time passcode (OTP) sent to their phone number, use the useLoginWithSms hook.

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).

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.

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

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.

The method used by the user to login.

The account corresponding to the loginMethod used.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the login flow.

To authenticate your users with a one-time passcode (OTP) sent to their phone number, use the useLoginWithSMS hook.

Send Code

sendCode: ({phone: string}) => Promise<{success: boolean}>

Parameters

phone

string

required

The phone number of the user to log in.

Returns

success

boolean

A promise that resolves to an object with a success property indicating if the code was sent successfully.

loginWithCode: ({ code: string, phone?: string, disableSignup?: boolean }) => Promise<{user: PrivyUser; isNewUser: boolean}>

Parameters

code

string

required

The one-time passcode sent to the user’s phone number.

phone

string

The user’s phone number. Though this parameter is optional, it is highly recommended that you pass the user’s phone number explicitly.

Whether to disable the ability to sign up with the phone number.

Returns

user

PrivyUser

The user object returned by the login process.

Usage

import { useState } from 'react';
import { useLoginWithSMS } from '@privy-io/expo';

export function LoginScreen() {
  const [phone, setPhone] = useState('');
  const [code, setCode] = useState('');
  const { sendCode, loginWithCode } = useLoginWithSMS();

  return (
    <View style={styles.container}>
      <Text>Login</Text>
      <TextInput value={phone} onChangeText={setPhone} placeholder="Phone" inputMode="tel" />
      <Button onPress={() => sendCode({ phone })}>Send Code</Button>

      <TextInput value={code} onChangeText={setCode} placeholder="Code" inputMode="numeric" />
      <Button onPress={() => loginWithCode({ code, phone })}>Login</Button>
    </View>
  );
}

The state variable returned from useLoginWithSMS will always be one of the following values.

type OtpFlowState =
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'sending-code'}
  | {status: 'awaiting-code-input'}
  | {status: 'submitting-code'}
  | {status: 'done'};

status

The current state of the SMS login flow.

error

Error | null

The error that occurred during the SMS login flow.

Callbacks

You can optionally pass callbacks into the useLoginWithSMS hook to run custom logic after an OTP has been sent, after a successful login, or to handle errors that occur during the flow.

`onSendCodeSuccess`

onSendCodeSuccess?: ((phone: string) => void) | undefined

Parameters

phone

string

The phone number the code was sent to.

`onLoginSuccess`

onLoginSuccess?: ((user: User, isNewUser: boolean) => void) | undefined

Parameters

user

User

The PrivyUser returned by loginWithCode.

isNewUser

boolean

Whether the user is a new user or an existing user.

`onError`

onError?: (error: Error) => void

Parameters

error

Error

The error that occurred during the login flow.

To authenticate a user via their phone number, use the Privy client’s sms handler.

Send Code

sendCode(to phoneNumber: String) async throws

Parameters

String

required

The phone number of the user to log in. Must be in E.164 format (e.g., “+14155552671”).

Returns

Nothing, indicating success.

Throws

An error if sending the code fails.

loginWithCode(_ code: String, sentTo phoneNumber: String) async throws -> PrivyUser

Parameters

code

String

required

The one-time passcode sent to the user’s phone number.

sentTo

String

required

The user’s phone number.

Returns

PrivyUser

The authenticated Privy user

Throws

An error if logging the user in is unsuccessful.

Usage

// Send code to user's phone
do {
    try await privy.sms.sendCode(to: "+14155552671")
    // successfully sent code to users phone
} catch {
    print("error sending code: \(error)")
}

// Log the user in
do {
    let user = try await privy.sms.loginWithCode("123456", sentTo: "+14155552671")
    // user successfully logged in
} catch {
    print("error logging user in: \(error)")
}

To authenticate a user via their phone number, use the Privy client’s sms handler.

Send Code

sendCode(phoneNumber: String): Result<Unit>

Parameters

phoneNumber

String

required

The phone number of the user to log in. Must be in E.164 format (e.g., “+14155552671”).

Returns

Result<Unit>

A Result object that indicates whether the operation was successful. Returns Result.success if the code was sent successfully, or Result.failure if there was an error.

loginWithCode(code: String, phoneNumber: String?): Result<PrivyUser>

Parameters

code

String

required

The one-time passcode sent to the user’s phone number.

phoneNumber

String

(Optional) The user’s phone number. Though this parameter is optional, it is highly recommended that you pass the user’s phone number explicitly. If phone number is omitted, the phone number from sendCode will be used.

Returns

Result<PrivyUser>

A Result object containing the PrivyUser if successful, or an error if the operation failed.

Usage

// Send code to user's phone number
val result: Result<Unit> = privy.sms.sendCode(phoneNumber = "+14155552671")

result.fold(
  onSuccess = {
    // OTP was successfully sent
  },
  onFailure = {
    println("Error sending OTP: ${it.message}")
  }
)

// Authenticate with the OTP code
val result: Result<PrivyUser> = privy.sms.loginWithCode(code = "123456", phoneNumber = "+14155552671")

result.fold(
  onSuccess = { user ->
    // User logged in
  },
  onFailure = {
    println("Error logging in user: ${it.message}")
  }
)

To authenticate a user via their phone number, use the Privy client’s sms handler.

Send Code

sendCode(String phoneNumber): Future<Result<void>>

Parameters

phoneNumber

String

required

The phone number of the user to log in. Must be in E.164 format (e.g., “+14155552671”).

Returns

Result<void>

Future<Result<void>>

A Result object that indicates whether the operation was successful. Returns Result.success if the code was sent successfully, or Result.failure if there was an error.

loginWithCode({required String code, String? phoneNumber}): Future<Result<PrivyUser>>

Parameters

code

String

required

The one-time passcode sent to the user’s phone number.

phoneNumber

String

Returns

Result<PrivyUser>

Future<Result<PrivyUser>>

A Result object containing the PrivyUser if successful, or an error if the operation failed.

Usage

// Send code to user's phone number
final Result<void> result = await privy.sms.sendCode("+14155552671");

result.fold(
  onSuccess: (_) {
    // OTP was sent successfully
  },
  onFailure: (error) {
    // Handle error sending OTP
    print(error.message);
  },
);

// Authenticate with the OTP code
final Result<PrivyUser> result = await privy.sms.loginWithCode(
  code: code,
  phoneNumber: phoneNumber,
);

result.fold(
  onSuccess: (user) {
    // User authenticated successfully
  },
  onFailure: (error) {
    // Handle authentication error
  },
);

User authentication

​Send Code

​Parameters

​Returns

​Formatting the phone number

​Login with Code

​Parameters

​Returns

​Usage

​Tracking Flow State

​Callbacks

​onComplete

​Parameters

​onError

​Parameters

​Send Code

​Parameters

​Returns

​Formatting the phone number

​Login with Code

​Parameters

​Returns

​Usage

​Tracking Flow State

​Callbacks

​onComplete

​Parameters

​onError

​Parameters

​Send Code

​Parameters

​Returns

​Login with Code

​Parameters

​Returns

​Usage

​Tracking login flow state

​Callbacks

​onSendCodeSuccess

​Parameters

​onLoginSuccess

​Parameters

​onError

​Parameters

​Send Code

​Parameters

​Returns

​Throws

​Login with Code

​Parameters

​Returns

​Throws

​Usage

​Send Code

​Parameters

​Returns

​Login with Code

​Parameters

​Returns

​Usage

​Send Code

​Parameters

​Returns

​Login with Code

​Parameters

​Returns

​Usage

Send Code

Parameters

Returns

Formatting the phone number

Login with Code

Parameters

Returns

Usage

Tracking Flow State

Callbacks

`onComplete`

Parameters

`onError`

Parameters

Send Code

Parameters

Returns

Formatting the phone number

Login with Code

Parameters

Returns

Usage

Tracking Flow State

Callbacks

`onComplete`

Parameters

`onError`

Parameters

Send Code

Parameters

Returns

Login with Code

Parameters

Returns

Usage

Tracking login flow state

Callbacks

`onSendCodeSuccess`

Parameters

`onLoginSuccess`

Parameters

`onError`

Parameters

Send Code

Parameters

Returns

Throws

Login with Code

Parameters

Returns

Throws

Usage

Send Code

Parameters

Returns

Login with Code

Parameters

Returns

Usage

Send Code

Parameters

Returns

Login with Code

Parameters

Returns

Usage