How WhatsApp Pairing Works on textmeflow: QR Codes, Polling and Re-Pairing

Before you can send a single message through textmeflow, your WhatsApp number needs to be linked to your account. This works the same way "WhatsApp Web" or "Linked Devices" does inside the official WhatsApp app: you scan a QR code once, and the connection stays live until you explicitly log it out or WhatsApp forces a re-link. There's no separate app to install and no phone number porting — your number keeps working normally on your phone while textmeflow sends and receives through the same session.

This post walks through what actually happens during pairing, how to poll for the result, and what to do when a connection needs to be redone.

Starting a pairing session

Pairing is a two-step API flow. First, you request a QR code:

POST /v1/accounts/me/pair
Authorization: Bearer <your API key>
Content-Type: application/json

{ "label": "front-desk-phone" }

The response contains a pair_id and a qr_png_b64 field — a base64-encoded PNG you render directly in a browser or admin panel. Open WhatsApp on the phone you want to connect, go to Linked Devices → Link a Device, and scan the code exactly as you would for WhatsApp Web. The label is just a human-readable name so you can tell devices apart later, which matters once you're running more than one.

Polling for the result

Scanning doesn't confirm instantly from the API's point of view — WhatsApp has to complete its own handshake first. Poll the status endpoint until it settles:

async function waitForPairing(pairId, apiKey) {
  const res = await fetch(
    `https://api.textmeflow.eu/v1/accounts/me/pair/${pairId}/status`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  const { status } = await res.json();
  return status; // "pending" | "connected" | "expired" | "failed"
}

Call this every couple of seconds from your onboarding screen until you get connected (show a success state), expired (the QR timed out before it was scanned — request a fresh one), or failed (something went wrong on WhatsApp's side — also request a fresh code). A pending result just means "keep waiting."

Once a pairing reaches connected, no further action is needed — the session persists across restarts on our side, and messages sent via /v1/messages or the /send.php compatibility endpoint go out through that linked number until it's disconnected.

How many numbers you can pair

Every plan pairs at least one number. Free, Starter and Pro are single-device; Business allows up to 3 concurrently paired numbers on the same account, which is what makes it a fit for a front desk, a sales line and a support line running in parallel. If you're weighing whether you actually need that, the multi-device team setup guide covers how teams typically split traffic across paired numbers rather than sharing one inbox.

Re-pairing and logging out

Two things force a re-pair: you explicitly disconnect, or the phone itself gets logged out of WhatsApp Web sessions (a factory reset, a manual unlink from the phone, or WhatsApp's own periodic re-authentication). To disconnect from your side deliberately — swapping to a new SIM, decommissioning a device — call:

DELETE /v1/accounts/me/session

This ends the linked session cleanly. There's no separate "unpair" step needed beyond this; the next POST /v1/accounts/me/pair call generates a fresh QR code for the same account. Keep in mind that the phone itself must stay online and connected to the internet at least periodically — like WhatsApp Web, the pairing is a session against your phone's WhatsApp client, not a fully independent connection to WhatsApp's servers.

Practical tips

• Generate the QR code close to when someone will actually scan it — treat expired as the normal outcome of leaving a code open in a browser tab overnight, not an error to debug.
• Use a clear label per device ("front-desk", "support-line-2") so a Business-plan account with 3 numbers doesn't turn into a guessing game later.
• If messages suddenly start failing after weeks of working fine, check pairing status before assuming an API or account issue — a phone that's been offline for an extended period, or that had WhatsApp reinstalled, will need a re-scan.

Pairing is a one-time setup cost per device, not something you'll touch often once it's stable. For everything after that — sending, receiving replies, handling media — see the webhook events overview for how inbound messages reach your system once a number is connected.

Start free at textmeflow.eu/signup?plan=free — pair your first number in under two minutes and send up to 50 messages a month at no cost.