WhatsApp Integration Guide

Learn how to integrate your Agent5ive agents with WhatsApp for business messaging.

Multimodal Support (Images & Voice)NEW

Agents can now process incoming images and voice messages along with text via WhatsApp. Vision-enabled agents will analyze images, and all agents can transcribe and respond to voice messages. Responses are always delivered as text.

Integration Availability

WhatsApp Business integration is available for all users. Explorer tier users can connect 1 agent to WhatsApp, while Pro subscription users can connect unlimited agents.

Explorer Tier

Explorer tier users can connect 1 agent to WhatsApp.

Pro Tier

Pro tier users can connect unlimited agents to WhatsApp.

Overview

Agent5ive offers two ways to connect your agents to WhatsApp, each designed for different use cases and setup requirements:

Multimodal Capabilities (Images & Voice)

WhatsApp integration now supports multimodal interactions. Agents with vision enabled can receive and process images sent by users. Additionally, all agents can process voice messages - the audio is transcribed and your agent responds in text.

Note: If your agent does not have vision capabilities enabled, users will receive a notification that image processing is not supported. Voice messages are supported for all agents.

Instant WhatsApp Chat (via Twilio)

The quickest way to get started with zero setup. Connect your agent to WhatsApp in 1 minute using our Twilio-powered sandbox.

Zero configuration required
Connect from any phone number
Test and demo immediately
Perfect for testing and self-use

Business API Integration

Production-ready solution using your own WhatsApp Business number with full control and customization.

Your own business phone number
Custom branding and profile
Production-grade reliability
Full API control and features
Requires Meta Business setup

Choosing the Right Method

Use Instant WhatsApp Chat for quick testing, demos, and prototyping. Switch to Business API when you're ready for production with your own branded WhatsApp Business number.

Integration Methods

Choose the integration method that best fits your needs. You can start with Instant WhatsApp Chat for immediate testing and switch to Business API for production.

Instant WhatsApp Chat (Twilio Sandbox)

Get started with WhatsApp in under 1 minute. The Instant WhatsApp Chat integration uses Twilio's sandbox environment to connect your agent to WhatsApp without any setup or configuration. Perfect for testing, demos, and quick prototypes.

Zero Setup Required

No API keys, no business accounts, no webhooks. Just scan a QR code or click a button to start chatting with your agent on WhatsApp.

Step 1: Join Twilio Sandbox

First, you need to join the Twilio WhatsApp Sandbox by scanning the QR code or clicking the button. This connects your WhatsApp account to the sandbox environment.

QR Code will appear here

Scan the QR code or click the "Join Sandbox via WhatsApp" button when setting up your integration

Important

You'll need to send a specific message (e.g., "join consonant-acres") to the Twilio number to complete the sandbox registration. Follow the on-screen instructions carefully.

Step 2: Connect to Your Agent

After joining the sandbox, scan the second QR code or click the button to route messages to your specific agent. This links your WhatsApp sandbox session to your Agent5ive agent.

QR Code will appear here

Scan the QR code or click the "Connect this agent on WhatsApp" button to link your agent

Step 3: Start Chatting

That's it! You can now send messages to your agent via WhatsApp. All messages will be routed through the Twilio sandbox to your agent.

You're Connected!

Start sending messages to your WhatsApp agent. The connection will remain active as long as you stay connected to the Twilio sandbox.

Sandbox Limitations

The Twilio sandbox is designed for testing and development. For production use with your own WhatsApp Business number, use the Business API integration method below. The sandbox may have message rate limits and is shared with other users.

Integration Checklist

Use this checklist to ensure you've completed all the necessary steps for the WhatsApp integration:

Create a Meta Business Account and WhatsApp Business Account
Register as a Meta Developer and create a Meta App
Create a System User in Meta Business Platform
Assign WhatsApp Business Account to System User
Generate Access Token with WhatsApp Business API permissions
Get WhatsApp Business Account ID and Phone Number ID
Enter WhatsApp Business API Credentials in Agent5ive
Get Webhook URL and Verify Token from Agent5ive
Configure Webhooks in Meta Developer Platform
Subscribe to Webhook Fields in Meta Developer Platform
Verify the Connection with a test message

Best Practices

Conversation Best Practices

Keep messages concise and mobile-friendly
Use clear, action-oriented language
Provide structured options when possible
Handle multi-turn conversations gracefully

Multimodal Best Practices (Images & Voice)

Enable vision on your agent if you expect users to send images
Instruct your agent (via system prompt) on how to handle visual content
Provide fallback responses for non-vision agents receiving images
Consider image-based use cases in your agent's knowledge base
Voice messages are automatically transcribed - agents respond in text only
Consider that voice transcriptions may contain minor inaccuracies
Design your agent to handle conversational voice input gracefully

Troubleshooting

Common Issues and Solutions

Webhook Verification Fails

Double-check that the webhook URL and verify token are correctly copied from Agent5ive
Ensure your Agent5ive subscription is active
Verify that your agent is publicly deployed

Messages Not Being Received

Confirm you've subscribed to the "messages" webhook field
Check that your access token has the necessary permissions
Verify that your WhatsApp Business account is active and in good standing

Agent Not Responding to Messages

Check that your agent is properly deployed and online
Verify the connection between Agent5ive and WhatsApp
Ensure your agent has the necessary capabilities to handle the incoming queries

Image Processing Issues

Images Not Being Processed

Verify that your agent has vision capabilities enabled
Ensure your agent is using a vision-capable model (e.g., Gemini Flash)
Check that the image was sent correctly through WhatsApp
Redeploy your agent after enabling vision in Edit Details

User Receives "Images Not Supported" Message

This means your agent does not have vision enabled
Enable "Image Upload & Vision" in your agent's Edit Details
Redeploy the agent and reconnect to WhatsApp if needed

Voice Messages Not Processing

Ensure your agent is properly deployed and connected to WhatsApp
Voice messages are transcribed server-side before being sent to your agent
If transcription fails, check that the audio file was sent correctly
Note: Agents always respond to voice messages with text, not audio

Need Help?

If you encounter issues setting up the WhatsApp Business integration, please contact our support team at sales@agent5ive.com.

Meta Platform Resources

The following official Meta resources will help you navigate the WhatsApp Business API integration process:

Meta Business Suite

Manage your business presence across Meta apps, including WhatsApp Business.

Access Business Suite

Meta for Developers

Access developer tools, APIs, and documentation for Meta platforms.

Access Developer Portal

WhatsApp Business Platform

Official documentation for the WhatsApp Business API and platform.

View Documentation

WhatsApp Cloud API

Specific documentation for the WhatsApp Cloud API used in this integration.

View API Documentation

WhatsApp Business Management API

API for managing WhatsApp Business accounts and phone numbers.

View Management API

Meta Business Help Center

Get help with Meta Business products and services.

Access Help Center

Explore Embedding Explore Telegram Integration

Documentation

Guides

Tutorials

Help