> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/whatsapp.md).

# Connect a Conversation Platform: WhatsApp

Integrate the WhatsApp channel: prepare a Meta Business account and WhatsApp Business API credentials, add a channel in MaiAgent, and bind an Agent.

## Before You Integrate <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* An "AI Assistant" has been created on the [MaiAgent platform](https://admin.maiagent.ai/)
* You have a [Meta Business](https://business.facebook.com/) account
* A phone number ready to integrate. Either of the following works:
  * A number already linked to a WhatsApp Business account, or a number added in the Meta authorization window
  * A number currently in use in the WhatsApp Business App on a phone; the App can still be used after integration, see [Sharing a Number with the WhatsApp Business App](#business-app-coexistence)

## Start Integrating <a href="#start-integration" id="start-integration"></a>

### 1. Open the Channel Integration Page <a href="#step-go-to-channel-page" id="step-go-to-channel-page"></a>

In the left menu, select <mark style="color:blue;">Messaging Channels</mark>, then click the <mark style="color:blue;">Connect Channel</mark> button at the top right.

### 2. Select WhatsApp <a href="#step-select-whatsapp" id="step-select-whatsapp"></a>

On the platform selection page, click <mark style="color:blue;">WhatsApp</mark>.

### 3. Connect a Facebook Account <a href="#step-connect-facebook-account" id="step-connect-facebook-account"></a>

Click the <mark style="color:blue;">Connect WhatsApp</mark> button; the system opens a Facebook OAuth login window.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-09c1beb016a12dcb7030760d06d8b163e178d65c%2Fwhatsapp-connect-button.png?alt=media" alt="The WhatsApp step of connecting a channel, with the Connect WhatsApp button in the center of the screen"><figcaption><p>Click Connect WhatsApp to open the Meta authorization window</p></figcaption></figure>

1. Log in to your Facebook account
2. Authorize MaiAgent to access WhatsApp Business management permissions
3. Follow the instructions in the Meta window to select or create a WhatsApp Business account and phone number. To integrate a number currently used by the WhatsApp Business App, choose the option to connect an existing WhatsApp Business App, and complete the confirmation in the App on your phone as instructed
4. After authorization is complete, the window closes automatically and returns to the settings page

{% hint style="warning" %}
Make sure your browser allows pop-up windows; otherwise the OAuth login window may be blocked.
{% endhint %}

### 4. Select the WhatsApp Business Account and Phone Number <a href="#step-select-whatsapp-business-account-and-phone" id="step-select-whatsapp-business-account-and-phone"></a>

After OAuth authorization is complete:

1. From the <mark style="color:blue;">Select WhatsApp Business account</mark> dropdown, choose the business account you selected in the Meta window; the options appear as "WABA" followed by the account's numeric ID, not the account name
2. From the <mark style="color:blue;">Select phone number</mark> dropdown, choose the phone number that will receive messages: if a number was already selected in the Meta window, the list shows only that number; for a number integrated from the WhatsApp Business App, or when only a business account was selected in the Meta window, the list shows the numbers under that business account

If you chose the wrong account or number, click <mark style="color:blue;">Reload</mark> at the top right before saving to authorize again.

{% hint style="warning" %}
After saving, the business account and phone number can no longer be changed, and the <mark style="color:blue;">Reload</mark> button does not appear on the edit page. To use a different account or number, delete this WhatsApp channel and create it again.
{% endhint %}

### 5. Basic Settings <a href="#step-basic-settings" id="step-basic-settings"></a>

| Field             | Description                                                                                                                                                                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Channel name**  | Give this integration a name for easy identification                                                                                                                                                                                                                                                                             |
| **AI Assistant**  | Select the Agent to bind                                                                                                                                                                                                                                                                                                         |
| **Reset command** | (Optional) When turned on, you can add one or more command texts (for example "Start over"); when a message a user sends on WhatsApp exactly matches one of them, a new conversation is started for that user. The command itself receives no reply; the AI answers in the new conversation when the user sends the next message |

### 6. Save Settings <a href="#step-save-settings" id="step-save-settings"></a>

After confirming the settings are correct, click <mark style="color:blue;">Save</mark> to complete the integration.

Once the integration is complete, when users send messages to that phone number through WhatsApp, the Agent replies automatically.

{% hint style="info" %}
After a successful integration, you can find it in the channel list; click Edit to configure further feature options (OCR recognition, scheduled replies, permission control, and so on).
{% endhint %}

## Sharing a Number with the WhatsApp Business App <a href="#business-app-coexistence" id="business-app-coexistence"></a>

A number already run on the phone with the WhatsApp Business App can be integrated with MaiAgent without switching to a new number: in the Meta window from [Connect a Facebook Account](#step-connect-facebook-account), choose to connect an existing WhatsApp Business App, and when finished, select that number as described in [Select the WhatsApp Business Account and Phone Number](#step-select-whatsapp-business-account-and-phone). No separate activation is needed on the MaiAgent side.

After integration, the number works on both the App and MaiAgent:

* **The App keeps working**: The number stays in the WhatsApp Business App on your phone, and you can continue to view and reply to customers in the App
* **The Agent replies to customer messages**: Messages customers send to this number enter MaiAgent, and the bound Agent replies automatically

{% hint style="warning" %}

* **Replies in the App do not enter MaiAgent**: Messages you reply to customers yourself in the phone App do not appear in MaiAgent's conversation records, and the Agent does not stop replying because of them; for the same customer's next message, the Agent still answers as usual. When a human needs to take over, take over the reply in MaiAgent, see [Human Agent Handoff and Replies](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/human-handoff-operations.md)
* **Conversations before integration are not imported**: Chat history in the App from before integration is not imported into MaiAgent; MaiAgent's conversation records start from the first message a customer sends after integration
  {% endhint %}

{% hint style="info" %}
Whether a number can be integrated this way (for example, by country/region or App version) depends on the options shown in the Meta authorization window.
{% endhint %}

## Message Format and Consecutive Messages <a href="#message-format-and-merging" id="message-format-and-merging"></a>

* **Markdown is automatically converted to text**: Markdown syntax in Agent replies, such as headings, links, tables, and code, is automatically converted to plain text before being sent to WhatsApp (a link becomes "text URL"), and bold uses WhatsApp's own `*bold*` style; text typed by human agents is not affected, see [Message Rendering Optimization: Messaging Channels](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)
* **Consecutive messages are merged into one round**: When a user sends several images in a row, or sends an image and then types text, the Agent waits for the whole series of messages to arrive and then answers once (for image-only messages, it answers when no new message arrives about 4 seconds after the last one, up to about 20 seconds at most; as soon as text is received, it answers immediately); only one round is processed at a time per conversation

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Situation or error message                                                                                                                                 | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Solution                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The organization receives the platform announcement "WhatsApp integration requires reconnection", and that WhatsApp channel no longer replies to customers | Meta has invalidated the authorization MaiAgent stored and it cannot be renewed automatically. Common causes: the Facebook account that authorized this integration changed its password, removed MaiAgent's app permissions in Facebook settings, the authorization expired, or Meta reset the login state for security reasons. The system checks the authorization once a day and issues the announcement only when a renewal attempt fails, so the channel may stop replying first and the announcement arrives later | Go to <mark style="color:blue;">Messaging Channels</mark>, delete this WhatsApp channel, then recreate it with the same phone number following [Start Integrating](#start-integration). The announcement ends automatically after deletion                                                     |
| "WhatsApp registration was not completed. Please try again." appears after connecting                                                                      | After authorization in the Meta window, the system did not receive the WhatsApp Business account to integrate (for example, no business account was selected in the Meta window), or MaiAgent failed while processing this authorization. If the Meta window is closed midway, the screen shows no message and simply stays on the original page                                                                                                                                                                          | Click <mark style="color:blue;">Connect WhatsApp</mark> again and complete the steps of selecting the business account and phone number in the Meta window; if the same message still appears on retry, contact customer support                                                               |
| The <mark style="color:blue;">Select phone number</mark> dropdown is empty                                                                                 | The selected WhatsApp Business account has no phone numbers yet                                                                                                                                                                                                                                                                                                                                                                                                                                                           | In Meta's WhatsApp management tools, add and verify a phone number for this business account, or add a number directly in the Meta authorization window; then click <mark style="color:blue;">Reload</mark> at the top right to authorize again                                                |
| "WhatsApp phone number registration failed." appears when saving                                                                                           | Meta refused to let this number start using the WhatsApp Cloud API, for example because the number has not completed verification, or a two-step verification PIN has been set in Meta. For a number in use by the WhatsApp Business App, the system may have failed to check the number's status with Meta at that moment and mistakenly taken the registration steps for a regular number                                                                                                                               | Regular number: in Meta's WhatsApp management tools, confirm the number has completed verification; if two-step verification is set, turn it off and save again. Number in use by the WhatsApp Business App: turning off two-step verification does not help; please save again a little later |
| "This WhatsApp phone number is already in use." appears when saving                                                                                        | This phone number is already integrated with another WhatsApp channel (possibly in another organization), and one number can be integrated with only one channel                                                                                                                                                                                                                                                                                                                                                          | First delete the WhatsApp channel that currently uses this number (if it is in another organization, contact that organization's administrator), then create it again                                                                                                                          |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/whatsapp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
