Connect channels
Connect WhatsApp
How to link a WhatsApp number in coexistence or API-only mode, through Meta's official signup.
Choose the mode
Section titled “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
Section titled “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
Section titled “Step by step in the panel”- Open Connections and click Connect WhatsApp.
- Pick the mode: Keep my WhatsApp Business (coexistence) or New number, API only. In coexistence, the panel shows the list of limits before moving on. Click Continue.
- 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.
- In the popup, log in to Facebook, choose (or create) the portfolio and the messaging account, and choose the number.
- 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.
- When the popup closes, the panel shows Finishing the connection… and then WhatsApp connected. The connection shows as Active and the
connection.createdevent 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 error.
When a step is missing
Section titled “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
Section titled “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). - A single-use link that was already used answers
link_used; an expired one,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.
Coexistence limits
Section titled “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
Section titled “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
Section titled “Switch partners in coexistence”In coexistence the number accepts one partner at a time. To bring a number that is already with another provider:
- Back up the chats in the app.
- In the app, go to Settings > Account > Business platform > Disconnect.
- 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.
After connecting
Section titled “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);
- 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, with the reason in reason, and an email to owners and admins, in each one’s language.
When the connection drops
Section titled “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) 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. 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.