· 5 min · TextMeFlow Team

Associer WhatsApp par QR code : appairage et ré-appairage

Avant de pouvoir envoyer le moindre message via TextMeFlow, votre numéro WhatsApp doit être relié à votre compte. Cela fonctionne comme « WhatsApp Web » ou « Appareils connectés » dans l'application WhatsApp officielle : vous scannez un QR code une seule fois, et la connexion reste active jusqu'à ce que vous la déconnectiez explicitement ou que WhatsApp impose une nouvelle liaison. Aucune application supplémentaire à installer, aucune portabilité de numéro : votre numéro continue de fonctionner normalement sur votre téléphone pendant que TextMeFlow envoie et reçoit via la même session.

Cet article détaille ce qui se passe réellement pendant l'appairage, comment interroger le résultat et que faire lorsqu'une connexion doit être refaite.

Démarrer une session d'appairage

L'appairage se fait en deux étapes via l'API. D'abord, vous demandez un QR code :

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

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

La réponse contient un pair_id et un champ qr_png_b64, un PNG encodé en base64 que vous affichez directement dans un navigateur ou un panneau d'administration. Ouvrez WhatsApp sur le téléphone à connecter, allez dans Appareils connectés → Associer un appareil et scannez le code exactement comme pour WhatsApp Web. Le label n'est qu'un nom lisible qui permet de distinguer les appareils par la suite, ce qui devient important dès que vous en gérez plusieurs.

Interroger le résultat

Le scan n'est pas confirmé instantanément côté API : WhatsApp doit d'abord terminer sa propre négociation. Interrogez le endpoint de statut jusqu'à ce que le résultat soit définitif :

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"
}

Appelez-le toutes les deux secondes environ depuis votre écran d'onboarding jusqu'à obtenir connected (affichez un message de réussite), expired (le QR code a expiré avant d'être scanné : demandez-en un nouveau) ou failed (un problème est survenu côté WhatsApp : demandez là aussi un nouveau code). Un résultat pending signifie simplement « continuez d'attendre ».

Dès qu'un appairage passe à connected, plus rien à faire : la session persiste de notre côté après les redémarrages, et les messages envoyés via /v1/messages ou le endpoint de compatibilité /send.php partent par ce numéro relié jusqu'à sa déconnexion.

Combien de numéros peut-on associer

Chaque forfait permet d'associer au moins un numéro. Free, Starter et Pro sont mono-appareil ; Business autorise jusqu'à 3 numéros associés simultanément sur le même compte, ce qui convient à un accueil, une ligne commerciale et une ligne support fonctionnant en parallèle. Si vous vous demandez si vous en avez vraiment besoin, le guide de configuration multi-appareils pour équipes explique comment les équipes répartissent généralement le trafic entre plusieurs numéros associés plutôt que de partager une seule boîte de réception.

Ré-appairage et déconnexion

Deux choses imposent un nouvel appairage : vous vous déconnectez explicitement, ou le téléphone est déconnecté des sessions WhatsApp Web (réinitialisation d'usine, dissociation manuelle depuis le téléphone, ou réauthentification périodique de WhatsApp lui-même). Pour vous déconnecter volontairement de votre côté, par exemple lors d'un changement de carte SIM ou du retrait d'un appareil, appelez :

DELETE /v1/accounts/me/session

Cela met fin proprement à la session liée. Aucune étape de « dissociation » distincte n'est nécessaire : le prochain appel POST /v1/accounts/me/pair génère un nouveau QR code pour le même compte. Gardez à l'esprit que le téléphone lui-même doit rester en ligne et connecté à internet au moins périodiquement : comme pour WhatsApp Web, l'appairage est une session rattachée au client WhatsApp de votre téléphone, pas une connexion totalement indépendante aux serveurs de WhatsApp.

Conseils pratiques

  • Générez le QR code juste avant que quelqu'un ne le scanne. Considérez expired comme l'issue normale d'un code laissé ouvert toute une nuit dans un onglet de navigateur, et non comme une erreur à déboguer.
  • Donnez un label clair à chaque appareil ("front-desk", "support-line-2") pour qu'un compte Business avec 3 numéros ne devienne pas un casse-tête par la suite.
  • Si des messages se mettent soudain à échouer après des semaines de bon fonctionnement, vérifiez le statut d'appairage avant de soupçonner un problème d'API ou de compte : un téléphone resté hors ligne longtemps, ou sur lequel WhatsApp a été réinstallé, nécessitera un nouveau scan.

L'appairage est un coût de mise en place ponctuel par appareil, pas quelque chose que vous retoucherez souvent une fois stable. Pour tout ce qui suit (envoi, réception de réponses, gestion des médias), consultez la vue d'ensemble des événements webhook pour voir comment les messages entrants parviennent à votre système une fois un numéro connecté.

Commencez gratuitement sur textmeflow.eu/signup?plan=free : associez votre premier numéro en moins de deux minutes et envoyez jusqu'à 50 messages par mois sans frais.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours