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. Start the connection

   1. Log in to your AGO Admin panel
   2. Navigate to Settings > Integrations > WhatsApp
   3. Click Connect WhatsApp
2. Sign in and pick your number

   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.
3. Finish the connection

   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. Get Your WhatsApp Business Credentials

   1. Go to the Meta Business Suite
   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
2. Add the Account in AGO

   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., [phone])
      • 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
3. Test the Integration

   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)
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

Common Issues

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

Checking Connection Status

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

Webhook Health

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