> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/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**, covering text chat, platform voice calls, and message templates.

| Mode        | Availability                                         |
| ----------- | ---------------------------------------------------- |
| Text chat   | Included with WhatsApp messaging access              |
| Voice calls | Included with WhatsApp voice access                  |
| Templates   | Uses the same WhatsApp Business account as text chat |

**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

Your plan includes WhatsApp text and/or WhatsApp voice.

## 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: the chat and outbound-voice assistants, **AI Auto-Responses**, **Keep conversations unread**, calling readiness (**Enable calling on Meta**), and the Business Profile (**About**, Description, Business Address, Business Category, logo, banner, websites, and contact emails/phones). **Sync** pushes the profile to Meta — the logo becomes your WhatsApp profile picture.
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. Place a test WhatsApp call from the connection panel

For manual setup, copy the webhook URL shown after connecting (verified custom domains are handled automatically) and subscribe to **messages**, **calls**, and **message template status updates**. For voice, also enable calling on the phone number under **Edit → Enable calling on Meta**.

## The 24-hour window and templates

Meta only allows freeform replies inside a **24-hour service window** that opens each time a customer messages you:

* **Inside the window** — your assistant can send any message, no template required.
* **Outside the window** — you must send an **approved template**. This applies to starting a new conversation, re-engaging a customer after 24 hours of inactivity, and any notification or marketing message you initiate.

Meta sorts templates into three categories, each with a different approval bar:

| Category           | Use for                                                                                       | Typical approval time  |
| ------------------ | --------------------------------------------------------------------------------------------- | ---------------------- |
| **Utility**        | Order/appointment confirmations, reminders, account notifications — never promotional content | Minutes to a few hours |
| **Marketing**      | Offers, announcements, re-engagement                                                          | Hours, up to 24 hours  |
| **Authentication** | One-time passwords, login/verification codes                                                  | Minutes to a few hours |

**Add template** creates Utility and Marketing templates, and the official library it browses is Utility. Authentication templates are created in WhatsApp Manager and picked up by **Sync with Meta** like any other template.

A **call-permission request** isn't a separate category — it's a `CALL_PERMISSION_REQUEST` button component added to a Utility or Marketing template to ask a customer for permission to call them over WhatsApp voice. Approval for that component is usually immediate.

<Note>
  Meta rejects templates that mix categories — for example, promotional language inside a Utility template. Other common rejection causes: vague example values for `{{1}}`/`{{2}}` variables (use realistic samples, not "test"), aggressive or urgent-sounding language, URL shorteners instead of your own domain, and restricted content (alcohol, gambling, adult, political, or otherwise prohibited categories).
</Note>

<Tip>
  Once a template is approved it can't be edited — create a new one instead. Keep a couple of backup templates ready for high-traffic use cases so a single rejection or disable doesn't block outreach.
</Tip>

## Message quality and sending limits

Meta controls how much a sender may send through two separate things.

**Quality rating** — **High**, **Medium**, or **Low**, based on how people react to your messages: blocks, spam reports, and whether they reply. It drops after a run of blocks or reports and recovers as you send relevant, requested content.

**Messaging limit** — how many customers you may start a conversation with in a rolling 24 hours. A new sender starts at the lowest tier (typically 250 customers) and Meta raises it a step at a time — 1,000, then 10,000, then 100,000, then unlimited — as you send more with a healthy quality rating. A rating that stays Low can freeze the tier or move it back down.

Replies inside an open 24-hour window don't count against the limit. Both values come straight from Meta and are shown per sender under **Edit → WhatsApp Sender Details** as **Quality Rating** and **Messaging Limit**, so build a track record of quality conversations before scaling volume.

## 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 Beta Features, WhatsApp voice access, an outbound-ready sender, and an approved call-permission template selected for that sender. Business-initiated calling also depends on Meta availability, region, and explicit customer permission. Permission requests and their visible **Awaiting permission** state are handled automatically. A grant resumes the lead only while its campaign is running.

Voice campaigns may use an approved WhatsApp template, SMS, or email as their single post-retry follow-up. Successful calls, suppressed contacts, and manually paused campaigns never create that follow-up. Template sends use the same messaging credits as session WhatsApp.

## Read-receipts webhook

In **WhatsApp Sender Details**, you can configure an HTTPS endpoint that receives delivery and read-status callbacks. Every callback is signed with HMAC-SHA256 over the exact raw request body. The signature is sent as `X-Signature-256: sha256=<hex digest>`.

A signing secret is generated when you first save the webhook URL. Existing secrets cannot be retrieved. Use **Rotate signing secret** in the sender settings, `POST /api/v1/whatsapp/connectors/{id}/profile` with `action=rotate_read_receipts_webhook_secret`, or the MCP tool `rotate_whatsapp_read_receipts_webhook_secret`. The new `signing_secret` is shown or returned exactly once, and the previous secret stops working immediately. Store the new value before leaving the response and update your receiver before sending a test request.

## History

Every WhatsApp conversation lands in [History](/monitoring/history) alongside your other channels:

* Text conversations appear as channel **WhatsApp**.
* Voice calls appear as 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.

When a customer sends a photo, your assistant automatically describes what's in it and can respond to the content as part of the conversation. Incoming voice notes are automatically transcribed and handled just like a typed message. Both the media and the resulting description or transcript are visible in the conversation.

## Billing

* Text: billed per message at the workspace's **Messaging (sent)** / **Messaging (received)** rate — the same rate [other messaging channels](/channels/messaging#billing) use. Current rates are on the [Usage page](https://app.famulor.io/usage).
* Voice: existing voice-minute credit reservation/settlement (same as phone/SIP calls)
* Meta conversation pricing: customer payment method in WhatsApp Manager (Tech Provider)

## Troubleshooting

A sender's status pill shows **PENDING**, **CONNECTED**, or **ERROR**.

<AccordionGroup>
  <Accordion title="Sender stays PENDING">
    Confirm you completed the full Meta signup popup and created (not reused) a WhatsApp Business account during setup, then refresh after a few minutes. Still pending after 30+ minutes: contact support with the sender ID.
  </Accordion>

  <Accordion title="Sender shows ERROR">
    Open **Edit** and read the last error. Credential problems are fixed by re-running the connect flow; a policy or quality suspension has to be addressed (usually spam-like sending behavior) and appealed through Meta.
  </Accordion>

  <Accordion title="Template rejected or disabled">
    The rejection reasons above are the usual causes; a disabled template is normally quality feedback. Create an improved version and narrow who you send it to.
  </Accordion>

  <Accordion title="Template pending for a long time">
    Marketing templates can take the longest; create an alternate template if you need to send sooner.
  </Accordion>

  <Accordion title="Messages not delivering">
    Send to numbers in E.164 format, confirm the recipient has WhatsApp, check the sender is CONNECTED, and confirm you haven't hit your messaging limit.
  </Accordion>

  <Accordion title="Freeform message rejected">
    You're outside the customer's 24-hour window; send an approved template instead.
  </Accordion>

  <Accordion title="AI not responding">
    Confirm an assistant is assigned to the sender and **AI Auto-Responses** is on, then check History for the conversation's error state.
  </Accordion>

  <Accordion title="Quality rating dropped or limits hit">
    Review what you sent right before the drop, tighten targeting, and reduce volume; both the rating and the tier recover as you send higher-quality, more relevant messages.
  </Accordion>

  <Accordion title="Meta popup doesn't appear or closes without completing">
    Allow popups for the site, clear cookies/cache, or retry in another browser; then re-run the connect flow from the start.
  </Accordion>
</AccordionGroup>

## Public API

* 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).
* Sender profile and read receipts: `GET`/`PATCH`/`POST /api/v1/whatsapp/connectors/{id}/profile` manages the sender profile, tests the signed callback, and rotates its signing secret.
* Messenger Connect can also be driven entirely through the API: `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 + `start_whatsapp_outbound_call` + `get_whatsapp_calling_status` + `manage_whatsapp_calling` + `rotate_whatsapp_read_receipts_webhook_secret` + `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).