> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# WhatsApp connection: link your WhatsApp Business Account

> Connect your WhatsApp Business Account and up to 20 of its numbers through Meta's signup, and know what stops a number from sending.

Before the online shop can tell its customers that the Ember jacket ships late, it connects its WhatsApp number to Heythere. A workspace's WhatsApp connection links one WhatsApp Business Account, and up to 20 of its phone numbers, to the workspace. Every message the workspace sends or receives goes through it.

Meta requires a person of the business to approve the connection in a browser, through Meta's Embedded Signup. An agent starts the connection, and an [administrator](https://heythere.io/docs/concepts/organizations-and-workspaces) of the workspace completes it.

## How does an agent connect a WhatsApp number?

1. Create a connection request with `createWhatsAppConnectionRequest`. Its `url` opens the Heythere console and stays valid for 1 hour.
2. Give the URL to an administrator, and ask them to say when they are done.
3. The administrator selects Connect with WhatsApp, and picks the business account and the phone number in Meta's window.
4. Read the connection with `getWhatsAppConnection` until its `status` is `active`.

Connecting another number of the same business account takes a new connection request. A business account and each of its numbers belong to one workspace at a time.

## What stops a connection from sending?

| `status`          | Meaning                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `active`          | Every number sends and receives messages.                                                  |
| `action_required` | A number needs an administrator, as its `registrationState` says. The others keep sending. |
| `restricted`      | Meta stopped the business account from sending, as its `standing` says.                    |
| `access_revoked`  | Heythere lost access to the business account: connect again.                               |
| `disconnecting`   | An administrator disconnected the workspace.                                               |

Most problems with a number end the same way: an administrator reconnects it through a new connection request. A restriction from Meta lifts only on Meta's side, in Meta Business Support Home.

## What does disconnecting remove?

Disconnecting stops the workspace's numbers from sending and receiving, and removes the connection's numbers, message templates, and media from Heythere. The templates stay in the business account at Meta, and come back when the workspace connects it again.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `createWhatsAppConnectionRequest`: Create a WhatsApp connection link. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests`
- `getWhatsAppConnectionRequest`: Get WhatsApp connection request status. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests/{connectionRequestId}`
- `getWhatsAppConnection`: Get the workspace WhatsApp connection. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection`
- `disconnectWhatsAppConnection`: Disconnect the workspace WhatsApp connection. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection`
- `createWhatsAppMedia` (REST only): Upload a WhatsApp media. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/media`
