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

# WhatsApp (Text + Voice)

> Connect WhatsApp Business Cloud API for chat and platform voice calls

WhatsApp is one workspace channel under **Settings → Channels → WhatsApp**.

| Mode        | Stack                                  | Plan flag                |
| ----------- | -------------------------------------- | ------------------------ |
| Text chat   | Meta Cloud API                         | `plans.whatsapp_channel` |
| Voice calls | Platform WhatsApp voice connector      | `plans.whatsapp_voice`   |
| Templates   | Meta Message Templates API + cron sync | same WABA as text        |

**Preferred onboarding (platform domain only, e.g. app.famulor.io):** [WhatsApp Embedded Signup](/channels/whatsapp-embedded-signup) (Connect with Meta). On whitelabel custom domains, workspaces use **manual credential paste** only.

**Marketplace numbers** (Settings → Numbers) are **PSTN/SIP** for phone voice. The same E.164 becomes WhatsApp only after Meta verifies it (OTP). Your SIP trunk settings are independent of WhatsApp Cloud API. Platform SMS helpers are SMS/MMS only — not used for WhatsApp.

## Prerequisites

**Workspace users**

* Plan includes WhatsApp text and/or WhatsApp voice
* Webhooks use your **base app URL** (platform host or verified custom domain). After you connect, Settings shows the exact webhook URL to paste into Meta if needed — no server env access required

**Platform operators** (Embedded Signup / Meta app): see [WhatsApp Embedded Signup](/channels/whatsapp-embedded-signup).

## Product UI

1. **Connect with Meta** (Embedded Signup) — pick assistant, optional marketplace number, OTP helper for marketplace SMS
2. Or paste credentials manually (token, app secret, verify token, phone number ID, WABA ID)
3. Toggles: text / voice inbound / voice outbound
4. **Edit** a connection → WhatsApp Sender Details (display name, AI auto-responses, keep unread, business profile, **Sync Profile to WhatsApp**, calling readiness)
5. Select **Templates** beside a sender to open its dedicated template page. **Sync with Meta** follows every result page, imports templates created in WhatsApp Manager, and refreshes approval status. **Add template** lets you create a custom draft or browse the official template library by language with a live phone preview. Variables must be numbered contiguously (`{{1}}`, `{{2}}`, `{{3}}`) and mapped to a system variable, lead attribute, assistant variable, or custom key. URL and phone-number buttons must be configured before a library template is added.
6. Test WhatsApp call (`POST /api/calls/whatsapp-outbound`)

Webhook (after connect): `https://app.famulor.io/api/webhooks/messaging/whatsapp/{connectorId}`\
Subscribe: **messages**, **calls**, **message\_template\_status\_update** (API v23/v24). For voice, also enable calling on the phone number (Edit → Enable calling on Meta).

## Campaigns

Choose **WhatsApp** in the campaign wizard to send an active sender's approved text template once per lead. Saved template bindings are prefilled and can be overridden per campaign. Mappings can use canonical contact fields, read-only channel/system variables, lead attributes, assistant variables, or a custom lead key.

**WhatsApp Call (Beta)** requires workspace Beta Features, `multichannel_campaigns`, `whatsapp_voice`, an outbound-ready sender, and a specifically selected **APPROVED call-permission template for that sender** (`channel_config.permission_template_id`). Campaign create and update fail closed without it; legacy campaigns keep their automatic fallback until edited. Business-initiated calling also depends on Meta availability, region, and explicit customer permission. Permission requests and their visible `Awaiting permission` delivery state are handled automatically. Inside the 24-hour service window the platform uses Meta's interactive request; outside it, the selected approved template opens the request. A grant only resumes the lead while its campaign is running.

Voice campaigns may use an approved WhatsApp template as their single post-retry follow-up. Successful calls, suppressed contacts, and manually paused campaigns never create that follow-up.

## History

* Text conversations: channel **WhatsApp** (`messaging_*` tables)
* Voice: channel **WhatsApp voice** (`calls.metadata.channel = whatsapp_voice`)

Completed text conversations remain manually replyable while Meta's 24-hour customer service window is open. After a manual reply, History asks whether to keep the conversation completed or reopen it with AI auto-replies. Reopening starts a fresh inactivity timer without extending Meta's 24-hour window.

## Billing

* Text: existing messaging receive/send credits
* Voice: existing voice-minute credit reservation/settlement (same as phone/SIP calls)
* Meta conversation pricing: customer payment method in WhatsApp Manager (Tech Provider)

## Public API

* Embedded Signup: `GET/POST /api/whatsapp/embedded-signup`, OTP session routes
* Messaging connectors: `GET/POST /api/v1/messaging-connectors` with `platform=whatsapp`
* Templates: `GET/POST /api/v1/whatsapp/templates`; use `source=library`, `language`, `limit`, and the returned `paging.after` cursor to browse the official library. `parameter_bindings` maps positions such as `1` or `header.1` to variable keys. Supply `library_template_name` plus `library_button_values` when a preset has URL or phone-number buttons. `action=update` edits drafts locally or sends component changes for an existing provider template. API and MCP clients can create the same call-permission template by supplying a `BODY` and `CALL_PERMISSION_REQUEST` component.
* Outbound voice: `POST /api/v1/calls/whatsapp-outbound`
* History AI resume: `POST /api/v1/history/actions` with `action=resume_ai`, `kind=messaging`, and the conversation ID
* Calling management: `GET /api/v1/whatsapp/calling` reads readiness (Meta call settings, webhook subscription, quality rating) for a connector's business number; `POST /api/v1/whatsapp/calling` runs `enable_calling`, `resubscribe`, or `ensure_voice`.
* Sender assets: `POST`/`DELETE /api/v1/whatsapp/connectors/{id}/assets` upload or remove a Business Profile logo/banner (URL or base64).
* Messenger Connect can now be driven entirely through the API too: `POST /api/v1/messenger/facebook-login/pages` lists the Facebook Pages a user access token can manage, ahead of `POST /api/v1/messenger/facebook-login`.
* MCP: WhatsApp template tools + `complete_whatsapp_embedded_signup` + `start_whatsapp_outbound_call` + `get_whatsapp_calling_status` + `manage_whatsapp_calling` + `upload_whatsapp_sender_asset` / `delete_whatsapp_sender_asset` + `list_messenger_facebook_pages`

The marketplace-number **OTP capture** session (the phone-number-verification step that turns a purchased number into a WhatsApp-capable one) stays dashboard-only — it's an interactive telephony flow with no REST/MCP equivalent.

See also [Embedded Signup setup](/channels/whatsapp-embedded-signup), [Messaging channels](/channels/messaging), [WhatsApp Voice](/telephony/whatsapp-voice).