# WhatsApp Integration
Connect your Chipp AI app to WhatsApp and let users chat with your AI through WhatsApp messaging.
---
Deploy your Chipp AI app to WhatsApp and let users interact with your AI directly through WhatsApp messaging.
## Prerequisites
Before you begin, you'll need:
- A Chipp application ready to deploy
- A [Meta Developer Account](https://developers.facebook.com/)
- A phone number to associate with your WhatsApp Business account
## Setup Instructions
**1.**
Create a Meta App
Log in to the [Meta Developer Platform](https://developers.facebook.com) and create a new app:
1. Click **Create App**
2. Select **Business** as the app type
3. Fill in your app details
4. Navigate to **WhatsApp** in the sidebar and click **Quick Start**
5. Select **Get Started with the API** and click **Start using the API**
**2.**
Open WhatsApp Configuration in Chipp
Go to your Chipp application and open **Launch > Share**. Select the **Deploy** tab and click the **WhatsApp** card. The dialog walks you through three steps: **Create App**, **Webhook**, and **Credentials**. After you create your Meta app, click **I've created my app**.
**3.**
Copy the Callback URL
The **Webhook** step shows your **Callback URL**. Copy it, then click **Continue**. The Verify Token is generated after you save your credentials, so you finish the webhook in Meta in step 5.
**4.**
Enter Your Meta Credentials
From the Meta Developer Platform, copy these values into the Chipp dialog, then click **Save Configuration**:
- **Phone Number ID**: A 15-16 digit ID found in **WhatsApp > API Setup**
- **WhatsApp Business Account ID**: A 15-16 digit ID found in **WhatsApp > API Setup**
- **Permanent Access Token**: Your WhatsApp API access token (at least 32 characters). Use a System User token for production.
- **App Secret**: The 32-character secret in **App Settings > Basic**. Chipp uses it to check that every incoming message really comes from Meta.
**5.**
Configure the Webhook in Meta
After saving, the dialog shows **WhatsApp Connected** with your **Callback URL** and **Verify Token**.
1. In the Meta Developer Platform, go to **WhatsApp** > **Configuration**
2. Paste the Callback URL into Meta's **Callback URL** field
3. Copy the **Verify Token** from Chipp and paste it into Meta's **Verify Token** field
4. Click **Verify and Save**
**6.**
Subscribe to Messages
In the Meta Developer Platform webhook configuration:
1. Scroll down to find the **Webhook fields** section
2. Find **messages** and click **Subscribe**
3. This allows your app to receive incoming WhatsApp messages
**7.**
Test Your Connection
1. Use the test WhatsApp number provided by Meta
2. Send a test message like "Hello"
3. Verify that your Chipp AI responds automatically
## Going Live
When you're ready for production:
1. In the Meta Developer Platform, switch your app from **Development** to **Live Mode**
2. Complete the required business verification
3. Request the `whatsapp_business_messaging` permission
4. Add a production phone number
> **Warning:** Development mode limits you to messaging with registered test numbers only. You must go live to message any WhatsApp user.
## Managing Your Connection
### Disconnect WhatsApp
To disconnect your WhatsApp integration:
1. Go to **Launch > Share** > **Deploy** and click the **WhatsApp** card
2. Click **Disconnect** at the bottom of the dialog
3. Click **Yes, Disconnect** to confirm
### Add Your App Secret
Connections saved before Chipp asked for the App Secret show an **Add your App Secret** card in the connected dialog. Until you add it, Chipp cannot check that incoming messages really come from Meta.
1. Go to **Launch > Share** > **Deploy** and click the **WhatsApp** card
2. In your Meta app, open **App Settings > Basic** and copy the **App Secret**
3. Paste it into the card and click **Save App Secret**
Chipp checks the secret with Meta before it saves it, so a wrong secret is refused and your agent keeps running as before. You do not need to re-enter your other credentials or change the webhook.
### Update Credentials
The connected dialog has no credential editor. To update your Access Token or other credentials:
1. Disconnect WhatsApp as above
2. Run the setup again and enter the new values
3. Click **Save Configuration**, then paste the new Verify Token into Meta
## Best Practices
### Response Time
WhatsApp expects responses within 24 hours of the user's last message. After that, you'll need to use approved message templates for proactive outreach.
### Message Templates
For proactive messaging (reaching out first), create message templates in the Meta Business Suite and get them approved before use.
### Rate Limits
Be aware of WhatsApp's rate limits:
- **Tier 1**: 1,000 unique users per 24 hours
- **Tier 2**: 10,000 unique users per 24 hours
- **Tier 3**: 100,000 unique users per 24 hours
You can increase your tier by maintaining good quality ratings.
## Troubleshooting
### Messages Not Being Received
1. Verify the Callback URL is correct in Meta
2. Check that the **messages** webhook is subscribed
3. Ensure your app is in Live mode (or using test numbers in Development)
4. Verify all three credentials are valid (Access Token, Phone Number ID, Business Account ID)
### Webhook Verification Failed
1. Double-check the Verify Token matches exactly
2. Ensure your Chipp app is published and running
3. Try re-copying the Callback URL from Chipp
### AI Not Responding
1. Check your Chipp app is active
2. Verify your AI model is configured correctly
3. Check the chat history in Chipp's **Chats** page for any errors
### AI Stops Answering Another Bot
Sometimes the number on the other side is a bot too, for example a store's menu assistant. Each reply from your agent makes that bot send its menu again, and the two bots talk to each other without end. Every one of those messages is a billed turn.
Chipp stops this on its own. When the same message keeps arriving (five or more times in one hour, in a busy thread), your agent saves it in the chat history but does not reply. A new or different message, such as a person who joins the chat, still gets an answer.
### Invalid Credentials Error
- **Access Token**: Must be at least 32 characters
- **Phone Number ID**: Must be 15-16 digits
- **Business Account ID**: Must be 15-16 digits
## Pricing
WhatsApp Business API pricing is based on conversation types:
- **User-initiated conversations**: Lower cost per conversation
- **Business-initiated conversations**: Higher cost per conversation
Prices vary by country. Check [Meta's pricing page](https://developers.facebook.com/docs/whatsapp/pricing) for current rates.
## Using with MCP
You can check WhatsApp deployment status programmatically using the Chipp MCP Server.
### Available Tools
| Tool | Description |
|------|-------------|
| `get_whatsapp_deployment` | Get WhatsApp business configuration |
### Example Prompts
```
"Is my app connected to WhatsApp?"
"Show me the WhatsApp configuration for my support bot"
"What's the status of my WhatsApp deployment?"
```
### Workflow: Deployment Status
```
You: Check the WhatsApp status for my support bot
AI: [Calls get_whatsapp_deployment]
WhatsApp Deployment:
- Status: Connected
- Phone Number ID: 123456789012345
- Business Account ID: 1234567890123456
- Mode: Production
- Last message received: 1 hour ago
```
> **Note:** MCP server access requires a Studio plan or higher. See the [MCP Setup Guide](/docs/guides/mcp/setup) to get started.