Connect WhatsApp Web through your phone: step by step

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.

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.
• 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:

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
• Connect WhatsApp Web by QR pairing
• Managed proxies for WhatsApp Web inboxes
• Inbox settings