> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/modules/ai-agents/publishing/whatsapp.md).

# WhatsApp

{% hint style="info" %}
Publish to WhatsApp with the Lite plan and above.
{% endhint %}

{% hint style="warning" %}
Requires [Meta Developer](https://developers.facebook.com/docs/development/register/) and [Meta Business](https://business.facebook.com/settings) accounts.
{% endhint %}

Publishing to WhatsApp lets your audience interact with the AI agent — and later a [live agent](/docs/modules/ai-agents/workflows-and-actions/human-handoff.md) — in a WhatsApp thread.

In the agent's **Publish** tab, create a WhatsApp channel or select an existing one to open its settings.

***

## Basic settings

| Setting                   | Description                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Name**                  | Internal name distinguishing this channel from other WhatsApp instances.            |
| **Default chat language** | Set from the agent's [Agent settings](/docs/modules/ai-agents/manage-ai-agents.md). |
| **Icon**                  | The channel's avatar, seen by live agents in the [Inbox](/docs/modules/inbox.md).   |

Select **Save** to confirm edits.

***

## Connect to WhatsApp

Four values are required from your Meta Developer account, set in the **Configuration** accordion: **App ID**, **App secret**, **User access token**, and **Phone number ID**. You'll also integrate a Proto webhook with Meta Developer.

{% tabs %}
{% tab title="App ID & secret" %}

1. Log in to your [Meta Developer account](https://developers.facebook.com/).
2. If you don't already have a Meta app: **My Apps → Create App**, fill in the details, and select **Create app**.
3. Select the app to connect to Proto.
4. In its **Dashboard** tab, scroll to WhatsApp and select **Set up**.
5. Create or choose a **Meta Business Account** and select **Continue**.
6. In **Settings → Basic**, copy the **App ID** and **App secret** into Proto's WhatsApp configuration fields.
   {% endtab %}

{% tab title="User access token" %}

1. Log in to [Meta Business](https://business.facebook.com/settings) with the same account.
2. Select the business connected to your Meta App and WhatsApp account.
3. If there's no System User, select **Add** to apply an **ADMIN** system user.
4. Ensure the Meta App is listed under **Assigned Assets**; if not, add it.
5. Select **Generate Token** and choose the Meta App.
6. Select the permissions: `whatsapp_business_management`, `whatsapp_business_messaging`, `business_management`.
7. Select **Generate Token** and paste it into Proto's **User access token** field.
   {% endtab %}

{% tab title="Phone number ID" %}

1. Log in to [Meta Business](https://business.facebook.com/settings).
2. Go to **WhatsApp Manager** → select your WhatsApp Business account.
3. Go to **Phone Numbers → Add Phone Number**.
4. Enter your business display name and category, then proceed.
5. Enter and verify the phone number.
6. In [Meta Developer](https://developers.facebook.com/) → **My Apps → WhatsApp → Getting Started**, copy the **Phone Number ID** into Proto.
   {% endtab %}

{% tab title="Proto webhook" %}

1. In Meta Developer → **My Apps → WhatsApp → Configuration**.
2. Under Webhooks, select **Edit**.
3. Paste Proto's **Webhook URL** as the Callback URL, and Proto's **App secret** as the Verify Token.
4. Select **Verify and Save**.
5. Return to **Configuration**, select **Manage** under Webhooks, and enable the **messages** subscription.
   {% endtab %}
   {% endtabs %}

{% hint style="warning" %}
Businesses must [receive opt-in](https://developers.facebook.com/docs/whatsapp/overview/getting-opt-in) before messaging a person on WhatsApp.
{% endhint %}

***

## Messaging & pricing

| Topic                    | Detail                                                                                                                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Message limits**       | Incoming messages are unlimited; outgoing messages have tiered limits. See WhatsApp's [messaging limits](https://developers.facebook.com/docs/whatsapp/messaging-limits#messaging). |
| **Conversation pricing** | Meta charges businesses [per conversation](https://developers.facebook.com/docs/whatsapp/pricing), independent of Proto. The first 1,000 conversations each month are free.         |

***

## Using WhatsApp

Add the WhatsApp account's phone number to your contacts, then start a new chat with that contact to begin a thread with the AI agent.