> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Business
> Connect AGO agents with WhatsApp for customer interactions
This documentation describes the WhatsApp Business integration with AGO, allowing your customers to interact with AGO agents directly from WhatsApp.
## Overview
The WhatsApp Business integration supports:
* Receiving messages from WhatsApp Business accounts
* Message processing by AGO agents
* Text messages with support for long responses (auto-split at 4096 characters)
* Media messages (images, documents, audio, video)
* Location sharing
* Secure webhook validation with HMAC-SHA256
## Prerequisites
Before setting up the integration, you need:
1. **Meta Business Account**: A verified Meta Business account
2. **WhatsApp Business Platform Access**: Access to the WhatsApp Business Platform through Meta
3. **System User**: A System User with appropriate permissions for the WhatsApp Business Account
4. **Phone Number**: A phone number registered with WhatsApp Business Platform
## Setup Guide
There are two ways to connect a WhatsApp number. **Connect WhatsApp** is the recommended path: you sign in to Facebook in a popup and AGO collects the credentials for you. Manual setup is still available for cases where you already hold a System User token.
### Connect WhatsApp (recommended)
1. Log in to your AGO Admin panel
2. Navigate to **Settings > Integrations > WhatsApp**
3. Click **Connect WhatsApp**
1. A Facebook popup opens. Sign in with the account that manages your business.
2. Select or create your Meta Business and WhatsApp Business Account.
3. Pick or add the phone number you want to connect and verify it.
4. The popup closes and returns you to AGO.
1. Enter the 6-digit **PIN** used for WhatsApp two-step verification on that number.
2. Optionally choose an **Assigned Agent** to handle messages for this number.
3. Click **Finish connection**.
AGO exchanges the sign-in for credentials, registers the number, and subscribes to message webhooks automatically. The connected number then appears in the list with a status badge.
During the Facebook popup, the business adds its own payment method in WhatsApp Manager. Meta bills WhatsApp conversation usage directly to that business — AGO only bills for the AGO subscription.
### Manual setup (fallback)
Use this when you already have a System User access token and prefer to enter credentials by hand.
1. Go to the [Meta Business Suite](https://business.facebook.com/)
2. Navigate to **WhatsApp Manager**
3. Select your WhatsApp Business Account
4. Note down the following:
* **Phone Number ID**: Found in the phone number settings
* **WhatsApp Business Account ID (WABA ID)**: Found in the account settings
* **Access Token**: Generate a System User Access Token with `whatsapp_business_messaging` and `whatsapp_business_management` permissions
1. Log in to your AGO Admin panel
2. Navigate to **Settings > Integrations > WhatsApp**
3. Expand **Advanced: manual setup** and click **Add Account**
4. Fill in the required fields:
* **Phone Number ID**: Your WhatsApp Phone Number ID
* **WhatsApp Business Account ID**: Your WABA ID
* **Access Token**: Your System User Access Token
* **Phone Number**: The phone number (e.g., +1234567890)
* **Display Name** (Optional): A friendly name for the account
* **Assigned Agent** (Optional): Select a specific agent to handle messages
5. Click **Add Account**
6. The system will automatically test the connection
1. In the AGO Admin panel, find your connected account
2. Click **Test** to verify the connection
3. If successful, you'll see the phone number details and quality rating
4. Send a test message from WhatsApp to your business number
## Supported Message Types
### Incoming Messages (From Users)
| Type | Description |
| -------- | ------------------------------------------------------------------------------------------- |
| Text | Plain text messages |
| Image | Photos with optional captions |
| Document | Files (PDF, Word, Excel, etc.) |
| Audio | Voice messages and audio files (transcribed to text, see [Voice messages](#voice-messages)) |
| Video | Video messages with optional captions |
| Location | Shared locations with coordinates |
| Sticker | Sticker images |
| Contacts | Shared contact cards |
### Outgoing Messages (From AGO)
| Type | Description |
| -------- | ------------------------------------------------------------- |
| Text | Plain text up to 4096 characters (longer messages auto-split) |
| Image | Images via URL with optional caption |
| Document | Documents via URL with filename |
| Audio | Audio files via URL |
## Features
### Long Message Handling
WhatsApp has a 4096 character limit per message. AGO automatically splits longer responses intelligently:
* Prioritizes splitting at paragraph breaks
* Falls back to sentence endings
* Then word boundaries
* Small pause (0.5s) between split messages
### Agent Assignment
You can assign specific agents to each WhatsApp account:
* Messages are routed to the assigned agent
* If no agent is assigned, the default agent handles messages
* Change agent assignments anytime in the admin panel
### Voice messages
When a user sends a voice message, AGO transcribes the recording to text and the assigned agent answers it like any typed message, using its knowledge and tools. The reply comes back as text. Transcription detects the spoken language automatically, so users can record in their own language. In the conversation view, transcribed voice messages are marked with a 🎤 so you can tell them apart from typed messages.
If a recording can't be transcribed (for example, no speech is detected), the agent still receives a short placeholder and responds normally.
### Message Queuing
When users send multiple messages rapidly (within 2 seconds), AGO:
* Queues the messages
* Merges them into a single request
* Provides a unified response
This prevents fragmented conversations and improves response quality.
## Troubleshooting
**Connection Test Failed: Invalid Access Token**
* Verify your access token has not expired
* Ensure the token has `whatsapp_business_messaging` permission
* Generate a new token if necessary
**Messages Not Being Processed**
* Check that the account is marked as "Connected" in AGO
* Verify the Phone Number ID is correct
**Duplicate Messages**
* AGO automatically deduplicates messages within a 1-hour window
* If you see duplicates, check if you have multiple webhook subscriptions
1. Go to **Settings > Integrations > WhatsApp**
2. Check the status badge on each account:
* **Connected**: Account is working
* **Connection Failed**: See error details
* **Not Tested**: Click Test to verify
The integration displays webhook status:
* **Webhook Active**: Webhook is properly configured
* **Webhook Inactive**: Check Meta webhook configuration
## Security
The WhatsApp integration includes several security measures:
* **Webhook Signature Validation**: All incoming webhooks are validated using HMAC-SHA256
* **Encrypted Token Storage**: Access tokens are encrypted at rest
* **Verify Token Protection**: Webhook verification uses a separate token
## Limitations
* Only one account can use each Phone Number ID (unique constraint)
* Media uploads require publicly accessible URLs
* Interactive message templates are not currently supported
* Template messages require separate configuration in Meta
## Support
If you encounter issues:
1. Check the troubleshooting section above
2. Contact support with your account details and error messages