# 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 an AI agent to WhatsApp allows your audience to interact with the agent—and [subsequently with live agents](/docs/modules/ai-agents/workflows-and-actions/human-handoff.md)—in a WhatsApp thread. In the agent's **Publish** tab, [create a WhatsApp channel](/docs/modules/ai-agents/publishing.md#add-a-channel) or select an existing one from the table to open its settings. *** ## Basic Settings In the **Basics** accordion, the following options are available: * **Name** — the internal name of the channel, used to distinguish from any other WhatsApp channels the agent is published to. * **Default chat language** — the language used by the AI agent at the start of a new chat. Available languages are set in the agent's [General](/docs/modules/ai-agents/manage-ai-agents.md#general) settings. * **Icon** — the channel's avatar seen by live agents in the [Inbox](/docs/modules/inbox.md) dashboard. Press **Save** to confirm edits. *** ## Connecting to WhatsApp In the **Configuration** accordion, four values are required from your Meta Developer account: * **App ID** * **App secret** * **User access token** * **Phone number ID** Then, you'll need to integrate a Proto webhook with Meta Developer. Follow the guides below for each step. *** ### App ID and App Secret Meta Developer provides the app ID and secret: 1. Login to your [Meta Developer account](https://developers.facebook.com/). 2. If you don't already have a Meta app for this connection: 1. Go to **My Apps**. 2. Select **Create App**. 3. Fill in the required details and press **Create app**. 3. Go to **My Apps** and select the one you want to connect to Proto. 4. In its **Dashboard** tab, scroll down to WhatsApp and select **Set up**. 5. Create or choose a **Meta Business Account** and press **Continue**. At this stage: * Your App is associated with the Meta Business Account. * A WhatsApp test phone number is made available, to prevent having to register or migrate a real number. Test numbers can send unlimited messages to up to five recipients, anywhere in the world. 6. In the **Settings > Basic** tab, copy the **App ID** and **App secret** and paste them into Proto's respective WhatsApp configuration fields. *** ### User Account Token Meta Business provides the user account token: 1. Login to [Meta Business](https://business.facebook.com/settings) with the same Meta Business account used earlier. 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 to the Business Account. 4. In the System Users screen, ensure the Meta App is listed under **Assigned Assets**. If not, select **Add Assets** and add the app for system users. 5. Select **Generate Token** and choose the **Meta App**. 6. Before generating the token, you must enable the business\_management permission for your app: 1. In a new tab, go to [Meta Developer](https://developers.facebook.com/) > **My Apps** > select your app. 2. Navigate to **Permissions and features** (under Use cases > Customize). 3. Find business\_management in the permissions list. 4. Select **Add to App Review** to enable it for your app. 5. Return to the System User token generation screen in Meta Business. 7. After choosing the app, a list of available permissions appears. Select the following: * **whatsapp\_business\_management** * **whatsapp\_business\_messaging** * **business\_management** 8. Press **Generate Token**, and paste it into Proto's WhatsApp **User access token** field. *** ### Phone Number ID Connect a chosen phone number to your WhatsApp account by getting its phone number ID. Starting in Meta Business: 1. Login to [Meta Business](https://business.facebook.com/settings) with the same Meta Business account used earlier. 2. Go to **Business Manager** and select your **business**. 3. Select **三** (3 lines) in the top left corner. 4. Go to the **Engage customers** section. 5. Select **WhatsApp Manager**. 6. Select the **WhatsApp Business account** that you want to set up the phone number for. 7. Navigate to the left-most menu and select **Phone Numbers**. 8. Press **Add Phone Number**. 9. In the Business profile section, enter your **WhatsApp Business display name** and the **category** of your business, and proceed with **Next**. Your customers will see the display name when they receive messages from you. 10. Enter the **phone number** for your business, choose how you'd like to verify, and proceed with **Next**. 11. Enter the **verification code**. 12. Add the new phone number to your phone number list. The certificate for this phone number will be provided based on your current business account status: * If verified, your display name is ready and the certificate is available for download immediately. * If unverified, your phone number will be pending review. Once approved, use the **View** button to see the available certificate for the phone number. Then, in Meta Developer: 1. Login to [Meta Developer](https://developers.facebook.com/). 2. Go to **My Apps** > **WhatsApp** > **Getting Started**. 3. Copy the **Phone Number ID,** and paste it into Proto's WhatsApp **Phone Number ID** field. *** ### Proto Webhook For Proto to send and receive message from WhatsApp, a webhook integration is required. 1. Login to [Meta Developer](https://developers.facebook.com/). 2. Go to **My Apps** > **WhatsApp** > **Configuration**. 3. Under Webhooks press **Edit**, which prompts for the following: * **Callback URL** — copy in the **Webhook URL** from Proto's WhatsApp **Webhook** accordion. * **Verify Token**: copy in the **App secret** from Proto's WhatsApp **Setup** accordion. 4. Press **Verify and Save**. 5. Go back to **My Apps > WhatsApp** > **Configuration**. 6. Under Webhooks press **Manage**. 7. In the Webhooks table, locate the messages field and enable its subscription toggle. This allows Proto to exchange messages with WhatsApp. {% hint style="warning" %} Business must [receive opt-in](https://developers.facebook.com/docs/whatsapp/overview/getting-opt-in) before messaging a person on WhatsApp. {% endhint %} *** ## WhatsApp Messaging Incoming messages are unlimited, but there are limits for outgoing messages. See WhatsApp's [messaging limits](https://developers.facebook.com/docs/whatsapp/messaging-limits#messaging) for more information on messaging tiers. Use WhatsApp's [message templates](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates) to send business-initiated messages to people who've opted into notifications or customer care messages. *** ## WhatsApp Pricing Businesses are charged [per conversation](https://developers.facebook.com/docs/whatsapp/pricing) by Meta, completely independent of Proto. The first 1,000 conversations each month are free, and [credit card must be added](https://www.facebook.com/business/help/488291839463771) to your Meta Business account for more. *** ## Using WhatsApp Add the WhatsApp account's phone number to your contacts, then start a new WhatsApp chat with that contact. This will begin a thread with the AI agent. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.proto.cx/docs/modules/ai-agents/publishing/whatsapp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.