> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Send WhatsApp messages, interactive buttons, media, location, and templates from your agents. Ideal for post-call voice-AI follow-up.

# WhatsApp Integration

Give your agents the ability to message customers on WhatsApp Business — not just text and templates, but interactive buttons, PDFs and images, locations, contacts, and list pickers. Perfect for **post-call voice-AI follow-up**: end a call, then WhatsApp the caller a tappable "Confirm appointment" button or send the invoice PDF they just agreed to.

## Connecting WhatsApp

Connection goes through Meta's verified OAuth flow — you do **not** need to register your own Meta Developer app or generate access tokens manually. thinnestAI brokers the OAuth through Composio.

### Step 1: Find your WABA ID

Your WhatsApp Business Account (WABA) ID is a 15-digit number issued by Meta when your business joined WhatsApp Business.

1. Go to [Meta Business Settings](https://business.facebook.com/settings).
2. In the left sidebar, click **Accounts → WhatsApp Accounts**.
3. Select your WhatsApp account — the ID is shown at the top of the page.

> **Not the phone number ID.** Each WABA can own multiple phone numbers. The WABA ID is the parent account; do not paste a phone number or the phone-number ID.

### Step 2: Connect via OAuth

1. Navigate to **Agents** and select your agent.
2. Open the **Tools** section and click **Add Tool**.
3. Select **WhatsApp**.
4. Paste your **WABA ID** into the config modal.
5. Click **Connect WhatsApp**.
6. A Meta sign-in popup opens. Authenticate with the Facebook account that owns the WABA, review the requested permissions, and click **Continue**.

The popup closes automatically when the connection is complete. The modal shows a green **Connected** badge.

### Step 3: Choose Allowed Actions

Six capability toggles control which groups of actions the agent can invoke:

| Toggle                          | Default | What it unlocks                                                |
| ------------------------------- | ------- | -------------------------------------------------------------- |
| **Send Messages**               | ✅ On    | Plain text messages and approved template messages             |
| **Interactive (buttons/lists)** | ✅ On    | Reply buttons ("Yes / No / Maybe") and list pickers            |
| **Media (PDF/image/audio)**     | ✅ On    | Send images, documents, audio, video (by URL or upload)        |
| **Location & Contacts**         | ✅ On    | Send GPS locations and vCard contact cards                     |
| **Manage Templates**            | Off     | Create, delete, and check approval status of message templates |
| **Account Admin**               | Off     | Read business profile and phone numbers on the WABA            |

Leave **Manage Templates** and **Account Admin** off unless the agent specifically needs to administer your WhatsApp account — they expose Meta-level management APIs that most post-call follow-up flows don't need.

## Available Actions

### Messaging (2)

| Action                    | Description                                            |
| ------------------------- | ------------------------------------------------------ |
| **Send Message**          | Send a plain text WhatsApp message to a phone number   |
| **Send Template Message** | Send a Meta-approved template with variables filled in |

### Interactive (2)

| Action                       | Description                                          |
| ---------------------------- | ---------------------------------------------------- |
| **Send Interactive Buttons** | Message with up to 3 tappable reply buttons          |
| **Send Interactive List**    | Message with a tappable list picker (up to 10 items) |

### Media (4)

| Action               | Description                                            |
| -------------------- | ------------------------------------------------------ |
| **Send Media**       | Send an image / PDF / audio / video by URL             |
| **Send Media By ID** | Send a media asset already uploaded to Meta            |
| **Upload Media**     | Upload a file to Meta and get back a reusable media ID |
| **Get Media Info**   | Look up metadata on a previously uploaded media ID     |

### Rich Content (2)

| Action            | Description                                          |
| ----------------- | ---------------------------------------------------- |
| **Send Location** | Share a GPS pin with optional name + address         |
| **Send Contacts** | Share one or more contact cards (name, phone, email) |

### Templates (4) *— opt-in*

| Action                      | Description                                  |
| --------------------------- | -------------------------------------------- |
| **Create Message Template** | Submit a new template to Meta for approval   |
| **Delete Message Template** | Remove an approved or pending template       |
| **Get Message Templates**   | List all templates and their approval status |
| **Get Template Status**     | Check approval status of a specific template |

### Admin (3) *— opt-in*

| Action                   | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| **Get Business Profile** | Read the WABA's public profile (about, address, website) |
| **Get Phone Number**     | Look up metadata on a specific phone number              |
| **Get Phone Numbers**    | List all phone numbers on the WABA                       |

## Voice-AI Use Cases

WhatsApp pairs naturally with the voice tools. After a call ends, the agent can follow up via WhatsApp to confirm outcomes, share files, or collect a structured response — without the user needing to check email.

### Post-Call Appointment Confirmation

```
Agent instructions:
"After a scheduling call ends:
1. Send a WhatsApp message to the caller with interactive buttons:
   - Text: 'Hi {name}, I've tentatively booked {date} at {time}.
            Does that work for you?'
   - Buttons: [Yes, confirm] [Change time] [Cancel]
2. When they tap a button, update the calendar accordingly."
```

### Invoice Delivery

```
Agent instructions:
"When a voice call concludes with a purchase:
1. Generate the invoice PDF
2. Send it via WhatsApp Media to the caller's number
3. Message body: 'Here's your invoice for ₹{amount}. Tap below
   to pay.'
4. Follow with an interactive button: [Pay now]"
```

### Location Sharing for Service Visits

```
Agent instructions:
"When a customer books an on-site appointment:
1. Send a WhatsApp location message with the service address
2. Include arrival window in the accompanying text
3. Send a contact card for the assigned technician"
```

## Example: Appointment-Confirmation Agent

Build a voice agent that confirms bookings via WhatsApp after hangup.

### Agent Setup

| Field | Value                     |
| ----- | ------------------------- |
| Name  | Appointment Confirmer     |
| Model | GPT-4o                    |
| Tools | WhatsApp, Google Calendar |

### Agent Instructions

```
You are a booking confirmation agent. After every voice call where
an appointment is discussed, follow up on WhatsApp.

WORKFLOW:
1. During the call, collect: caller name, preferred date/time, service.
2. Create a tentative calendar event.
3. After hangup, send a WhatsApp interactive-buttons message:
   - Header: "Appointment Request"
   - Body: "Hi {name}, I've pencilled you in for {service} on
           {date} at {time}. Please confirm."
   - Buttons: "Confirm" / "Reschedule" / "Cancel"
4. Wait for the button tap (via a webhook or next conversation).
5. If confirmed → mark calendar event as accepted; send a follow-up
   message with the location as a WhatsApp location pin.
6. If rescheduled → send a list picker with 3 alternative slots.
7. If cancelled → delete the calendar event; acknowledge politely.

RULES:
- Never send WhatsApp messages to numbers the user hasn't called.
- If the call was inbound, the caller's number is auto-detected.
- For outbound, always confirm the number verbally before hangup.
- Use the caller's first name only (never last names in messages).
```

## Combining with Other Tools

| Combination                | Use Case                                                   |
| -------------------------- | ---------------------------------------------------------- |
| WhatsApp + Voice           | Post-call confirmation, invoice delivery, location sharing |
| WhatsApp + Google Calendar | Interactive reschedule flows with button taps              |
| WhatsApp + UPI Payment     | Send a payment link and follow up with "Did you pay?"      |
| WhatsApp + Google Sheets   | Log every outbound WhatsApp + response into a tracker      |
| WhatsApp + Gmail           | Escalate silent WhatsApp leads to email after N days       |

## Template Messages

Plain text messages can only be sent within a **24-hour customer service window** — i.e. within 24 hours of the customer's last message to you. Outside that window, WhatsApp requires a pre-approved **template message**.

* Templates are submitted to Meta for review (usually approved within 24 hours).
* Once approved, the agent fills in the variables (e.g. name, date, amount) and sends.
* Voice-AI follow-up sent within a few minutes of a call almost always falls inside the 24-hour window — plain text works. Reminders sent the next day must use a template.

Enable the **Manage Templates** toggle only if the agent should create or delete templates itself. For sending approved templates, the default **Send Messages** toggle is sufficient.

## Security & Privacy

* **OAuth tokens** are encrypted at rest. thinnestAI never sees your Facebook password.
* **Per-user scoping** — Each user's WABA connection is isolated. One user's agent can never message from another user's WhatsApp account.
* **Revoke access** — Disconnect from the config modal, or revoke directly from [Meta Business Settings → Business Integrations](https://business.facebook.com/settings/business-integrations).
* **Opt-in required** — WhatsApp Business Policy requires the recipient to have opted in to receive business messages. Agents cannot cold-message new numbers outside an active conversation or template.

## Troubleshooting

| Issue                                      | Solution                                                                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Connection failed: WABA ID not found"     | Double-check the ID is from Meta Business Settings → WhatsApp Accounts, not a phone number or phone number ID.                                                                                                |
| "Not authorized" after working for weeks   | Meta's OAuth tokens can be revoked if Business Verification lapses. Re-connect from the config modal.                                                                                                         |
| Messages silently don't arrive             | Recipient may have blocked your WABA, or they're outside the 24-hour window and you sent plain text instead of a template.                                                                                    |
| "Template not approved"                    | Approval takes up to 24 hours. Check status via Manage Templates → Get Template Status, or Meta Business Manager.                                                                                             |
| Interactive buttons don't appear           | Check the recipient's WhatsApp app version — interactive messages require v2.20.197 or newer. Falls back to plain text on old clients.                                                                        |
| Media send fails with "Unsupported format" | WhatsApp accepts specific MIME types per media category (e.g. images: JPG/PNG; docs: PDF/DOC/XLS). Check [Meta's supported types](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-media). |

## Next Steps

* **[Voice](/docs/voice)** — Pair WhatsApp with outbound calling for full post-call workflows.
* **[Google Calendar](/docs/tools/google-calendar)** — Build reschedule flows with tappable buttons.
* **[SMS](/docs/tools/sms)** — Fall back to SMS when the recipient isn't on WhatsApp.