# Connecting a number

URL: https://wa.genuka.com/en/docs/onboarding
Language: English

> Numbers join through Meta's Embedded Signup — no credentials ever pass through us, and none through you.

## The connect link

Every account has a unique public link at `/connect/{your-slug}`. Open it yourself to connect your
own number, or share it — by email, chat, or a button on your own site — with a business whose
numbers you manage. It shows your brand name and a **Connect WhatsApp** button.

## What happens during signup

1. ### Meta Embedded Signup opens

   The person connecting authenticates with Facebook and selects (or creates) the WhatsApp Business
   Account and phone number to use.

2. ### Authorization is exchanged

   On completion, the platform exchanges a one-time code for a long-lived access token, which is
   stored **encrypted**. The token never leaves the server.

3. ### The number appears in your dashboard

   A `Company` (named after the business Meta returns) and its `Connection` — the WABA plus the phone
   number — are created under your account. The WABA is subscribed to webhooks so statuses flow in,
   and the number is registered on the Cloud API so it can send right away.

> [!NOTE]
> **Numbers already on the WhatsApp Business app**
>
> A coexistence number stays on the WhatsApp Business app and is registered by Meta itself, so we
> leave its registration alone — it connects and sends exactly the same way. If a registration ever
> fails (an existing two-step PIN, for instance) the connection is still stored, and the number
> becomes usable once it is registered on Meta's side.

> [!NOTE]
> **What you can see afterwards**
>
> For every connected business: the WABA, its phone number(s) with quality rating and status, every
> template with its approval state, and message delivery stats (sent / delivered / read / failed
> with reasons).

## Knowing WHICH client connected WHICH number

If you share your link with several clients, put your own identifier for that client in it:

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

The reference lands on the `Company` created at the end of the flow, and you read it back:

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

One row: that client's. It spares you both wrong answers to this question — taking the most
recent connection, which eventually hands one client's number to another the day two of them
connect in the same minute; or showing the list and asking your client to point at their own,
which discloses every other client's number and business name on the way.

> [!NOTE]
> **Pick an unguessable reference**
>
> It travels in a URL. A sequential identifier (`client-42`) can be guessed, and whoever guesses
> it can attach their own number to that client. Use a UUID or equivalent randomness.

Accepted characters: letters, digits, `.` `_` `:` `-`, 128 max. A missing or malformed reference
is never quietly widened to the full list — the lookup simply returns zero rows. Sending the same
reference again on a reconnection moves it to the number that just connected: it is your ledger,
not ours.

## Hearing about a connection as it happens

Rather than polling `GET /api/v1/connections?externalRef=`, subscribe a webhook to the
`connection.connected` event (through the API, or by ticking "Number connected through your link"
in the dashboard). It fires at the end of every successful connection, reconnections included,
except for a suspended client, and its `data` is the row the lookup would return, with the
reference stored for that client:

```json title="POST https://your-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` is `null` when that client has none. A reconnection without `?ref=` keeps the one it
had. `isNewNumber` is false when a number your account already knows goes through the flow again,
a released number coming back included. `setupIssue` is `"registration_unconfirmed"` when
the number's Cloud API registration was not confirmed: the connection exists, but sending waits
for Meta to finish.

The event only reaches endpoints that ask for it, or that take every event (empty `events`). An
endpoint created before it existed with an explicit event list does not receive it: add it.

## Use case: connecting your clients' numbers hands-free

You publish software (billing, booking, e-commerce…) and your clients want your messages to leave
from **their** WhatsApp number. With a plan that includes managing client numbers (Scale or
higher), it all happens from your application:

1. ### A "Connect my WhatsApp" button in your app

   It opens `https://wa.genuka.com/connect/{your-slug}?ref={reference}`, where the reference is the
   **unguessable** identifier you gave that client and keep on your side.

2. ### Your client goes through Meta's checks

   They log in with Facebook and pick the number. Nothing else is asked of them.

3. ### You receive `connection.connected`

   Find your client by `data.externalRef`, and keep `connection_id`: it is what you pass to send and
   to create templates. Ignore an event whose reference matches none of your clients. The link is
   public, so anyone can follow it.

4. ### You create their templates

   One `POST /api/v1/templates` per template and language, with that `connectionId`. Your templates
   must exist on **their** WhatsApp Business account: those of your own number do not follow. You
   never need their Meta token: your API key is enough, the platform uses the token it stores for
   that number.

5. ### You follow approval, then switch over

   `template.status_changed` brings Meta's verdict, and
   `GET /api/v1/templates?companyId={company_id}&sync=true` is the safety net. Review usually takes a
   few hours, up to 48 h. Keep sending from your own number until every one of the client's templates
   is approved.

## Multiple numbers, limits & re-connection

You can connect as many numbers as your subscription pays for, spread across as many businesses as
you like. Connecting a brand-new number takes a free slot; going past the number count you paid for
is refused with `402 plan_limit_numbers`, and raising it takes a new payment from the Billing page.
Re-running the connect flow for a number that is already connected refreshes its token and details
rather than creating a duplicate — and never consumes a slot.
