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

> Deploy your thinnestAI agent to WhatsApp via Twilio for instant messaging with automatic lead capture.

# WhatsApp

Connect your agent to WhatsApp so users can message it directly from their phone. Uses Twilio as the messaging provider, supporting both the WhatsApp Business API and the Twilio Sandbox for testing.

## Prerequisites

* A [Twilio account](https://www.twilio.com/try-twilio) (free trial works for testing)
* A Twilio phone number with WhatsApp enabled, or the Twilio WhatsApp Sandbox
* Your agent created and tested in thinnestAI

## Setup

### Step 1: Get Twilio Credentials

1. Log in to [Twilio Console](https://console.twilio.com/)
2. Copy your **Account SID** and **Auth Token** from the dashboard

### Step 2: Configure Your Agent

1. Open your agent in thinnestAI
2. Go to the **Deploy** tab
3. Select **WhatsApp**
4. Enter your Twilio credentials:
   * **Account SID** — Your Twilio Account SID
   * **Auth Token** — Your Twilio Auth Token
   * **Phone Number** — Your Twilio WhatsApp number (e.g., `+14155238886` for sandbox)
5. Click **Save & Enable**

### Step 3: Set the Webhook URL

1. In Twilio Console, go to **Messaging > Try it out > Send a WhatsApp message** (for sandbox) or your WhatsApp sender configuration
2. Set the webhook URL to:

```
https://api.thinnest.ai/webhooks/twilio/YOUR_AGENT_ID
```

3. Set the HTTP method to **POST**

### Step 4: Test It

* **Sandbox**: Send the join code shown in Twilio to `+1 415 523 8886` via WhatsApp
* **Production**: Message your WhatsApp Business number directly

Send a message — your agent should respond within seconds.

## How It Works

```
User sends WhatsApp message
        ↓
Twilio forwards to /webhooks/twilio/{agent_id}
        ↓
thinnestAI verifies Twilio signature (security)
        ↓
Extracts sender phone number → auto-captures lead
        ↓
Routes message to your agent (GraphExecutor)
        ↓
Agent responds → Twilio delivers to WhatsApp
```

### Session Persistence

Each phone number gets its own conversation session with your agent. When a user messages again, the agent remembers the full conversation history.

Session ID format: `twilio_{agent_id}_{phone_number}`

### Automatic Lead Capture

Every WhatsApp user is automatically captured as a lead with:

* **Phone number** from the sender's WhatsApp number
* **Platform**: `whatsapp`
* **Deduplication**: One lead per phone number per agent (no duplicates)

Leads appear in your **Leads** dashboard, filterable by the WhatsApp platform tab.

## Message Limits

WhatsApp/Twilio has these constraints:

| Limit              | Value                            |
| ------------------ | -------------------------------- |
| Max message length | 1,600 characters                 |
| Media support      | Not yet (text only)              |
| Message window     | 24 hours after last user message |

Messages longer than 1,500 characters are automatically truncated with `...`.

## Security

* **Signature verification**: Every incoming webhook is verified using the `X-Twilio-Signature` header and your Auth Token
* **Credentials encrypted**: Your Twilio credentials are encrypted at rest in the database
* **No plaintext storage**: Auth tokens are never stored in plaintext

## Sandbox vs Production

| Feature           | Sandbox                  | Production                      |
| ----------------- | ------------------------ | ------------------------------- |
| Cost              | Free                     | Per-message pricing             |
| Phone number      | Shared (+1 415 523 8886) | Your own number                 |
| Join code         | Required for each user   | Not needed                      |
| Message templates | Not required             | Required for business-initiated |
| Approval          | None                     | WhatsApp Business API approval  |

## Testing with Sandbox

1. Go to [Twilio WhatsApp Sandbox](https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn)
2. Follow the "join" instructions to connect your phone
3. Send a test message — your agent should respond
4. Check the **Leads** dashboard for the auto-captured lead

## Troubleshooting

| Issue                   | Solution                                                |
| ----------------------- | ------------------------------------------------------- |
| No response             | Check webhook URL is correct and agent is enabled       |
| "WhatsApp not enabled"  | Enable WhatsApp in agent Deploy settings                |
| "Unauthorized"          | Verify Auth Token matches Twilio console                |
| Delayed responses       | Check agent execution time — complex agents may be slow |
| Messages not delivering | Verify Twilio account has credit/active trial           |