## Overview

This is the hands-on guide to the **phone connection** for WhatsApp Web: the whole path, in the order
it really happens, for someone doing it for the first time. If you would rather first understand what
the feature is, what it promises and what it does not do, read
[Use your phone connection for WhatsApp Web](/hc/ajuda/articles/inboxes-channels-whatsapp-mobile-egress-en).

The work has two halves, and they are usually two different people:

1. **Prepare the network connection** — once per account. This is whoever owns the Tailscale account:
   an administrator of this account, or the platform operator when the network is shared by them.
2. **Enrol the phone and route the inbox** — always an administrator of this account, with the phone
   in hand.

This feature is in a **closed development pilot** and ships disabled. It has no SLA and is not
approved for production.

> There are two different QR codes in this flow. The first one puts the **phone** on the network. The
> second one pairs the **WhatsApp session** under Linked devices. One does not replace the other.

## Prerequisites

Go through this list **before** opening the wizard. Every item below has already sunk an entire
enrolment three screens away from the real error — checking now costs two minutes.

- **A Tailscale personal access token — required, not optional.** Tailscale publishes no OAuth scope
  that covers invitations. An OAuth client alone reads devices and creates route keys, but can
  **never** invite a phone. Without the token the connection can be saved, the test can partly pass,
  and enrolling the phone fails later. The token expires in **90 days** and has to be replaced before
  that.
- **The "Network name (tailnet)" field wants the Tailnet ID, not the display name.** The Tailnet ID is
  the identifier Tailscale uses for API calls. The display name usually works, but contains characters
  that are easy to mistype — when the screen says the network does not exist, this is almost always
  why.
- **The tag has to be authorised in the policy file.** The wizard shows a snippet ready to paste into
  the `tagOwners` section. Without that authorisation, the keys that put the account on the network
  are refused, and the failure surfaces far from this screen.
- **The plan has to allow the people who join the network.** Tailscale's Personal plan is free but
  allowed for non-commercial use only. Business use starts on a paid plan, billed per person who joins
  the network — **one person per phone you enrol**.
- **The phone has to be sharing its exit.** Installing the app and signing in is **not enough**: "Run
  as exit node" is a separate button, off by default. While it stays off, the device shows up on the
  network and the screen waits forever.
- An **account administrator** role to create or reconfigure a WhatsApp Web inbox.
- The **Phone connection** pilot enabled for this account by the platform operator.
- An Android phone or iPhone with the [official Tailscale app](https://tailscale.com/download).
- Access to the email address that will be used to sign in to Tailscale on the phone.
- Stable Wi-Fi or mobile data, and preferably the device on power.

Where each value comes from:

| Wizard field | Where it lives in Tailscale |
|---|---|
| Network name (tailnet) | Settings → **General** → **Tailnet ID** |
| OAuth client ID and secret | Settings → **Trust credentials** (the page once called "OAuth clients") |
| Personal access token | Settings → **Keys** |
| Tag snippet | copied from the wizard itself and pasted into the **policy file**, `tagOwners` section |

When you create the OAuth client, grant **only** `devices:core`, `devices:routes` and `auth_keys`, and
select the tag the wizard shows. Do not grant `users`: nothing here uses that scope, and it includes
user deletion.

## Step by step

### 1. Prepare the network connection (once per account)

1. Go to **Settings → Inboxes → Add inbox → WhatsApp Web** and pick **Use my phone** as the connection
   source.
2. If no network is ready, the wizard opens **Connect your own network account**, with three steps and
   everything ready to copy. If your operator already provides the network, this block appears as
   managed and you can skip straight to step 9.
3. **Create a Tailscale account**, if you do not have one.
4. **Add the tag to your policy file**: copy the snippet shown and paste it into the `tagOwners`
   section.
5. **Create an OAuth client** with the three scopes listed above and select the tag.
6. **Generate the personal access token** under Settings → Keys.
7. Fill in **Network name (tailnet)**, **OAuth client ID**, **OAuth client secret** and **Personal
   access token**, then click **Save connection**. Credentials are stored encrypted; leaving a field
   blank keeps the current value.

### 2. Test the connection before moving on

8. Click **Test connection**. The test no longer just counts devices: it exercises the three
   capabilities the enrolment depends on, and shows the result of each under **What this connection
   can do**.

   | Capability | What the test does | If it fails |
   |---|---|---|
   | Read the devices on the network | lists the tailnet's devices | check the Tailnet ID and the credentials |
   | Invite a phone | creates a throwaway invitation and **revokes it right after** | almost always the missing personal access token |
   | Create a route key | creates a key that lives 60 seconds and **revokes it right after** | check the `auth_keys` scope and the tag in the policy file |

   The test does not stop at the first failure: it shows the whole picture at once, with the date of
   the last check. A failed capability does not prevent saving the connection — but enrolling a phone
   will stop exactly there. Fix it before calling someone with a phone in their hand.

### 3. Enrol the phone

9. Read and accept the four confirmations about the network, battery and data, IP isolation and the
   calling limitation. They are required to continue.
10. Enter the **email that will be used on the phone** and click **Create temporary link**.
11. On the phone, scan the QR code or open the link. It is shown **once only**, expires in five
    minutes and must not be shared.
12. Install or open Tailscale, sign in with **exactly** that email and accept joining the network.
13. In the app, open **Exit Node** and tap **Run as exit node**. If it shows "Disabled" next to it,
    that is the current state — tapping is what turns it on. The five minutes are for **opening the
    link**: once the device is on the network the deadline grows, so you have time to find that button
    calmly.
14. Go back to the wizard and wait for **Phone connected**. If more than one device appears, pick
    explicitly the one you have just enrolled, comparing name and platform.

> **Shortcut.** If the phone is already on your network, turn **Run as exit node** on *before*
> creating the link. The wizard recognises the device that already advertises sharing and enrols it
> straight away, with no clock running.

### 4. Route the inbox

15. Under **Your phones**, click **Use for this inbox** on the chosen device and finish creating the
    channel.
16. When the WhatsApp QR appears, open **WhatsApp → Linked devices → Link a device** and do the normal
    pairing.
17. On an inbox that already exists, the path is **Settings → Inboxes → your inbox → Connection →
    Change route**, then **Route through this phone**.

## Settings & options

- **If the device becomes unavailable**: the default is **Hold messages until the device is back**.
  The alternative, **Keep sending through the default exit**, keeps the inbox working, but WhatsApp
  starts seeing the session leave from a different IP while the phone is away — which raises the risk
  for the number.
- **One inbox per phone**: the pilot's safe limit. The device stays reserved while the inbox keeps an
  active route.
- **Pause / Resume / Remove** a device: under **Your phones**. An active route has to be released
  first; removing a phone means enrolling it again to use it.
- **Swap phones**: **Change route → Switch to this phone**. The previous route stays in force until
  the new one is applied.
- **Check exit**: shows the IP the inbox is leaving from right now. If the gateway is too old to
  answer, the screen says so instead of inventing a result.

### Taking the inbox off the phone

You can now **remove the phone route** and return the inbox to a managed proxy or to the server's
direct exit — without creating a new inbox and without pairing the number again, which is what it used
to require. Do it under **Connection → Change route**, choosing the managed proxy. Before you confirm,
know what changes:

- **The other side starts seeing a different IP.** From the next connection on, the session leaves
  through whatever proxy the inbox already had configured or, when there is none, straight out through
  the server's internet. To WhatsApp that is a change of origin — and a change of origin weighs on how
  a number is judged. That is why removal is always an explicit, confirmed decision, never automatic
  and never a fallback: if the phone drops, the hold policy keeps holding the messages, and the
  platform does not swap the route on its own.
- **The inbox reconnects.** What is removed is the network path, not the WhatsApp session: a healthy,
  already-paired inbox stays paired. If the inbox was stuck waiting for a QR code, the old code stops
  working and a new one appears — scan the new one. An inbox you had deliberately turned off stays
  off.
- **Repeating is safe.** Ask twice and the second answer simply says there was no route left. If the
  network does not respond halfway through, try again: the operation is built to be repeated without
  breaking anything.

## Use cases

- Getting the first phone-routed inbox live without discovering the prerequisites one at a time, by
  trial and error.
- Validating a real residential route using the connection of the person who owns the number.
- Swapping the device serving an inbox when the original phone will be off the air.
- Returning an inbox to a managed proxy after the test, deliberately, knowing the IP WhatsApp sees
  changes.

## Tips, limits & best practices

- **Write down when the personal access token expires.** Ninety days. When it lapses, reading the
  network keeps working and inviting a phone stops working — the symptom only shows up at the next
  enrolment.
- **Test the connection whenever you change any credential.** It is the only place that answers "this
  one can invite" before you call the person with the phone.
- Keep Tailscale connected, allowed to work in the background and out of aggressive battery
  optimisation.
- Traffic uses the device's data plan. Check the allowance, roaming and the carrier's policies.
- The public IP can change when switching between Wi-Fi and mobile data, through CGNAT or by carrier
  decision.
- **The vendor warns that a phone as an exit node is not performant**: routing happens in user space,
  with no kernel optimisation. Measure before promising performance.
- **Voice and video calls do not go through this route** and are blocked in this mode.
- Do not use another account's network and do not share the temporary enrolment link.
- The feature does not prevent WhatsApp blocks and does not turn the Web connection into an official
  Meta API.

## Troubleshooting

Every item below starts with the sentence that appears on screen.

- **"Phone connection is not enabled"** — the pilot is off for this account. Talk to the platform
  operator; there is nothing to fix in the connection.
- **"Your role cannot manage the phone connection"** — this screen needs an administrator of this
  account.
- **"Phone connection is not set up yet"** — no network is connected. Do stage 1 of this guide, or ask
  the operator to enable their shared network.
- **"The connection cannot invite phones"** — the stored credentials read the network fine, but no
  OAuth scope covers invitations. Save a **personal access token** on this connection and test again.
  It is the one error whose remedy is exactly that.
- **"The network name does not exist"** — no network answers to the saved name. Use the **Tailnet ID**
  from Settings → General, not the display name.
- **"The network credentials were not accepted"** — the credential exchange returned no authorisation
  at all, which usually means a wrong OAuth client ID or secret. Redo stage 1; if it persists, the
  operator has the full response in the log.
- **"The invitation was not created"** — the network accepted the request and returned no invitation.
  No phone was enrolled and nothing was left hanging: try again.
- **"The invitation came without its link"** — the invitation exists on the network, but the one-time
  link did not come with it and cannot be recovered. Cancel and create another link.
- **"The device list could not be read"** — the network returned the list in a shape this screen
  cannot interpret. There is nothing to fix in the connection; the operator has the full response in
  the log.
- **"The phone is not sharing its connection yet"** — **Run as exit node** still has to be turned on
  in the app, on the phone itself. Turn it on and click **Check connection**, or wait for the
  automatic check.
- **"The route key was not issued"** — without that key the inbox cannot join the network. Try again;
  if it repeats, check that the OAuth client has the `auth_keys` scope and that the tag is authorised
  in the policy file.
- **"The chosen phone is no longer there"** — the device left the network between being picked and
  being saved. Nothing was recorded: refresh the list and pick again.
- **"There was not enough time to finish"** — the platform stopped before starting a step it could not
  have finished safely, precisely so nothing was left half-done. Try again; if it always happens, tell
  the operator.
- **"The network's answer could not be read"** — the network replied with something unreadable. The
  connection is not wrong; the operator has the status and body in the log.
- **"We could not identify the cause"** — the screen received a failure it does not recognise, so it
  cannot say what to change. Send the operator the approximate time of the attempt.
- **"Temporary link expired"** — create another one and open it on the phone within five minutes. If
  the device is already on the network, turn sharing on before creating the link.
- **"The one-time link has already been delivered"** — for safety it is never shown twice. If the phone
  never opened it, cancel the enrolment and create another link.
- **"Waiting for the phone to join"** that never moves — the device only appears if you signed in to
  the app with exactly the email you entered. Signed in with a different one? Cancel the link and
  create a new one with the right email.
- **The inbox is held or offline** — keep the phone online, check Tailscale and exit sharing, then
  refresh devices. With the hold policy, the platform will not use the direct exit while the phone is
  unavailable.
- **I cannot pause or remove the device** — first release the inbox that still uses that phone's active
  route.
- **I want to go back to a managed proxy** — you can: see "Taking the inbox off the phone" above, and
  confirm knowing that the IP WhatsApp sees changes.

## See also

- [Use your phone connection for WhatsApp Web](/hc/ajuda/articles/inboxes-channels-whatsapp-mobile-egress-en)
- [Connect WhatsApp Web by QR pairing](/hc/ajuda/articles/inboxes-channels-whatsapp-web-wazmeow-en)
- [Managed proxies for WhatsApp Web inboxes](/hc/ajuda/articles/inboxes-channels-whatsapp-web-proxy-global-en)
- [Inbox settings](/hc/ajuda/articles/inboxes-channels-configuracoes-de-inbox-en)