# Connect WhatsApp

> How to link a WhatsApp number in coexistence or API-only mode, through Meta's official signup.

## Choose the mode

Messajo connects numbers through Meta's official signup (Embedded Signup), in two modes. You pick one when connecting, and it changes what the number can do:

| | Coexistence ("Keep my WhatsApp Business") | API only ("New number, API only") |
|---|---|---|
| WhatsApp Business app on the phone | Keeps working, and messages sent from the phone reach the API (`message.echo`) | The number is dedicated to the integration |
| Sending speed | Fixed at 20 msg/s | 80 msg/s, or 1,000 msg/s when Meta grants high throughput |
| 6 months of history and contacts | Synced once, within 24 h | None |
| Profile, display name and username | Edited in the phone app | Edited in the panel or through the API |
| Number registration | The number is not registered again | Registered with a random 6-digit PIN, stored encrypted |
| Partners at the same time | Only one | Several |

Use coexistence when support keeps happening on the phone. Use API only for volume or for a new number.

## Requirements

- A business portfolio at Meta and admin access to it.
- A phone number to connect.
- In coexistence: the number already active in the WhatsApp Business app **2.24.17 or newer**.
- In API only: a number that can receive the verification code by SMS or call and that is not in use in the app.
- In the panel, the owner or admin role, with 2FA turned on.

## Step by step in the panel

1. Open **Connections** and click **Connect WhatsApp**.
2. Pick the mode: **Keep my WhatsApp Business** (coexistence) or **New number, API only**. In coexistence, the panel shows the list of [limits](#coexistence-limits) before moving on. Click **Continue**.
3. Click **Open Meta's popup**. The popup opens in another window: do not close the panel page. If the browser blocks it, allow popups for the panel address and try again.
4. In the popup, log in to Facebook, choose (or create) the portfolio and the messaging account, and choose the number.
5. In coexistence, confirm in the phone app by scanning the QR code Meta shows. In API only, confirm the number with the code sent by SMS or call.
6. When the popup closes, the panel shows **Finishing the connection…** and then **WhatsApp connected.** The connection shows as **Active** and the `connection.created` event goes out.

On completion, the server exchanges the popup code for the account token (stored encrypted), checks that the chosen account is really the one the popup authorized, subscribes the app to the account webhooks, registers the number (API only) and reads the number's health. Accounts banned or flagged by Meta are refused before any change at Meta, with the [`account_flagged`](/en/errors#account_flagged) error.

### When a step is missing

If a step after the subscription fails, the connection stays **Pending** and the panel shows the reason, for example "Registering the number with Meta failed.". On the connection page:

- **Retry registration** redoes only the number registration (API only). Meta accepts up to 10 registrations per number in 72 h.
- **Finish connection** redoes what was missing, without opening the popup again.

Every step, from the popup and from the server, is recorded in the connection's **History** tab. A cancellation in the popup shows up there with the step where the person stopped.

## Invite the customer by link

Agencies can connect a customer's number without the customer creating a Messajo account. In **Connection links**, click **Create link** and fill in the form (the **Create connection link** button, in **Connections**, takes you there):

| Field | What it is |
|---|---|
| **Label** | Name of the link, only your team sees it |
| **Channel** | WhatsApp. Instagram and Messenger arrive in `0.2.0-alpha` |
| **Mode** | Coexistence, API only or "chosen by whoever opens it" |
| **Valid for** | 1 hour, 24 hours, 3, 7, 14 or 30 days. Default: 7 days |
| **Reusable** | Off, the link works for a single number; on, for several |
| **Password (optional)** | 8 to 128 characters, asked before the signup opens |
| **Page language** | Language of the page and of the email: Portuguese, English or Spanish |
| **Reconnect a connection (optional)** | Turns the link into a reconnection: it inherits the connection's mode and works once |
| **Email it to (optional)** | Sends the link by email right when it is created |

The link URL (`https://<panel>/c/<token>`) is shown **only once**, at creation: Messajo stores only the token hash. Copy it and send it any way you like, or send it through the platform email. **Send by email** generates a new token, and the previous URL stops working. The password never goes in the email: share it with the customer some other way.

The invite page does not ask for a login. It shows your organization's name and logo, lets the visitor switch the language, explains the modes and the coexistence limits, and opens the same Meta popup. At the end, it shows "Connection done. You can close this page." The connection belongs to your organization: the customer gets access to nothing.

- Five wrong passwords in a row lock the link for 15 minutes ([`link_locked`](/en/errors#link_locked)).
- A single-use link that was already used answers [`link_used`](/en/errors#link_used); an expired one, [`link_expired`](/en/errors#link_expired). To take a link down before it expires, use **Revoke**.
- The logo comes from **Settings → Organization**.

Links can also be created through the API, at `POST /v1/connection-links` (`admin` permission). See the [API reference](/en/reference).

## Coexistence limits

Meta enforces these rules on every number in coexistence:

- fixed speed of 20 msg/s;
- groups do not sync;
- broadcast lists become read-only;
- disappearing and view-once messages are turned off;
- the app must be opened every ~14 days;
- requires WhatsApp Business 2.24.17 or newer;
- only one partner at a time.

## Coexistence sync

Right after connecting in coexistence, Messajo asks Meta for the app contacts and then for up to 6 months of chats. The connection's **Sync** tab shows each one:

| Status | What it means |
|---|---|
| **Queued** | Not requested yet, or about to be requested again after a failure |
| **Requested from Meta** | Meta accepted the request and is sending the data |
| **Completed** | Everything arrived. History shows the progress in % per phase |
| **Declined** | The person declined to share history on the phone |
| **24 h deadline passed** | Meta only accepts the request up to 24 h after connecting |

Each sync happens only once. If the request fails, Messajo tries again after 1 min, 5 min, 15 min, 1 h, 3 h and 6 h, always within the 24 h. A failure here never takes the connection down. Contacts arrive as the `contacts.sync` event and chats as `history.batch`, and the imported messages show up in the logs with the `history` source.

## Switch partners in coexistence

In coexistence the number accepts one partner at a time. To bring a number that is already with another provider:

1. Back up the chats in the app.
2. In the app, go to **Settings > Account > Business platform > Disconnect**.
3. Connect again through Messajo, as in the step by step above.

The old partner gets Meta's `PARTNER_REMOVED` notice. If an error about the previous partner's line of credit shows up, follow [Meta's coexistence guide](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users).

## After connecting

The connection's **Overview** tab shows the number's **Health**:

- **Quality**: High, Medium, Low or Not rated, as Meta measures it;
- **Messaging tier**: how many new contacts per 24 h the portfolio can reach (see [Limits](/en/api/limits#meta-messaging-limit));
- **Speed**: 20, 80 or 1,000 msg/s, the throughput used when sending;
- **Sending**: Available, Limited or Blocked;
- the restriction, when Meta restricts the account, with its end date.

Messajo reads health every 15 minutes. **Refresh health** reads it right away. The **Profile** tab edits the business profile, requests a display name change and sets the username (API only).

Every status change emits a `connection.*` event to your [event destinations](/en/webhooks/events/), with the reason in `reason`, and an email to owners and admins, in each one's language.

## When the connection drops

| Status | When | What to do |
|---|---|---|
| **Needs reconnect** | Meta invalidated the token (error `190`), in a health read or a send | Reconnect |
| **Restricted** | Meta restricted the account for a period, or blocked sending due to policy | Wait for the period and fix the cause in WhatsApp Manager. Sending keeps working where Meta allows |
| **Disabled** | Policy violation or ban | Appeal at Meta. If Meta reinstates it, the connection goes back to **Active** on its own |
| **Disconnected** | The app was removed from the account, the account or number was deleted, or someone disconnected it in the panel | Connect again |

On error `190`, the email to owners and admins carries a **reconnect link**. On the connection page, **Reconnect** opens the popup again, and **Create reconnect link** creates a link to send to whoever manages the number. The reconnection must be for the **same number** ([`reconnect_mismatch`](/en/errors#reconnect_mismatch)) and keeps the connection `id`, the history and the destinations.

Reconnecting a **Disconnected** connection counts as a new connection for billing; reconnecting one in **Needs reconnect** does not. A WhatsApp Business Account (WABA) belongs to a single organization: connecting it in another returns [`waba_owned_by_other_org`](/en/errors#waba_owned_by_other_org). A **Disconnected** connection never goes back to **Active** on its own: only by reconnecting in the panel.

**Disconnect** stops receiving and sending on the number. In API only, you can also deregister the number at Meta. In coexistence, the panel shows how to remove access in the phone app.
