Overview
This integration allows you to:
Send personalized WhatsApp messages to contacts in your Clay table
Automate outreach workflows triggered by data enrichment
Track message delivery with unique message IDs
Organize conversations with automatic labeling
Time to set up: 5-10 minutes
Prerequisites
Before you begin, make sure you have:
An active TimelinesAI account with at least one WhatsApp number connected
A Clay account with an existing table containing phone numbers
Your TimelinesAI API key (we'll show you where to find this)
Step 1: Get Your TimelinesAI API Key
Log in to your TimelinesAI account
Navigate to Integrations → Public API
Copy your API token
🔒 Keep this key secure. Treat it like a password—don't share it publicly.
Step 2: Add an HTTP API Column in Clay
Open your Clay table containing the contacts you want to message
Click + Add Column
On "add enrichment" search for "whatsapp"
Select HTTP API from the results
Step 3: Configure the API Request
A configuration panel will appear. Fill in the following settings:
Basic Settings
Setting | Value |
Method |
|
URL |
|
📸 Screenshot 3: Clay HTTP API configuration panel showing Method and URL fields
Headers
Add two headers by clicking + Add Header:
Header Key | Header Value |
|
|
|
|
⚠️ Important: Include the word Bearer followed by a space before your API key.
Step 4: Configure the Request Body
This is where you map your Clay columns to the WhatsApp message.
Scroll to the Body section
Select Raw or JSON mode
Paste the appropriate JSON structure (see options below)
Option A: Basic Setup (Recommended for Most Users)
Use this if you have one WhatsApp account or want the simplest setup:
json
{ "phone": "", "text": "" }Required columns:
Phone Number — Recipient's phone in international format
Message Text — The message you want to send
Option B: Advanced Setup
Use this if you have multiple WhatsApp accounts in your workspace or want to auto-label conversations:
json
{ "phone": "", "text": "", "whatsapp_account_phone": "", "label": "" }Additional columns:
Sender WhatsApp Number — Which team member's WhatsApp sends the message
Label — Auto-tag the conversation (e.g., "Clay Lead")
Step 5: Map Your Columns
For each field in the JSON body:
Place your cursor inside the empty quotes
""Type
/or click the + iconSelect the corresponding column from your table
Example mapping:
JSON Field | Maps To |
| Your phone number column |
| Your message content column |
Step 6: Set Up Response Handling (Optional)
To capture the message ID for tracking:
Find the Results Path or Output section
Enter:
data.message_uid
This stores the unique message identifier in your Clay table.
Step 7: Test Your Integration
Click Save and Run or Run for first 10 rows
Check the new HTTP API column for results
Verify in TimelinesAI that the message was sent
Success Indicators
✅ Column shows 200 status code
✅ Response contains "status": "ok"
✅ Message appears in your TimelinesAI inbox
✅ Recipient receives the WhatsApp message
Field Reference
Required Fields
Field | Format | Description |
|
| Recipient's phone number in international format |
| Any text | Message content. Use |
Optional Fields
Field | Format | Description |
|
| Sender's WhatsApp number (for multi-user workspaces) |
| Any text | Auto-apply a label to the conversation |
Phone Number Format
Phone numbers must be in international format:
+[country code][area code][local number]
Examples:
Country | Format |
United States |
|
United Kingdom |
|
Germany |
|
Brazil |
|
Troubleshooting
Common Errors
Error | Cause | Solution |
401 Unauthorized | Invalid API key | Check that you included |
400 Bad Request | Invalid phone format | Ensure phone number includes country code (e.g., |
403 Forbidden | Quota exceeded | Check your TimelinesAI plan message limits |
404 Not Found | Wrong URL | Verify the URL is exactly |
Message Not Received?
Check the phone format — Must include country code
Verify WhatsApp account is connected — Go to TimelinesAI → WhatsApp Accounts
Check message quota — Ensure you have available message credits
Wait a moment — Messages are sent with ~2 second delays to avoid spam detection
Good to Know
Message Credits
Sending a text message uses 1 credit
Sending a message with an attachment uses 2 credits
Failed messages have credits restored automatically
Rate Limiting
Messages are sent with a small delay (~2 seconds) between each to comply with WhatsApp's guidelines and avoid spam detection.
Multi-User Workspaces
If your workspace has multiple team members with connected WhatsApp accounts:
Leave
whatsapp_account_phoneempty to use the default (most recently connected) accountSpecify the phone number to route messages through a specific team member's WhatsApp
Example Use Cases
Lead Outreach
Send personalized welcome messages to new leads as they're added to your Clay table.
json
{ "phone": "{{Lead Phone}}", "text": "Hi {{First Name}}, thanks for your interest in {{Company}}! I'd love to chat about how we can help. When works best for a quick call?", "label": "Clay Lead" }Follow-Up Sequences
Trigger follow-up messages based on enrichment data or time delays.
Event Reminders
Send WhatsApp reminders to webinar or meeting registrants.
Need Help?
TimelinesAI Support: [email protected]
API Documentation: TimelinesAI Public API
Clay Help Center: Clay Documentation