# Phone

## Installation

In addition to following the overall instructions, pay attention to the following in the `settings.py` of your project:

    # Make sure that the login methods includes "phone" as a method.
    ACCOUNT_LOGIN_METHODS = {"phone", "email"}

    # Add a required phone field to the signup fields.
    # ACCOUNT_SIGNUP_FIELDS = [
      'phone*',
      'email*'  # Can be left out if you want to only use 'phone'.
    ]

    # You will need to provide methods for storing phone numbers, and
    # sending SMS messages in a custom adapter.
    ACCOUNT_ADAPTER = 'project.users.adapter.MyAccountAdapter'

# Configuration

Available settings:

`ACCOUNT_PHONE_VERIFICATION_ENABLED` (default: `True`)

  Whether or not mandatory verification of phone numbers during login/signup takes place.

`ACCOUNT_PHONE_VERIFICATION_MAX_ATTEMPTS` (default: `3`)

  This setting controls the maximum number of attempts the user has at inputting a valid code.

`ACCOUNT_PHONE_VERIFICATION_TIMEOUT` (default: `900`)

  The code that is sent has a limited life span. It expires this many seconds after which it was sent.

`ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE` (default: `False`)

  Whether or not the phone number can be changed after signup at the phone number verification stage.

  Warning: the warning related to enumeration prevent over at

    `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE` holds here as well.

`ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND` (default: `False`)

  Whether or not the user can request a new phone number verification code.

`ACCOUNT_PHONE_VERIFICATION_CODE_FORMAT` (default: `settings.ALLAUTH_USER_CODE_FORMAT`)

  Controls the format of the verification code.

## Form Fields

For presenting a phone number form field to the user a basic `<input type="tel">` field is used that requires input in E164 format. There are various external projects that offer more elaborate phone number input fields. You can switch over to using the fields provided by those projects, or, tweak the phone number validaton logic, by overriding the following adapter methods:

class allauth.account.adapter.DefaultAccountAdapter(request=None)

  The adapter class allows you to override various functionality of the `allauth.account` app. To do so, point `settings.ACCOUNT_ADAPTER` to your own class that derives from `DefaultAccountAdapter` and override the behavior by altering the implementation of the methods according to your own needs.

  phone_form_field(**kwargs)

    Returns a form field used to input phone numbers.

  clean_phone(phone: str) → str

    Validates a phone number. You can hook into this if you want to (dynamically) restrict what phone numbers can be chosen.

## Database Models

Out of the box, there are no models provided intended to store the phone numbers of users. It is up to the developer to decide where phone numbers are to be stored, for example, on a custom user model, or, on a separate Phone model of its own. Once those the models are setup, the following adapter methods need to be populated so that the models will be used:

> class allauth.account.adapter.DefaultAccountAdapter(request=None)

>   The adapter class allows you to override various functionality of the `allauth.account` app. To do so, point `settings.ACCOUNT_ADAPTER` to your own class that derives from `DefaultAccountAdapter` and override the behavior by altering the implementation of the methods according to your own needs.

>   get_phone(user) → tuple[str, bool] | None

>     Returns the phone number stored for the given user. A tuple of the phone number itself, and whether or not the phone number was verified is returned.

>   set_phone(user, phone: str, verified: bool)

>     Sets the phone number (and verified status) for the given user.

>   set_phone_verified(user, phone: str)

>     Marks the specified phone number for the given user as verified. Note that the user is already expected to have the phone number attached to the account.

>   get_user_by_phone(phone: str)

>     Looks up a user given the specified phone number. Returns `None` if no user was found.

## Sending SMS Messages

For sending SMS messages, various external providers and packages are available. You can integrate those by overriding the following adapter method:

> class allauth.account.adapter.DefaultAccountAdapter(request=None)

>   The adapter class allows you to override various functionality of the `allauth.account` app. To do so, point `settings.ACCOUNT_ADAPTER` to your own class that derives from `DefaultAccountAdapter` and override the behavior by altering the implementation of the methods according to your own needs.

>   send_verification_code_sms(user, phone: str, code: str, **kwargs)

>     Sends a verification code.

>   send_unknown_account_sms(phone: str, **kwargs) → None

>     In case enumeration prevention is enabled, and, a verification code is requested for an unlisted phone number, this method is invoked to send a text explaining that no account is on file.