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

# WhatsApp Business

> Your agent chats on WhatsApp, answers WhatsApp calls and sends messages from your company's own number.

## What the integration gives you

Once a WhatsApp Business number is connected, the agent does three things on
that one number:

* **Answers messages.** A customer writes on WhatsApp, the agent replies using
  its own prompt and remembers the thread.
* **Answers calls.** A call placed from inside WhatsApp reaches the same voice
  agent that answers the phone - same voice, same tools, same transcript and
  call history.
* **Sends messages.** During a phone call (the `send_whatsapp` tool) or
  automatically once the call ends.

Messages go through **your Meta account**, not ours. We add no per-message
fee - you are billed by Meta directly.

## What you need

* A **Meta for Developers** account and a **Business** app with the
  **WhatsApp** product added.
* A phone number registered on the WhatsApp Business Platform (Cloud API).

<Note>
  **A number from the WhatsApp Business app.** The integration does not support
  coexistence, where one number works in the WhatsApp Business app on a phone
  and in the API at the same time. Connecting a number you use in the app means
  moving it to the Cloud API, and it then stops working in the app. To keep
  receiving messages in the app, connect a separate number or stay with an
  after-call SMS - it can carry a `https://wa.me/48...` link that opens a chat
  with the app's number.
</Note>

## Setup

### 1. Copy the details from your Meta app

In the app dashboard, under **WhatsApp → API Setup**:

* **Phone Number ID** - the number's id, not the phone number itself.
* **Access Token**.

<Warning>
  The temporary token on that tab expires after 24 hours. For permanent use
  generate a system user token with the `whatsapp_business_messaging` and
  `whatsapp_business_management` permissions.
</Warning>

The **App Secret** is under **App Settings → Basic**. It is not required, but
without it we accept webhooks without verifying their signature, so filling it
in is recommended.

### 2. Connect the number in Brosbots

1. Open the **Integrations** page and pick **WhatsApp Business**.
2. Paste the Phone Number ID, the access token and the App Secret.
3. In the **Agent** field choose the agent that answers messages and calls.
   With no agent chosen, messages are only recorded.
4. Optional: in **After-call template** enter the name of a message template
   Meta has approved, and in **Template language** the language it was
   approved in (`pl` when empty). Only with a template can the agent send
   WhatsApp after a call - see [After the call](#after-the-call).
5. Save. We check the credentials against Meta before anything is stored.

### 3. Go back to Meta for the webhook

After saving we show two values: the **Callback URL** and the **verify token**.
In your Meta app, under **WhatsApp → Configuration → Webhooks**:

1. Paste both and click **Verify and save**.
2. Subscribe to the **messages** and **calls** fields.

Messages and calls now reach the agent.

## Text conversations

The agent answers with its own prompt - the same one it speaks on the phone -
plus an instruction telling it that it is writing on WhatsApp, so it keeps
replies short and does not read numbers out digit by digit.

The thread is remembered for **24 hours**, which is how long WhatsApp's own
customer service window lasts. Someone who writes again a week later starts a
fresh conversation.

Only text is answered. A voice note, image or document is recorded and
answered with a short note asking the person to write instead - rather than
with silence.

## Sending messages from the agent

In the agent editor, on the **Integrations** tab, switch on **Send WhatsApp**
and choose when it sends:

* **During the call** - the model decides, following your rules.
* **After the call** - from a template, with the same variables as SMS: what
  the agent collected, the call's own facts (`{{caller_number}}`,
  `{{call_time}}`, `{{call_disposition}}`) and `{{gathered_context.*}}`.
  Unlike an SMS, `{{call_summary}}` resolves here - WhatsApp is billed per
  conversation, not per 160 characters - but it has to be typed by hand, since
  the **Insert variable** menu no longer offers it.
* **Both.**

The **After the call** and **Both** options appear only once the WhatsApp
connection has an approved template - see below. Until then the editor shows a
note and the agent sends WhatsApp during the call only.

### After the call

WhatsApp only lets a business send free text to someone who wrote to its
number in the last 24 hours. After a phone call that window is usually closed,
and then Meta delivers only a **message template it has approved** - free
text is rejected. So the after-call message goes out as a template:

1. In **WhatsApp Manager → Message templates** create a template (the
   *Utility* category suits a follow-up) with **one variable `{{1}}`** in its
   body, e.g. "Thank you for the call. `{{1}}`". Wait for Meta to approve it.
2. On the **Integrations** page edit the WhatsApp connection and enter the
   template's name in **After-call template** and its language code in
   **Template language** (e.g. `pl`, `en_US`).
3. In the agent, choose **After the call** and write the text as before. It
   fills the template's `{{1}}`, folded onto one line (Meta rejects line
   breaks inside a variable) and cut at 1,000 characters.

An agent that was set to send after the call before this existed keeps the
setting and keeps sending free text, which reaches only contacts who wrote in
during the last 24 hours. The editor shows the warning next to it; add a
template to the connection, or switch the agent back to **During the call**.

## Voice calls

A WhatsApp call runs exactly the same path as a call through the website
widget, so the agent sounds the same and has the same tools. The call appears
in **Call history** and is billed like any other - an organization at zero
balance does not answer.

## Troubleshooting

| Symptom | Cause |
| - | - |
| Meta will not verify the callback URL | The verify token or the URL does not match. Copy both again from the Integrations page. |
| The connection test reports an auth error | The token expired - generate a system user token. |
| Messages arrive but the agent does not reply | No agent is chosen on the connection, or the connection is switched off. |
| The after-call message never arrives | The connection has no approved template and the 24-hour window is closed - see [After the call](#after-the-call). |
| "After the call" is not in the agent editor | The WhatsApp connection has no **After-call template** yet. |
| Meta rejects the template message (`#132000`, `#132001`) | The template name or language does not match the approved template, or its body does not have exactly one `{{1}}` variable. |


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