# Connect WhatsApp

Connect a WhatsApp Business number so customer messages land in the inbox, while the WhatsApp Business app on your phone keeps working.

Connect a **WhatsApp Business** number and customer messages land in the **Inbox**, next to your other channels. The number stays in the WhatsApp Business app on your phone: messages you send from the phone show in the conversation too, and both stay in sync. Distribution rules, flows, the AI assistant and reports work as on every other channel.

## What it supports

| Direction | Supported |
|---|---|
| Receiving | Text, images, video, voice and audio, documents, stickers, locations, contacts, button and list replies, quoted replies |
| Sending | Text (quoting the customer's message), images, video (MP4 up to 16 MB; larger ones go as a document), audio and documents; approved templates after 24 hours |
| From the phone | Messages you send in the WhatsApp Business app appear in the conversation as agent messages |
| Status | Sent, delivered and read ticks on your replies; the customer sees their message read when an agent opens the conversation |

## Before you start

- A phone number that uses the **WhatsApp Business** app, version 2.24.17 or later. Regular WhatsApp numbers cannot connect: install WhatsApp Business and move the number to it first.
- A Facebook account. You pick or create a Meta business portfolio while connecting.
- A website under **Customer Support → Channels**, and the **Manage** level on the Customer Support module.

## Connect a number

1. Go to **Customer Support → Channels**, click **Add channel** and pick **WhatsApp** under **Messaging apps**.
2. If the business has several websites, choose one under **Attach new connections to site**.
3. Click **Connect WhatsApp**. A Facebook window opens.
4. Sign in to Facebook and pick or create your business.
5. Enter your WhatsApp Business number. The window shows a QR code.
6. On the phone, open WhatsApp Business, confirm the connection and scan the QR code.
7. Back on the computer, finish the steps in the Facebook window.

The number appears under **Messaging apps** with the status **Active**. Its page shows the phone number, when it was connected and the last message or event.

![A connected WhatsApp number's page](https://hatang.dev/help/img/en/channels/whatsapp-page.webp)

> [!NOTE]
> Only messages received **after** connecting arrive in the Inbox. Older chats are not imported.

If the Facebook window closes before the end, the page shows "Not connected: the Facebook window closed before the end". If it says "Could not load the Facebook SDK", turn off ad blockers and try again.

## The 24-hour window and templates

WhatsApp lets you reply freely only within **24 hours** of the customer's last message. After that, the composer explains that WhatsApp only delivers templates approved by Meta, and a **Send a template** button appears. Internal notes still work.

To send a template:

1. Click **Send a template** and pick one from the templates Meta approved for this number.
2. Fill in the variables. The first one is filled with the customer's name, since it usually is the name. Check the **Preview**.
3. Click **Send**. When the customer replies, the 24-hour window opens again.

Create templates and get them approved in Meta's WhatsApp Manager. The list in the Inbox refreshes every 10 minutes and as soon as Meta changes a template's status.

> [!WARNING]
> The Inbox fills text variables in the body only. Templates with a media header, a variable in the header, buttons with variables or copy-code buttons show "Needs a media or variable header, not supported yet" and cannot be sent from Ha Tang.

## Costs

Ha Tang adds no WhatsApp message fees. Conversation fees, if any (for example when you send a template), are billed by Meta directly to your business at WhatsApp's prices.

## Limits

| Item | Limit |
|---|---|
| Free-form replies | Within 24 hours of the customer's last message |
| Text per message | 4,096 characters |
| Caption | One file with a text of up to 1,024 characters goes as one captioned message, as in the WhatsApp app |
| Media received | Up to 10 MB for images, audio and stickers, 25 MB for video and documents; larger media becomes a note |
| Reactions | Not shown in the Inbox |

Ha Tang paces sending per number to stay under WhatsApp's speed limits.

## Access and reconnecting

The access Meta grants for a number lasts 60 days. Ha Tang renews it on its own every day once it is within 10 days of expiring. If renewal fails, or you remove Ha Tang's access in Meta, the number shows **Needs reconnecting**: open its page and click **Reconnect**, which runs the same Facebook flow. See [Reconnect a channel](https://hatang.dev/help/channels/reconnect-channel).

**Disconnect** on the number's page stops new messages from reaching the Inbox. Past conversations are kept, and reconnecting the same number keeps its history. A number can be connected to only one business at a time.

To send WhatsApp conversations to one team, tick **WhatsApp** under a [distribution rule](https://hatang.dev/help/automation/routing-rules)'s **Channels (none ticked = any)**.

## Troubleshooting

| The Inbox says | Cause | What to do |
|---|---|---|
| more than 24 hours have passed since the customer's last WhatsApp message | The window is closed | Send an approved template, or wait for the customer to write again |
| WhatsApp could not deliver to this number | The number is not on WhatsApp, has not accepted the latest terms, or is limited by Meta | Check the number, or reach the customer on another channel |
| Meta refused the template | The template is paused, in the wrong language or missing variables | Check the template's status in WhatsApp Manager and pick another |
| the WhatsApp number is sending too fast | WhatsApp's speed limit | Wait a moment and send again |
| The number shows **Needs reconnecting** | The access was removed or could not be renewed | Click **Reconnect** on the number's page |