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

{% 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!

***

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

* [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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zaia.app/channels/channel-types/whatsapp-official.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.