> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/channels/channel-types/whatsapp-official.md).

# 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?

{% embed url="<https://www.youtube.com/watch?v=mApSDqLeWcg>" %}

#### 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:

{% embed url="<https://youtu.be/bUV5qWUaOEE>" %}

**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:

{% embed url="<https://youtu.be/c2rE0-aWzyk>" %}

***

### 🔌 Quick Connection Guide

#### In Zaia

1. Go to **Workspace Settings** → **Connections** → **New Connection**
2. Select **WhatsApp (Official)** and give it a name
3. 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**

| Create WhatsApp Account    | Connect Existing App                          |
| -------------------------- | --------------------------------------------- |
| 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

1. Create a **Channel** and link it to your new WhatsApp connection
2. Assign an Agent or Squad
3. **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.

{% hint style="info" %}
This details block appears only for **WhatsApp (Official)** connections.

It does not appear for **WhatsApp (Waha)** or other channel types.
{% endhint %}

***

#### ⚠️ 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:

* [Message Sending Tool](/tools/available-tools/message-sending-tool.md)
* [Message Sending Node](/workflows/workflow-nodes/message-sending-node.md)

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

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

* [Meta WhatsApp API Docs](https://developers.facebook.com/docs/whatsapp)
* [Business Manager Help](https://business.facebook.com/business/help)
* [WhatsApp Business Policy](https://www.whatsapp.com/legal/business-policy)

**Need help?** Contact Zaia support through the in-platform chat.