---
app: agent
audience:
  - owner
since: 0.1.2
ui_only: false
agent_actions:
  - tool: app_channel_status
    permission: auto
    example: is the WhatsApp number connected?
agent_examples:
  - the WhatsApp QR code expired
  - customers get a pairing code instead of an answer
llm_weight: normal
title: WhatsApp problems
description: Expired QR, strangers getting a pairing code, a phone that still
  shows the device, a number that keeps disconnecting.
editUrl: true
head: []
template: doc
sidebar:
  order: 3
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { AgentAsk } from "@components";

**Who this is for:** an owner whose WhatsApp number (QR route) misbehaves.

## Symptoms and fixes

| Symptom | Cause | Fix |
|---|---|---|
| **"The QR code expired — start the pairing again."** | A QR is valid for two minutes. | Press **Start QR pairing** again and scan within two minutes. |
| **"Pairing failed: the WhatsApp bridge stopped"** | The bridge process died mid-pairing. | Wake the agent (or restart the app) and pair again. |
| **Customers receive "I don't recognize you yet — here's your pairing code"** | The number was linked before *Who can chat* existed and still runs the raw pairing policy. | Open **Settings → Accounts**, click the number's row, pick **Public** or **Private** in the pane on the right, and press **Save** once. |
| **The phone still lists the device after Unlink** | Unlinking removes it on the computer; WhatsApp keeps its own list. | On the phone: **Linked devices** → remove it. |
| **Connected, but no answers** | Agent asleep, or the sender is not on a Private list. | Wake the agent; check [Who can chat](/agent/channels/who-can-chat/). |
| **The row flips to error every few minutes** | Another WhatsApp session on the same computer, or the number was paired on a second device and WhatsApp dropped this one. | Keep one link per number; pair again with **Scan again (new phone)**. |
| **The row shows enabled but "not paired"** | A profile that was set up but never scanned. | Open the row and press **Start QR pairing**. |

## Meta's rules

The QR route uses WhatsApp Web on a regular number. Meta may ban numbers it considers automated — use a dedicated business number, keep the pace human (the agent answers as fast as a person types, never bulk), and never message people who did not write first. For a verified business number use the official route (Cloud API).

## Ask your agent

<AgentAsk />

## Related

[Link WhatsApp with a QR code](/agent/channels/whatsapp-qr/) · [Who can chat](/agent/channels/who-can-chat/) · [An agent is not working](/agent/troubleshooting/agent-not-working/)