WhatsApp (Official)
This connection uses Meta's official WhatsApp Business API, providing a secure, stable, and feature-rich integration for your AI agents.
📹 Video Guides
Understanding WhatsApp Official API
Before connecting, watch this comprehensive guide to understand how the official API works, pricing models, and the two connection approaches available:
Topics covered:
How Meta's portfolio structure works
App + API vs API-only modes
Pricing model (24-hour conversation windows)
Two connection paths: Your portfolio vs Client portfolio
Verification requirements
Common questions answered
Step-by-Step Connection Tutorial
Watch this practical walkthrough showing exactly how to connect WhatsApp through Zaia's interface:
🔌 Quick Connection Guide
In Zaia
Go to Workspace Settings → Connections → New Connection
Select WhatsApp (Official) and give it a name
Click "Connect"
⚠️ Allow pop-ups when prompted - Meta's authentication opens in a new window.
In Meta's Flow
1. Create or Select Portfolio
New portfolio? Fill in: name, email, country, website (or Instagram)
Existing portfolio? Select from dropdown
2. Choose Connection Type
Brand new number
Number already using WhatsApp Business app
Number never used WhatsApp
Keep using app + add automation (coexistence)
3. Add Phone Number
Enter the number with country code
Info must match your WhatsApp Business app (if connecting existing)
4. Verify Number (for existing numbers)
QR Code Method:
You'll receive a message from Facebook Business on WhatsApp
Click "Connect" button in the message
Choose "Don't share conversations"
Scan the QR code
Access Code Method:
Click "Use access code instead"
Enter the code sent to WhatsApp
💡 New accounts: If verification fails, wait 15-30 minutes and try again.
5. Confirm Settings
Select timezone
Review permissions
Click "Confirm" → "Finish"
Back in Zaia
Create a Channel and link it to your new WhatsApp connection
Assign an Agent or Squad
Test by sending a message to your number
✅ Done!
⚠️ Important: New Portfolio Verification
Created a new portfolio during setup? You'll need to verify it within a few hours:
Required docs: Business registration, proof of address
Processing: 2-5 business days
Without verification, connection may be restricted after initial period
🎯 Two Connection Approaches
Your Portfolio (Up to 40 numbers)
Add client numbers to your own Meta Business portfolio.
Best for: Starting out, quick setup, full control Limit: 40 numbers total (2 portfolios × 20 each) Verification: Verify YOUR account once, add all 40 numbers without re-verifying
Client Portfolio (Unlimited)
Client creates portfolio and adds you as admin.
Best for: Scaling beyond 40, formal businesses, client ownership Limit: Unlimited Verification: Each client may need to verify their portfolio (if formal business)
💡 You can create 2 portfolios but be admin on unlimited client portfolios.
📱 App + API vs API-Only
App + API (Coexistence)
Client keeps using WhatsApp Business app + your AI agent responds via API.
When to use: Client wants to keep app access, team needs to respond, IA + human together
API-Only (Exclusive)
Number becomes 100% API. Client cannot use app anymore.
When to use: Full automation, client doesn't need app, dedicated new number
⚠️ Warning: API-only migration is irreversible - number can never return to app mode.
💰 Pricing
Client sends message: FREE
You respond (within 24h): FREE - unlimited replies
You initiate conversation: ~$0.15-0.35 per message (requires template)
✅ Perfect for AI agents! Each client message opens a 24h window for unlimited free responses.
✅ Verification
When Required
New portfolios (within a few hours of creation)
High volume (1,000+ messages/day)
Some advanced features
What You Need
Business documents (CNPJ, registration)
Proof of address
Processing: 2-5 business days
Key Points
Your Portfolio: Verify once → add all 40 numbers
Client Portfolio: Each client verifies their own (if formal business)
Small clients (MEI/PF): Usually don't need immediate verification
⚠️ New portfolios work initially but require verification within hours for continued service.
❓ FAQ
Do I need a Facebook Page? No! Connect directly through Business Manager.
Can I use an existing WhatsApp number? Yes! Choose "Connect existing app" for coexistence mode (App + API).
Will I see previous conversations? No. Only new conversations from connection time forward (Meta API limitation).
Can I switch from API-only back to App+API? No. API-only migration is irreversible.
How much does it cost? Receiving + replying (24h): FREE | Initiating: ~$0.15-0.35/message | Billed by Meta, not Zaia.
When do I need verification? New portfolios need verification within hours. Small clients (MEI/PF) usually don't need immediate verification.
🔧 Troubleshooting
QR Code / Verification Code Fails Wait 15-30 minutes (especially for new accounts) and try alternative method (QR ↔ Code).
Pop-up Blocked Allow pop-ups for Zaia domain. Try Chrome if issues persist.
Connection Works Then Stops Verification required. Check Meta email and verify business in Business Manager.
Messages Not Appearing Ensure: Connection → linked to Channel → Channel has active Agent/Squad → Account verified (if needed).
Can't See Message History Meta API limitation. Only new conversations from connection time forward are visible.
📚 Resources
Need help? Contact Zaia support through the in-platform chat.
Last updated