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

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

Testing with Sandbox

1. Go to Twilio WhatsApp Sandbox
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