# WhatsApp

Send template messages, broadcasts, flows and replies from a WhatsApp Business Account with the Zernio API, plus groups, calling and Click-to-WhatsApp attribution.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { PlatformCapabilities } from '@/components/platform-capabilities';

Send template messages, broadcasts, flows and replies on WhatsApp from a connected WhatsApp Business Account (platform value `whatsapp`).

A conversation starts with `POST /v1/inbox/conversations` and a template. A broadcast starts with `POST /v1/broadcasts`.

The same account serves:

- The [inbox](/platforms/whatsapp/inbox)
- [Group chats](/platforms/whatsapp/groups)
- [Voice calling](/platforms/whatsapp/calling)
- [Click-to-WhatsApp attribution](/platforms/whatsapp/ctwa)

## Quick reference

<PlatformCapabilities rows={[
  { property: 'Message types', value: 'Text, template, image, video, document, audio, interactive, location, contact card' },
  { property: 'Template required', value: 'Yes, outside the 24-hour customer service window' },
  { property: 'Media limits', value: <><a href="/platforms/whatsapp/reference#media-requirements">Media requirements</a></> },
  { property: 'Scheduling', value: 'Broadcasts only (no scheduled single messages)' },
  { property: 'Inbox (DMs)', value: 'Yes' },
  { property: 'Inbox (comments)', value: 'No' },
  { property: 'Group chats', value: <>Yes, non-coexistence numbers only (<a href="/platforms/whatsapp/groups">Group chats</a>)</> },
  { property: 'Flows', value: 'Yes (forms, surveys, booking)' },
  { property: 'Calling', value: <>Yes, inbound and outbound voice (<a href="/platforms/whatsapp/calling">Calling</a>)</> },
  { property: 'Analytics', value: 'No (delivery status per message only)' },
]} />

## Before you start

WhatsApp requires a WhatsApp Business Account (WABA) inside a Meta Business account ([business.facebook.com](https://business.facebook.com)). A personal WhatsApp account cannot be connected.

The WABA is created during the connection flow if you do not have one. It needs at least one phone number registered to it.

Two rules shape every send:

- **The 24-hour window.** You can message a customer freely for 24 hours after their last message. Outside that window the message must be an approved template ([Templates](/platforms/whatsapp/templates)).
- **The messaging tier.** A freshly connected number starts on Meta's lowest tier, 250 unique contacts per day. Meta raises it as you build messaging history and keep quality up.

## Connect

Call `GET /v1/connect/whatsapp` with `profileId` and `redirect_url`.

Embedded Signup is the only browser route onto Meta's Cloud API. The coexistence variant adds a QR code the business scans with the WhatsApp Business app ([coexistence](/platforms/whatsapp/connect#whatsapp-business-app-coexistence)).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: connect } = await zernio.connect.getConnectUrl({
  path: { platform: 'whatsapp' },
  query: {
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4',
    redirect_url: 'https://myapp.com/callback',
    onboarding: 'api'
  }
});

console.log(connect.authUrl);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

connect = client.connect.get_connect_url(
    platform="whatsapp",
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    redirect_url="https://myapp.com/callback",
    onboarding="api",
)

print(connect["authUrl"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/connect/whatsapp?profileId=66a1f0c2a4b9d3e8f1a2b3c4&redirect_url=https://myapp.com/callback&onboarding=api" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "authUrl": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...",
  "state": "..."
}
```

Send the user to `authUrl`. They land back on `redirect_url` with `accountId`, the id every WhatsApp call takes from here on.

Three questions decide how you connect. The [connection guide](/platforms/whatsapp/connect) answers each with the call to make:

- **Whose number.** A number you [buy through Zernio](/platforms/whatsapp/phone-numbers) can also carry Calls and SMS and can only be connected on the profile it was bought for. A number you already own connects through Embedded Signup or with a Meta System User token.
- **Coexistence or Cloud API only.** Keeping the number in the WhatsApp Business app (coexistence) caps throughput at 20 messages per second and turns off the Groups API and calling. Pass `onboarding=api` to skip it.
- **Several numbers per profile.** A profile can hold several WhatsApp numbers, each its own account. A number can be live on one profile only.

## Who bills what

WhatsApp has two billers, Zernio and Meta. [Pricing & costs](/platforms/whatsapp/pricing) says which charge lands on which invoice.

[WhatsApp rates](/pricing/whatsapp) has Meta's numbers by country.

## Analytics

WhatsApp exposes no post-level analytics through its API.

Delivery status (sent, delivered, read) is tracked per message and per broadcast recipient. It arrives as the `message.delivered` and `message.read` events ([inbox webhooks](/platforms/whatsapp/inbox#webhooks)).

## Common errors

The connect call fails on a `404` when `profileId` is unknown, and on a `402` when the team has no payment method ([connecting accounts](/guides/connecting-accounts#if-it-fails)).

The conflicts that matter for WhatsApp appear later, when the user picks a number. They come back on your `redirect_url` as one of:

- `error=one_whatsapp_per_profile`
- `whatsapp_number_pinned_to_profile`
- `whatsapp_number_already_connected`

Each has its fix in [connection and setup](/platforms/whatsapp/connect#if-it-fails).

## In this section

<PlatformPages platform="whatsapp" />

## Related

- [Connecting accounts](/guides/connecting-accounts): the redirect flow, headless mode and [scopes](/guides/connecting-accounts#scopes) shared by every platform.
- [Messages](/messages/list-inbox-conversations): the inbox API reference.
- [Broadcasts](/broadcasts/create-broadcast) and [Contacts](/contacts/list-contacts): API reference.
- [WhatsApp webhooks](/webhooks/whatsapp) and [phone number webhooks](/webhooks/phone-numbers): template reviews, number lifecycle.
- [Phone numbers](/platforms/phone-numbers): buying, porting, KYC and per-country pricing.