Public API
The TimelinesAI Public API gives you full control over your WhatsApp conversation resources. Send and receive messages, manage conversations, handle file attachments, organize chats with labels, and set up real-time webhooks — all through a simple REST APIBase URL
Capabilities
Messages
Send text messages, attachments, and voice notes to any WhatsApp number. Track delivery status from queued through read.
Chats
List, filter, and update conversations. Assign chats to team members, close/reopen, and manage read status.
Files
Upload files from URLs or directly. Send images, PDFs, audio, and video as WhatsApp attachments.
Labels
Organize chats with labels. Add, replace, or list labels to categorize and filter conversations.
Reactions
Get and update emoji reactions on messages.
Webhooks
Subscribe to real-time events like new messages, sent messages, and chat updates.
WhatsApp Accounts
List all connected WhatsApp numbers in your workspace.
Quotas & Usage
Monitor your messaging quota, API call limits, and current utilization.
Available endpoints
| Group | Endpoints | Description |
|---|---|---|
| Chats | GET /chats, GET /chats/{id}, PATCH /chats/{id} | List, get details, and update chats |
| Messages | POST /messages, POST /chats/{id}/messages, GET /chats/{id}/messages, and more | Send messages by phone, chat ID, JID, or chat name. Retrieve history and status. |
| Reactions | GET /messages/{uid}/reactions, PUT /messages/{uid}/reactions | Read and update message reactions |
| Files | GET /files, POST /files, POST /files_upload, GET /files/{uid}, DELETE /files/{uid} | Upload, list, download, and delete files |
| Labels | GET /chats/{id}/labels, PUT /chats/{id}/labels, POST /chats/{id}/labels | List, add, and replace chat labels |
| WhatsApp Accounts | GET /whatsapp_accounts | List connected WhatsApp numbers |
| Teammates | GET /teammates | List workspace team members |
| Quotas & Usage | GET /quotas | Check quota limits and current usage |
| Webhooks | GET /webhooks, POST /webhooks, GET/PUT/DELETE /webhooks/{id} | Manage webhook subscriptions |
Use case examples
CRM integration
CRM integration
Sync WhatsApp conversations with your CRM. When a new lead messages you, automatically create a contact in your CRM and assign the chat to the right sales rep.
- Set up a webhook for
message:received:new - On new message, check if the phone number exists in your CRM
- Create or update the CRM contact
- Use
PATCH /chats/{id}to assign the chat to the appropriate agent - Add a label like
crm-syncedfor tracking
Automated notifications
Automated notifications
Send order updates, appointment reminders, or shipping notifications directly to WhatsApp.
- Use
POST /messageswith the customer’s phone number - Include relevant details in the message text
- Attach documents (invoices, receipts) using the file upload endpoints
- Track delivery with
GET /messages/{uid}/status_history
Support ticket system
Support ticket system
Route incoming WhatsApp messages to your support team based on content or labels.
- Listen for new messages via webhooks
- Parse the message content to determine the category
- Add appropriate labels with
PUT /chats/{id}/labels - Assign to the right agent with
PATCH /chats/{id} - Add internal notes with
POST /chats/{id}/notesfor context
Bulk outreach campaigns
Bulk outreach campaigns
Send personalized messages to a list of contacts for marketing or onboarding campaigns.
- Iterate over your contact list
- Use
POST /messagesfor each recipient with personalized text - Auto-apply labels (e.g.,
campaign-jan-2025) when sending - Respect the ~2 second rate limit between messages
- Monitor delivery status and quota usage via
GET /quotas
Rate limits & credits
| Action | Credits |
|---|---|
| Text message | 1 |
| Message with attachment | 2 |
| Failed message | Refunded |
Check your current usage anytime with
GET /quotas. Contact support to discuss higher limits on Business plans.Next steps
Quickstart
Send your first message in 5 minutes
Authentication
Set up your API token