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
Troubles with WhatsApp connection?
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!
🔎 View connection details
After the connection is created, open Workspace Settings → Connections and check the connection details area.
For WhatsApp (Official) connections, Zaia shows:
Token
Phone Number ID
WABA ID
Each field is read-only.
Each field also has its own copy action.
For tokens longer than 30 characters, Zaia shows the first 30 characters followed by ....
The copy action always copies the complete token.
If a value is empty, Zaia shows Not available and disables copy for that field.
Zaia only displays values already returned by the existing connection.
It does not create, edit, or recalculate these identifiers.
⚠️ 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.
🧩 Templates and outbound messaging
Official WhatsApp supports approved templates for outbound delivery.
In Zaia, this is available in:
Supported send modes
When the connection type is WhatsApp (Official), Zaia can send:
Text
Template
Text with template fallback
With fallback enabled, Zaia tries text first. If Meta rejects the send because the 24-hour window expired, Zaia sends the configured template instead.
⚠️ Fallback only runs for the specific WhatsApp window-expired error. Other delivery errors do not trigger automatic template usage.
Template requirements
Templates only work when:
The connection is active
The connection is correctly configured
The template exists for that WhatsApp account
The template is approved in Meta
Zaia only lists approved templates from the selected connection. It also builds the required fields dynamically from Meta's template schema.
This includes:
Body variables
Header variables
Button variables
Header image input, when applicable
Sending a template from Conversations after the 24-hour window
When an official WhatsApp conversation is blocked because the 24-hour customer-service window has expired, Conversations displays an action to send an approved template from the same blocked composer area.
This action is not shown while free-form messaging is available. It applies only to WhatsApp (Official) conversations.
When the attendant opens the action:
Zaia lists the approved templates available for the connection linked to that conversation.
The attendant selects a template.
Zaia displays every required template field.
The send action remains unavailable until all required values are valid.
The completed template is sent through the same official WhatsApp connection.
After a successful send, the template message appears in the conversation history with its delivery information.
Sending a template does not reopen the free-form 24-hour window. Free-form messaging becomes available again only after the customer sends a new message.
If no approved templates are available, the interface shows an empty state and does not allow sending. If delivery fails, the interface reports the error and the conversation remains blocked.
Workflow vs tool behavior
In the Workflow node, all required template fields must be filled during configuration.
In the Agent tool, template fields can be partially filled. Missing values can be completed at execution time from context, execution data, or the LLM output.
When both sources provide values, Zaia keeps the configured values and fills only the missing ones.
Validations and restrictions
Zaia validates rendered template fields before sending. This includes limits for body, header, OTP, and button URL suffixes.
Templates with image headers accept a public URL, a stored file, or a data URL. Zaia converts the image to the format accepted by the WhatsApp API before sending.
Template metadata is stored in the delivery record for traceability.
In direct chat message sending, templates cannot be sent together with attachments.
✅ 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