---
app: agent
audience:
  - owner
since: 0.1.0
ui_only: true
agent_actions:
  - tool: app_channel_status
    permission: auto
    example: is Maya's WhatsApp connected?
  - tool: app_ui_open
    permission: auto
    example: open the WhatsApp pairing dialog for Maya
  - tool: app_channel_access
    permission: confirm
    example: make Maya's WhatsApp public
agent_examples:
  - connect WhatsApp to Maya
  - why did Maya's WhatsApp disconnect?
llm_weight: normal
title: Link WhatsApp with a QR code
description: Connect a WhatsApp number (unofficial route) to one agent by
  scanning a QR code.
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { Steps, Aside } from "@astrojs/starlight/components";
import { AgentAsk, UiOnly, Shot } from "@components";

**Who this is for:** an owner giving one agent its own WhatsApp number. You need: the agent **awake**, a phone with that number's WhatsApp, and a number not linked to another WhatsApp Web.

<UiOnly />

## Steps

<Steps>

1. Open **Settings → Accounts → WhatsApp → Add account**, pick the agent, choose **Unofficial — scan a QR code**. <Shot src="agent/channels/whatsapp-qr-01-add.png" alt="Add account dialog with the two WhatsApp routes" />

2. Press **Start QR pairing**. A QR code appears in the dialog; it is valid for two minutes (press the button again for a fresh one).

3. On the phone: WhatsApp → **Linked Devices** → **Link a Device** → scan. The row turns *connected* and shows the number.

4. Choose **Who can chat**: **Public — anyone** for customers, **Private — listed ids only** plus the allowed numbers (country code, no +) for staff. Press **Save** — the agent's gateway restarts with the new policy.

</Steps>

After that, every message to the number reaches the agent, which answers from it. Customer conversations show up in the panel's **Inbox** tab.

<Aside type="tip">
  Use **Scan again (new phone)** on the same row when the number moves to another phone. **Unlink** removes the session and tells the phone; if the phone still lists the device, remove it under Linked Devices.
</Aside>

## Ask your agent

<AgentAsk />

## Limits & safety

- The QR route is unofficial — Meta may block the number. One number = one agent.
- The session file stays on your computer; the tablet and the agents never see it.
- The agent replies to anyone in a Public channel: give it a role brief that says what it may promise.

## Troubleshooting

- **"Strangers currently receive a pairing code…"** — press **Save** once more; the row was created with an old policy.
- **QR expired** — press **Start QR pairing** again.
- **Connected, but no replies** — the agent is asleep (wake it) or the number is Private and the sender is not listed.
- **Two agents, one number** — the second scan disconnects the first. Use a second number, or [One number per room](/agent/channels/one-number-per-room/).

## Related

[Who can chat](/agent/channels/who-can-chat/) · [One number per room](/agent/channels/one-number-per-room/) · [Channels overview](/agent/channels/overview/)