> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Business Integration
> Enable AI-powered WhatsApp Business conversations for your assistants
## What is WhatsApp Business Integration?
WhatsApp Business Integration lets your IllumiChat assistants respond to WhatsApp messages automatically. When someone messages your WhatsApp Business number, your assistant reads the message, generates a helpful response, and sends it back — all over WhatsApp.
Perfect for:
* **Customer support**: Let customers message your business number for instant AI-powered help
* **Lead engagement**: Capture and respond to inbound leads on the channel they already use
* **After-hours coverage**: Provide instant responses even when your team is offline
* **Human handoff**: Hand any conversation to a human agent in the [Universal Inbox](/features/inbox) when needed
WhatsApp Business Integration connects through the **Meta WhatsApp Cloud API**. You can connect with one click using **Embedded Signup**, or paste your own credentials with **Advanced Setup**.
## Getting Started
### Prerequisites
Before connecting WhatsApp, make sure you have:
1. An IllumiChat workspace with **Admin** access
2. A **Meta Business Account**
3. A **WhatsApp Business Account (WABA)**
4. A **registered phone number** for WhatsApp Business
Each WhatsApp phone number can only be connected to **one** assistant at a time. If the number is already connected elsewhere, disconnect it there first.
### 1. Connect Your WhatsApp Business Number
1. Go to your assistant's **Settings**
2. Select **Channels** from the sidebar
3. Click the **WhatsApp** card
4. Review the prerequisites checklist
5. Click **Connect with WhatsApp**
6. Complete the Meta popup — log in to Facebook, choose your WhatsApp Business Account and phone number, and authorize access
IllumiChat will exchange the authorization, discover your WABA and phone number, subscribe the account to webhooks, and store your access token encrypted.
Embedded Signup is the recommended path — it handles token generation and webhook subscription for you. If you don't see the **Connect with WhatsApp** button, your workspace is in manual-only mode and you'll use Advanced Setup below.
### Advanced Setup (manual credentials)
If you manage your own Meta App, expand **Advanced Setup (manual credentials)** and provide:
| Field | Description |
| ---------------------------- | --------------------------------------------------------------- |
| **Phone Number ID** | The Cloud API phone number ID for your WhatsApp Business number |
| **WABA ID** | Your WhatsApp Business Account ID |
| **System User Access Token** | A long-lived System User token with WhatsApp permissions |
| **App Secret** | Your Meta App secret (used to validate incoming webhooks) |
Then click **Connect Manually**. IllumiChat validates the credentials against the Cloud API and stores them encrypted.
With a manual connection, IllumiChat verifies incoming webhooks using **your** App Secret, so each customer's own Meta App can deliver events to the same shared webhook URL.
### 2. Configure Webhooks (manual connections)
Embedded Signup subscribes your account to webhooks automatically — there's nothing extra to do.
If you connected manually, configure the webhook in your **Meta App Dashboard** under the WhatsApp product:
1. On the WhatsApp channel page, copy the **Webhook URL** shown in the **Webhook Setup** card (it ends in `/api/channels/webhook/whatsapp`)
2. In your Meta App Dashboard, paste it as the WhatsApp **Callback URL**
3. Enter your **Verify Token** (this must match the `META_WEBHOOK_VERIFY_TOKEN` configured for your deployment)
4. Subscribe to the **messages** webhook field
The webhook is shared across all WhatsApp connections — you don't need a unique URL per assistant. Incoming events are routed to the right assistant by phone number.
### 3. Configure Messaging Settings
After connecting, fine-tune how conversations are handled from the **Messaging Settings** card:
| Option | Default | Description |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| **AI replies to WhatsApp messages** | On | When off, the AI stops replying on WhatsApp, but conversations still appear in the inbox for manual handling |
| **Match WhatsApp users to existing contacts** | Off | Link incoming messages to contacts with matching phone numbers |
| **Auto-create contacts for new conversations** | Off | Create a contact record for new WhatsApp users (requires contact matching) |
| **Max message length** | 4096 | Maximum characters per message — 1000, 2000, 3000, or 4096; longer responses are split |
Use the **Enabled** toggle at the top of the WhatsApp Integration card to turn the channel on or off without disconnecting. Click **Save Changes** when you're done.
Use **Test** on the connection card at any time to confirm the connection is active and working.
### 4. Test It Out
Send a message to your connected WhatsApp Business number. Within a few seconds, you should receive an AI-generated response.
## How It Works
When someone sends a message to your WhatsApp Business number:
1. **Meta forwards the message** to IllumiChat via the Cloud API webhook
2. **IllumiChat validates** the request using the `X-Hub-Signature-256` header (against the platform App Secret for Embedded Signup, or your own App Secret for manual connections)
3. **A conversation session** is created (or resumed) for that user, keyed to their WhatsApp ID
4. **Your assistant generates a response** if AI is enabled for the channel and the conversation
5. **The response is sent back** via the Cloud API and saved to your chat history
### The 24-Hour Customer Service Window
WhatsApp enforces a strict **24-hour customer service window**. Your assistant (and human agents) can only send free-form messages within 24 hours of the customer's last message. After that window closes, free-form replies are rejected — the customer must message you again to reopen it, **or** you can re-engage using an approved **template message**.
Unlike Messenger, WhatsApp does **not** offer a human-agent tag to extend the window. Outside 24 hours, a pre-approved template is the only way to message a customer.
### Message Templates
Templates are pre-written, Meta-approved messages used for business-initiated conversations and to re-engage customers after the 24-hour window closes. Manage them from the **Message Templates** card on the WhatsApp channel page:
* **View templates** — Each template shows its **status** (Approved, Pending, Rejected, etc.), **category**, and language
* **Create a template** — Click **Create Template**, then provide:
* **Template Name** — lowercase letters, numbers, and underscores only (e.g. `order_confirmation`)
* **Category** — **Utility**, **Marketing**, or **Authentication**
* **Language** — English (US/UK), Spanish, French, or Portuguese (BR)
* **Body Text** — up to 1024 characters
* **Delete a template** — Remove templates you no longer need
New templates are submitted to Meta for review and start as **Pending**. They can only be used once Meta marks them **Approved** — review usually takes a few minutes but can take longer.
## Human Handoff
Human handoff for WhatsApp happens in the **[Universal Inbox](/features/inbox)** — there is no separate WhatsApp agent screen. Your WhatsApp conversations appear in the inbox alongside Messenger, Instagram, and Live Chat, so your team works every channel from one place.
From the inbox you can:
* **Take over AI** on a conversation so the assistant stops replying and you respond manually
* **Claim** a conversation so teammates know you're handling it
* **Reply** directly to the customer over WhatsApp
* **Resume AI** to hand the conversation back to your assistant
* Set an **auto-resume timer** (from 5 minutes up to 7 days) so conversations don't stay in human mode indefinitely
Human replies are still bound by the **24-hour customer service window**. If the window has expired, agent messages from the inbox cannot be sent until the customer messages again. Use an approved template to re-engage outside the window.
For full details on claiming, internal notes, and AI control, see the [Universal Inbox guide](/features/inbox).
## WhatsApp Analytics
Track how your WhatsApp integration is performing from the **WhatsApp Analytics** dashboard on the channel page. Filter by **Last 7 days**, **Last 30 days**, or **Last 90 days**.
### Usage Metrics
* **Total Messages**: Combined inbound and outbound message counts
* **Inbound Messages**: Messages received from users
* **Outbound Messages**: Messages sent by your assistant or human agents
* **Delivered Messages**: Messages confirmed as delivered by Meta
* **Read Messages**: Messages confirmed as read by the recipient
* **Delivery Rate**: Percentage of outbound messages successfully delivered
* **Read Rate**: Percentage of outbound messages read by recipients
### Conversation Metrics
* **Total Conversations**: All WhatsApp conversations
* **Active Conversations**: Conversations with activity in the selected period
* **Human Takeover Count**: Conversations currently in human takeover mode
### Daily Breakdown
View message volume by day to spot trends and peak usage periods, with inbound versus outbound messages over time. The dashboard also lists recent conversations for quick access.
## Admin Configuration
All WhatsApp management requires the **Admin** role in the workspace. Admins can:
* Connect and disconnect WhatsApp Business numbers
* Enable/disable the WhatsApp channel and update messaging settings
* Create, view, and delete message templates
* View analytics and conversation history
* Take over conversations and send messages as a human agent from the inbox
## Best Practices
The one-click flow generates tokens and subscribes webhooks for you, so there's no manual credential management. Reserve Advanced Setup for cases where you run your own Meta App.
Because templates require Meta review, create your common re-engagement messages ahead of time so they're already Approved when the 24-hour window closes on an active conversation.
Use **Utility** for transactional messages (order updates, reminders), **Marketing** for promotions, and **Authentication** for one-time passcodes. Picking the wrong category is a common cause of rejection.
Add WhatsApp-specific guidance to your assistant's system prompt, such as keeping replies concise and conversational, since WhatsApp is a fast, chat-style channel.
The connection card shows your number's quality rating (Green/Yellow/Red). A declining rating can lead to messaging limits — keep responses helpful and avoid spammy template sends.
A low delivery rate may indicate token or quality issues; a low read rate may mean your responses need to be timelier or more engaging.
## Troubleshooting
### Connection failed or shows a connection issue
* Confirm your Meta Business Account, WhatsApp Business Account, and phone number are all set up and the number is registered for WhatsApp Business
* For manual connections, double-check the **Phone Number ID**, **WABA ID**, **System User Access Token**, and **App Secret** — an invalid or expired token is the most common cause
* If the connection card shows a **Connection issue**, **Disconnect** and reconnect to re-authorize
* Use the **Test** button to re-check that the connection is active
### Phone number already connected
Each WhatsApp number can only be connected to one assistant. Disconnect it from the other assistant before connecting it here.
### Not receiving messages
* Verify the WhatsApp channel is **Enabled** and the connection status is active
* For manual connections, confirm the **Webhook URL** is set in your Meta App Dashboard with the correct **Verify Token**, and that the **messages** field is subscribed
* Ensure the phone number is properly registered on the Cloud API
### Can't send a message — window expired
If you see an error that the messaging window has expired, more than 24 hours have passed since the customer's last message. WhatsApp does not allow free-form replies after this window. Wait for the customer to message again, or re-engage with an approved template.
### Template rejected or stuck pending
* Templates must be **Approved** by Meta before use; freshly created templates start as **Pending**
* A **Rejected** status usually means the content or category violates WhatsApp's policies — review Meta's feedback, fix the body text or category, and recreate it
* Template names must use lowercase letters, numbers, and underscores only
Contact support for WhatsApp setup assistance