> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lazyapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting WhatsApp

> Connect a WhatsApp Business Account via the console or platform setup links, then confirm with webhooks.

Before you can send, a workspace needs a connected WhatsApp number. LazyApp is WhatsApp-only — there is no multi-network OAuth catalogue. Connection always goes through Meta Embedded Signup; you never collect access tokens yourself.

## How to think about it

* **Own workspace:** connect from the LazyApp console (Embedded Signup). Connecting your own number needs a [plan](https://docs.lazyapp.in/billing/pricing-and-tiers.md), and each plan includes a set number of numbers; the shared test number is free.
* **Meta bills messages, not LazyApp.** Add a payment method to the WhatsApp Business Account in Meta. Meta charges it at Meta's rates, and LazyApp adds 0%. See [Meta message billing](https://docs.lazyapp.in/billing/meta-message-billing.md).
* **Your customers' numbers:** use [setup links](https://docs.lazyapp.in/platform/setup-links.md) so each [platform customer](https://docs.lazyapp.in/platform/overview.md) connects into their own workspace.
* Confirm from webhooks (`connection.connected` / `customer.connected`), not from the browser redirect alone.
* After connect, read [capabilities](https://docs.lazyapp.in/concepts/capabilities.md) for that number — calling, messaging limits, and quality are per connection.

```mermaid theme={null}
sequenceDiagram
  participant U as User or customer
  participant A as Your app or LazyApp console
  participant L as LazyApp
  participant M as Meta
  A->>L: Start Embedded Signup / create setup link
  L-->>A: Hosted connect URL
  A->>U: Open URL
  U->>M: Authorizes WABA + number
  M->>L: Signup completes
  L-->>A: webhook connection.connected / customer.connected
  Note over A: Store mapping; start sending
```

## Console Embedded Signup

For your own workspace:

1. Open **Connections** in the LazyApp console.
2. Start **Connect WhatsApp** (Meta Embedded Signup).
3. Finish Meta's screens (Business Portfolio, WABA, phone number).
4. LazyApp stores the connection on the current workspace and mode (`live` / `test`).

During onboarding you can also paste existing Meta credentials (phone number ID, WABA ID, system-user token) in the console. That path is **not** exposed as a public API endpoint — platform integrations should use [setup links](https://docs.lazyapp.in/platform/setup-links.md) instead.

Subscribe to:

| Event | When |
| - | - |
| `connection.connected` | The number is ready to send |
| `connection.attention_required` | Meta needs action (review, credentials) |
| `connection.disconnected` | The link to Meta stopped working |

There is no public `GET /v1/connect/{platform}` OAuth starter for Twitter/Facebook/etc. — that Zernio-style surface does not apply here. There is also no public `POST /v1/connect/whatsapp/credentials` — use Embedded Signup or setup links.

### Details filled in for you

When your workspace has a name, a website and a time zone (and you have a billing email or a login email), LazyApp sends them to Meta so the business portfolio screen arrives filled in. Meta only uses them when all four are present; the person signing up can still edit every field.

### Finishing without a phone number

A business can share or create a WhatsApp account in Meta's window and skip adding a number. LazyApp still connects the account and then asks which number to send from: pick one already on the account, or add a new one (country code, number, and the name customers will see). LazyApp holds the account for one hour while you choose. A new number then needs a verification code and registration; see [Phone numbers](https://docs.lazyapp.in/guides/phone-numbers.md#verify-and-register-a-number).

### When Meta's window closes early

If the person closes Meta's window, LazyApp shows which step they stopped at (choosing the business, the WhatsApp account, the number, the code or the permissions) and what to do next. If Meta showed an error, LazyApp repeats Meta's message with the error code and session id to quote to support.

> [!NOTE]
>
> While Meta is still reviewing LazyApp's app (App Review for `whatsapp_business_management` and `whatsapp_business_messaging`), Embedded Signup only completes for businesses LazyApp has added as testers. Until then, connect with **Paste details from Meta** using your own system-user token.

## WhatsApp Business app coexistence

Businesses already on the **WhatsApp Business app** can connect the same number to Cloud API without giving up the app. During Embedded Signup, Meta offers **Connect existing WhatsApp Business app account**. LazyApp marks the connection as coexistence and requests contact and history sync from Meta.

When coexistence is active:

* Messages can mirror between the app and Cloud API (Meta syncs up to about six months of history).
* Contacts from the app are imported via Meta's `smb_app_state_sync` webhooks.
* Outbound messages sent from the phone app arrive as `message.received` with an echo flag — treat them like inbound for inbox UX.
* Revokes in the app emit [`message.deleted`](https://docs.lazyapp.in/webhooks/events#messages) for the original stored message.

**LazyApp-specific:** coexistence numbers report `flows: false` and `flows.data_endpoint: false` on [`GET /v1/capabilities`](https://docs.lazyapp.in/concepts/capabilities). Plan Flow-based onboarding for Cloud-API-only numbers.

**Meta limitations** (same on every BSP):

| Feature | Coexistence |
| - | - |
| Throughput | Fixed at 20 messages per second |
| Deregistering | Not allowed while the app still uses the number |
| Group chats (app-side) | App groups are not visible via API |
| Groups API | Not supported on coexistence — use a Cloud-API-only number; see [Group chats](https://docs.lazyapp.in/guides/groups.md) |
| Voice/video calls via API | Not supported |
| Disappearing / view-once messages | Disabled for 1:1 Cloud API chats |
| Broadcast lists in the app | Disabled |

**History sync window:** LazyApp requests sync immediately after signup. Meta allows about **24 hours** to complete it. If sync never starts, the customer may need to disconnect and run Embedded Signup again.

**Disconnection:** The business disconnects from the WhatsApp Business app (**Settings → Account → Business Platform → Disconnect**). That cannot be done via API. Meta notifies LazyApp; the connection moves to a disconnected state and [`connection.disconnected`](https://docs.lazyapp.in/webhooks/events) fires. Treat webhook absence as inconclusive — poll [`GET /v1/capabilities`](https://docs.lazyapp.in/concepts/capabilities) when you need to confirm liveness.

> [!NOTE]
>
> Coexistence uses the same send and webhook endpoints as a standard Cloud API number. The practical differences are throughput, Flows being off, and read-state quirks when the phone app owns blue ticks.

## Platform customers (white-label)

When each of *your* users brings their own WhatsApp number:

1. Create a [platform customer](https://docs.lazyapp.in/platform/overview.md#step-1-create-a-customer-per-tenant).
2. Create a [setup link](https://docs.lazyapp.in/platform/setup-links.md) with their `customer_id` and your `redirect_url`.
3. Send them the returned `url` (email or **Connect WhatsApp** button).
4. Confirm with `customer.connected` (and `setup_link.failed` on failure).

```bash theme={null}
curl https://lazyapp.in/v1/platform/setup-links \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_9f8b1c2d",
    "expires_in_days": 7,
    "use_policy": "single",
    "allowed_connection_type": "new",
    "redirect_url": "https://yourapp.example/settings/whatsapp?connected=1"
  }'
```

### Headless vs hosted

LazyApp hosts the connect UI at `/connect/{token}`. You do not build a Meta page picker yourself — WhatsApp Embedded Signup selects the WABA and number inside Meta's flow. Set a public connect host in **Branding** when that URL should use your domain. The host must proxy `/connect` to LazyApp.

Optional per-link `success_webhook_url` / `failure_webhook_url` fire in addition to your workspace webhooks. Still treat them as secondary to `customer.connected` / `setup_link.failed`.

### Reconnect

When `connection.disconnected` or `connection.attention_required` fires for a customer, issue a new setup link with `allowed_connection_type: "reconnect"` (or `either`) and prompt them in your UI. Details in [setup links](https://docs.lazyapp.in/platform/setup-links.md).

## After connect

1. `GET /v1/capabilities` — confirm the number is listed and which features Meta granted.
2. Send a template or session message ([quickstart](https://docs.lazyapp.in/quickstart.md)).
3. Register webhooks for delivery and inbound ([webhooks](https://docs.lazyapp.in/webhooks/overview.md)).

Coexistence (WhatsApp Business app + Cloud API on the same number) is supported when Meta's onboarding path allows it — see [WhatsApp Business app coexistence](#whatsapp-business-app-coexistence) above for limits and webhook behaviour.

## Related

* [WhatsApp overview](https://docs.lazyapp.in/guides/whatsapp.md) — quick reference and doc map
* [Setup links](https://docs.lazyapp.in/platform/setup-links.md) — create, options, revoke
* [Build a platform](https://docs.lazyapp.in/platform/overview.md) — customer model and webhook routing
* [Capabilities](https://docs.lazyapp.in/concepts/capabilities.md) — what the connected number can do
* [Event reference](https://docs.lazyapp.in/webhooks/events.md) — `connection.*` and `customer.connected`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.