# Connecter un numéro

URL: https://wa.genuka.com/docs/onboarding
Language: French

> Les numéros arrivent par l'Embedded Signup de Meta — aucun identifiant ne passe par nous, ni par vous.

## Le lien de connexion

Chaque compte dispose d'un lien public unique à l'adresse `/connect/{votre-slug}`. Ouvrez-le
vous-même pour connecter votre propre numéro, ou partagez-le — par e-mail, messagerie ou via un
bouton sur votre site — avec une entreprise dont vous gérez les numéros. Il affiche le nom de
votre marque et un bouton **Connecter WhatsApp**.

## Ce qui se passe pendant la connexion

1. ### L'Embedded Signup de Meta s'ouvre

   La personne qui se connecte s'authentifie avec Facebook et sélectionne (ou crée) le compte
   WhatsApp Business et le numéro à utiliser.

2. ### L'autorisation est échangée

   À la fin du processus, la plateforme échange un code à usage unique contre un jeton d'accès
   longue durée, qui est stocké **chiffré**. Le jeton ne quitte jamais le serveur.

3. ### Le numéro apparaît dans votre tableau de bord

   Une `Company` (nommée d'après l'entreprise renvoyée par Meta) et sa `Connection` — le WABA et le
   numéro de téléphone — sont créées sous votre compte. Le WABA est abonné aux webhooks pour que les
   statuts remontent, et le numéro est enregistré sur la Cloud API afin de pouvoir envoyer
   immédiatement.

> [!NOTE]
> **Numéros déjà sur l'application WhatsApp Business**
>
> Un numéro en coexistence reste sur l'application WhatsApp Business et est enregistré par Meta
> lui-même : nous ne touchons donc pas à son enregistrement — il se connecte et envoie exactement
> de la même façon. Si un enregistrement échoue malgré tout (un code PIN en deux étapes déjà
> défini, par exemple), la connexion est tout de même enregistrée, et le numéro devient utilisable
> une fois enregistré côté Meta.

> [!NOTE]
> **Ce que vous voyez ensuite**
>
> Pour chaque entreprise connectée : le WABA, son ou ses numéros avec leur note de qualité et leur
> statut, chaque template avec son état d'approbation, et les statistiques de livraison des
> messages (envoyés / livrés / lus / échoués avec motifs).

## Savoir QUI vient de connecter QUEL numéro

Si vous partagez votre lien avec plusieurs clients, ajoutez-y votre propre identifiant pour ce
client :

```
https://wa.genuka.com/connect/{votre-slug}?ref=cli_8f3a91e4
```

Cette référence est posée sur la `Company` créée à la fin du parcours, et vous la retrouvez
ensuite :

```bash title="GET /api/v1/connections?externalRef=cli_8f3a91e4"
curl "https://wa.genuka.com/api/v1/connections?externalRef=cli_8f3a91e4" \
  -H "Authorization: Bearer pk_live_xxx"

{ "data": [ { "id": "con_1", "companyId": "cmp_123", "companyName": "Acme Coffee",
              "displayPhoneNumber": "+237 6 90 …", "externalRef": "cli_8f3a91e4",
              "qualityRating": "GREEN", "status": "connected" } ] }
```

Une seule ligne : celle de ce client. C'est ce qui vous évite les deux mauvaises réponses à cette
question — prendre la connexion la plus récente, qui finit par attribuer le numéro d'un client à
un autre le jour où deux se connectent à la même minute ; ou afficher la liste et demander à
votre client de désigner le sien, ce qui lui montre au passage les numéros et raisons sociales de
tous vos autres clients.

> [!NOTE]
> **Choisissez une référence imprévisible**
>
> Elle voyage dans une URL. Un identifiant séquentiel (`client-42`) se devine, et qui le devine
> peut rattacher son propre numéro à ce client. Utilisez un UUID ou un aléa équivalent.

Caractères acceptés : lettres, chiffres, `.` `_` `:` `-`, 128 au maximum. Une référence absente ou
malformée n'est jamais ignorée au profit de la liste complète : la recherche renvoie simplement
zéro ligne. Renvoyer la même référence lors d'une reconnexion la déplace vers le numéro qui vient
d'être connecté — c'est votre registre, pas le nôtre.

## Être prévenu dès qu'un numéro est connecté

Plutôt que d'interroger `GET /api/v1/connections?externalRef=` en boucle, abonnez un webhook à
l'événement `connection.connected` (par l'API, ou en cochant « Number connected through your
link » dans le tableau de bord). Il part à la fin de chaque connexion réussie, reconnexions
comprises, sauf pour un client suspendu, et `data` reprend la ligne que la recherche renverrait,
avec la référence enregistrée pour ce client :

```json title="POST https://votre-app.com/webhooks/genuka"
{
  "id": "cmh2…",
  "type": "connection.connected",
  "field": "connection.connected",
  "company_id": "cmp_123",
  "connection_id": "con_1",
  "waba_id": "102290129340398",
  "phone_number_id": "106540352242922",
  "data": {
    "id": "con_1", "companyId": "cmp_123", "companyName": "Acme Coffee",
    "externalRef": "cli_8f3a91e4",
    "wabaId": "102290129340398", "wabaName": "Acme Coffee",
    "phoneNumberId": "106540352242922", "displayPhoneNumber": "+237 6 90 …",
    "verifiedName": "Acme Coffee", "qualityRating": "GREEN", "status": "connected",
    "isNewNumber": true, "setupIssue": null,
    "connectedAt": "2026-10-31T10:00:00.000Z"
  }
}
```

`externalRef` vaut `null` quand ce client n'en a pas. Une reconnexion sans `?ref=` garde celle
qu'il avait. `isNewNumber` est faux quand un numéro déjà connu de votre compte refait le parcours,
y compris un numéro libéré qui revient. `setupIssue` vaut `"registration_unconfirmed"` quand
l'enregistrement du numéro sur la Cloud API n'a pas été confirmé : la connexion existe, mais
l'envoi attend que Meta finisse.

L'événement n'est livré qu'aux endpoints qui le demandent, ou qui reçoivent tous les événements
(`events` vide). Un endpoint créé avant son apparition avec une liste d'événements précise ne le
reçoit pas : ajoutez-le.

## Cas d'usage : brancher les numéros de vos clients sans intervention

Vous éditez un logiciel (facturation, prise de rendez-vous, e-commerce…) et vos clients veulent
que vos messages partent de **leur** numéro WhatsApp. Avec un abonnement qui inclut la gestion
de numéros de clients (Scale ou plus), tout se fait depuis votre application :

1. ### Un bouton « Brancher mon WhatsApp » chez vous

   Il ouvre `https://wa.genuka.com/connect/{votre-slug}?ref={référence}`, où la référence est
   l'identifiant **imprévisible** que vous avez attribué à ce client et conservé de votre côté.

2. ### Votre client fait les validations Meta

   Il se connecte à Facebook et choisit le numéro. Rien d'autre ne lui est demandé.

3. ### Vous recevez `connection.connected`

   Retrouvez votre client par `data.externalRef`, et conservez `connection_id` : c'est lui que vous
   passerez pour envoyer et pour créer des templates. Ignorez un événement dont la référence ne
   correspond à aucun de vos clients. Le lien étant public, n'importe qui peut le suivre.

4. ### Vous créez ses templates

   Un `POST /api/v1/templates` par template et par langue, avec ce `connectionId`. Vos templates
   doivent exister sur **son** compte WhatsApp Business : ceux de votre propre numéro ne le suivent
   pas. Vous n'avez jamais besoin de son jeton Meta : votre clé API suffit, la plateforme utilise le
   jeton stocké pour ce numéro.

5. ### Vous suivez l'approbation, puis vous basculez

   `template.status_changed` vous apporte le verdict de Meta, et
   `GET /api/v1/templates?companyId={company_id}&sync=true` sert de filet de sécurité. La revue
   prend en général quelques heures, jusqu'à 48 h. Continuez d'envoyer depuis votre numéro tant que
   tous les templates du client ne sont pas approuvés.

## Numéros multiples, limites et reconnexion

Vous pouvez connecter autant de numéros que votre abonnement en paie, répartis sur autant
d'entreprises que vous le souhaitez. Un nouveau numéro occupe une place libre ; dépasser le nombre
de numéros payés est refusé avec `402 plan_limit_numbers`, et l'augmenter demande un nouveau
paiement depuis la page Facturation. Relancer le flux de connexion pour un numéro déjà connecté
rafraîchit son jeton et ses informations plutôt que de créer un doublon — et ne consomme jamais de
place.
