> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API Overview

> Manage WhatsApp communications programmatically with the TimelinesAI Public API

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

## Base URL

```
https://app.timelines.ai/integrations/api
```

All requests require Bearer token authentication. See [Authentication](https://timelines.ai/docs/authentication.md) for details.

## Capabilities

> [card] [Messages](https://timelines.ai/docs/public-api-reference/send-message-to-phone-number.md)
>
> Send text messages, attachments, and voice notes to any WhatsApp number. Track delivery status from queued through read.

> [card] [Chats](https://timelines.ai/docs/public-api-reference/get-full-or-filtered-list-of-all-chats-in-the-workspace.md)
>
> List, filter, and update conversations. Assign chats to team members, close/reopen, and manage read status.

> [card] [Files](https://timelines.ai/docs/public-api-reference/upload-a-file-using-a-publicly-accessible-url.md)
>
> Upload files from URLs or directly. Send images, PDFs, audio, and video as WhatsApp attachments.

> [card] [Labels](https://timelines.ai/docs/public-api-reference/list-labels-for-the-specified-chat.md)
>
> Organize chats with labels. Add, replace, or list labels to categorize and filter conversations.

> [card] [Reactions](https://timelines.ai/docs/public-api-reference/get-the-current-reactions-map-for-a-message.md)
>
> Get and update emoji reactions on messages.

> [card] [Webhooks](https://timelines.ai/docs/public-api-reference/create-webhook.md)
>
> Subscribe to real-time events like new messages, sent messages, and chat updates.

> [card] [WhatsApp Accounts](https://timelines.ai/docs/public-api-reference/list-whatsapp-accounts-connected-in-your-timelinesai-workspace.md)
>
> List connected numbers, or link a new one with a pairing code.

> [card] [Workspace Info](https://timelines.ai/docs/public-api-reference/workspace-info-and-all-current-quotas-and-utilization-stats.md)
>
> View workspace details, plan, and current quota 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`, `POST /whatsapp_accounts/phone_pairing`, `GET /whatsapp_accounts/phone_pairing/{id}` | List connected numbers, start a phone link, and read its status |
| **Teammates** | `GET /workspace/teammates`, `POST /workspace/invitations`, `DELETE /workspace/invitations/{user_id}` | List teammates, invite, and revoke invitations |
| **Workspace** | `GET /workspace` | Workspace info, plan, and quota utilization |
| **Webhooks** | `GET /webhooks`, `POST /webhooks`, `GET/PUT/DELETE /webhooks/{id}` | Manage webhook subscriptions |

## Use case examples

> [accordion] 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.
>
> 1. Set up a webhook for `message:received:new`
> 2. On new message, check if the phone number exists in your CRM
> 3. Create or update the CRM contact
> 4. Use `PATCH /chats/{id}` to assign the chat to the appropriate agent
> 5. Add a label like `crm-synced` for tracking

> [accordion] Automated notifications
>
> Send order updates, appointment reminders, or shipping notifications directly to WhatsApp.
>
> 1. Use `POST /messages` with the customer's phone number
> 2. Include relevant details in the message text
> 3. Attach documents (invoices, receipts) using the file upload endpoints
> 4. Track delivery with `GET /messages/{uid}/status_history`

> [accordion] Support ticket system
>
> Route incoming WhatsApp messages to your support team based on content or labels.
>
> 1. Listen for new messages via webhooks
> 2. Parse the message content to determine the category
> 3. Add appropriate labels with `PUT /chats/{id}/labels`
> 4. Assign to the right agent with `PATCH /chats/{id}`
> 5. Add internal notes with `POST /chats/{id}/notes` for context

> [accordion] Bulk outreach campaigns
>
> Send personalized messages to a list of contacts for marketing or onboarding campaigns.
>
> 1. Iterate over your contact list
> 2. Use `POST /messages` for each recipient with personalized text
> 3. Auto-apply labels (e.g., `campaign-jan-2025`) when sending
> 4. Respect the \~2 second rate limit between messages
> 5. Monitor delivery status and quota usage via `GET /workspace`

## Rate limits & credits

| Action | Credits |
| - | - |
| Text message | 1 |
| Message with attachment | 2 |
| Failed message | Refunded |

Messages are sent with a \~2 second delay between each to comply with WhatsApp guidelines.

> [!NOTE]
>
> Check your current usage anytime with `GET /workspace`. [Contact support](mailto:support@timelines.ai) to discuss higher limits on Business plans.

## Next steps

> [card] [Quickstart](https://timelines.ai/docs/quickstart.md)
>
> Send your first message in 5 minutes

> [card] [Authentication](https://timelines.ai/docs/authentication.md)
>
> Set up your API token


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.