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 of the workspace completes it.
How does an agent connect a WhatsApp number?
Create a connection request with
createWhatsAppConnectionRequest. Itsurlopens the Heythere console and stays valid for 1 hour.Give the URL to an administrator, and ask them to say when they are done.
The administrator selects Connect with WhatsApp, and picks the business account and the phone number in Meta's window.
Read the connection with
getWhatsAppConnectionuntil itsstatusisactive.
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 describes their parameters, payloads, and errors.
- POST
createWhatsAppConnectionRequestCreate a WhatsApp connection link
/api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests - GET
getWhatsAppConnectionRequestGet WhatsApp connection request status
/api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests/{connectionRequestId} - GET
getWhatsAppConnectionGet the workspace WhatsApp connection
/api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection - DELETE
disconnectWhatsAppConnectionDisconnect the workspace WhatsApp connection
/api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection - POST
createWhatsAppMediaREST onlyUpload a WhatsApp media
/api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/media