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

Log in to Twilio Console
Copy your Account SID and Auth Token from the dashboard

Step 2: Configure Your Agent

Open your agent in thinnestAI
Go to the Deploy tab
Select WhatsApp
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)
Click Save & Enable

Step 3: Set the Webhook URL

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

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

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

Go to Twilio WhatsApp Sandbox
Follow the “join” instructions to connect your phone
Send a test message — your agent should respond
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

​WhatsApp

​Prerequisites

​Setup

​Step 1: Get Twilio Credentials

​Step 2: Configure Your Agent

​Step 3: Set the Webhook URL

​Step 4: Test It

​How It Works

​Session Persistence

​Automatic Lead Capture

​Message Limits

​Security

​Sandbox vs Production

​Testing with Sandbox

​Troubleshooting