> ## Documentation Index
> Fetch the complete documentation index at: https://brosbots.mintlify.site/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. 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.**

<Warning>
  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 Meta will reject the message. The after-call message makes sense for
  contacts who message you on WhatsApp - otherwise send an after-call SMS. The
  after-call message does not use Meta's approved message templates, so it
  cannot get around this limit.
</Warning>

## 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 24-hour window is closed - see the warning above. |


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