# TimelinesAI API Documentation ## Docs - [Introduction](https://timelines.ai/docs/introduction.md): Welcome to the TimelinesAI API documentation - [Quickstart](https://timelines.ai/docs/quickstart.md): Send your first WhatsApp message in 5 minutes - [Authentication](https://timelines.ai/docs/authentication.md): How to authenticate with the TimelinesAI API - [Rate Limits](https://timelines.ai/docs/rate-limits.md): Understand API rate limits and how to handle them gracefully - [Sending Messages](https://timelines.ai/docs/guides/sending-messages.md): Learn how to send WhatsApp messages via the API - [Managing Chats](https://timelines.ai/docs/guides/managing-chats.md): Organize, filter, and manage your WhatsApp conversations - [Webhooks](https://timelines.ai/docs/guides/webhooks.md): Receive real-time notifications for WhatsApp events - [File Attachments](https://timelines.ai/docs/guides/file-attachments.md): Send images, documents, and other files via WhatsApp - [Public API Overview](https://timelines.ai/docs/public-api-reference/overview.md): Manage WhatsApp communications programmatically with the TimelinesAI Public API - [List Chats](https://timelines.ai/docs/public-api-reference/get-full-or-filtered-list-of-all-chats-in-the-workspace.md): Get full or filtered list of all chats in the workspace. Supports filtering by label, WhatsApp account, phone, responsible, and more. - [Get Chat](https://timelines.ai/docs/public-api-reference/get-details-of-a-chat.md): Get details of a specific chat by chat ID. - [Update Chat](https://timelines.ai/docs/public-api-reference/update-chat.md): Update chat's name, assign responsible, or close/re-open a chat. - [List Messages](https://timelines.ai/docs/public-api-reference/get-filtered-chat-history-messages-only-of-the-chat.md): Get filtered chat history (messages only) for a specific chat. Supports filtering by direction, date range, and message UID. - [Get Message](https://timelines.ai/docs/public-api-reference/get-the-details-of-a-message-specified-by-the-messages-uid.md): Get the details of a message specified by its UID. - [Get Message Status](https://timelines.ai/docs/public-api-reference/get-the-sending-history-of-a-message-specified-by-the-messages-uid.md): Get the sending history of a message specified by its UID. - [Send Message to Chat](https://timelines.ai/docs/public-api-reference/send-message-in-existing-chat.md): Send a message into an existing WhatsApp chat or group specified by chat_id. - [Send Message to Phone](https://timelines.ai/docs/public-api-reference/send-message-to-phone-number.md): Send a message to a WhatsApp phone number. Doesn't require a previous chat or contact with the recipient. - [Send Message to JID](https://timelines.ai/docs/public-api-reference/send-message-to-jid.md): Send a message to a WhatsApp chat or group specified by JID. - [Send Message to Chat Name](https://timelines.ai/docs/public-api-reference/send-message-in-existing-chat-specified-by-chat-name.md): Send a message to an existing WhatsApp chat or group specified by its name in TimelinesAI. - [Send Voice Message](https://timelines.ai/docs/public-api-reference/post-chats-voice_message.md): Send a voice note into an existing WhatsApp chat or group. Supports OGG, OGA, and MP3 audio files. - [Add Note](https://timelines.ai/docs/public-api-reference/add-a-note-to-existing-chat.md): Add a note to an existing WhatsApp chat or group specified by chat_id. - [Get Reactions](https://timelines.ai/docs/public-api-reference/get-the-current-reactions-map-for-a-message.md): Get the current reactions map for a message. - [Update Reactions](https://timelines.ai/docs/public-api-reference/update-reactions-for-a-message.md): Add or remove emoji reactions for a message. - [List Files](https://timelines.ai/docs/public-api-reference/list-files-uploaded-in-your-timelinesai-workspace.md): List files uploaded in your TimelinesAI workspace. Supports filtering by filename. - [Upload File (URL)](https://timelines.ai/docs/public-api-reference/upload-a-file-using-a-publicly-accessible-url.md): Upload a file using a publicly accessible URL. Filename and mime-type are auto-detected. - [Upload File (Form)](https://timelines.ai/docs/public-api-reference/upload-a-file-in-x-form-encoded-http-request.md): Upload a file using a multipart/form-data encoded HTTP request. - [Get File](https://timelines.ai/docs/public-api-reference/get-details-and-temporary-download-url-for-a-specified-uploaded-file.md): Get details and a temporary download URL (valid for 15 minutes) for a specified uploaded file. - [Delete File](https://timelines.ai/docs/public-api-reference/delete-the-specified-uploaded-file.md): Delete the specified uploaded file. - [List Labels](https://timelines.ai/docs/public-api-reference/list-labels-for-the-specified-chat.md): List labels for the specified chat. - [Add Labels](https://timelines.ai/docs/public-api-reference/adds-labels-for-the-chat.md): Add labels to a chat without removing existing ones. - [Replace Labels](https://timelines.ai/docs/public-api-reference/replaces-labels-for-the-chat.md): Replace all labels for a chat with the specified set. - [List WhatsApp Accounts](https://timelines.ai/docs/public-api-reference/list-whatsapp-accounts-connected-in-your-timelinesai-workspace.md): List WhatsApp accounts connected in your TimelinesAI workspace. - [Get Workspace Info](https://timelines.ai/docs/public-api-reference/workspace-info-and-all-current-quotas-and-utilization-stats.md): Returns workspace identity, plan, and current quota utilization. - [List Teammates](https://timelines.ai/docs/public-api-reference/list-all-teammates-in-the-workspace.md): List all teammates in the workspace. - [Invite Teammate](https://timelines.ai/docs/public-api-reference/invite-new-teammate-to-the-workspace.md): Send an invitation to a new teammate by email. - [Revoke Invitation](https://timelines.ai/docs/public-api-reference/revoke-a-pending-invitation.md): Revoke a pending teammate invitation. - [List Webhooks](https://timelines.ai/docs/public-api-reference/list-webhooks.md): List all webhook subscriptions for the current workspace. - [Create Webhook](https://timelines.ai/docs/public-api-reference/create-webhook.md): Create a new webhook subscription for a specified event. - [Get Webhook](https://timelines.ai/docs/public-api-reference/get-webhook.md): Get the webhook subscription identified by webhook_id. - [Update Webhook](https://timelines.ai/docs/public-api-reference/update-webhook.md): Update fields of a webhook subscription. Only supplied properties are changed. - [Delete Webhook](https://timelines.ai/docs/public-api-reference/delete-webhook.md): Permanently delete a webhook subscription. Deliveries stop immediately. - [WABA API Overview](https://timelines.ai/docs/public-api-reference/waba/overview.md): Manage WhatsApp Business Platform (WABA) conversations, messages, templates, and accounts programmatically - [List WABA Chats](https://timelines.ai/docs/public-api-reference/waba/get-full-or-filtered-list-of-all-waba-chats-in-the-workspace.md): Get a full or filtered list of all WABA chats in the workspace. - [Get WABA Chat](https://timelines.ai/docs/public-api-reference/waba/get-details-of-a-waba-chat.md): Get details of a specific WABA chat by chat ID. - [Update WABA Chat](https://timelines.ai/docs/public-api-reference/waba/update-waba-chat.md): Update a WABA chat (assignment, status, and read state). - [Get WABA Chat History](https://timelines.ai/docs/public-api-reference/waba/get-filtered-waba-chat-history-messages-only-of-the-chat.md): Get the filtered chat history (messages only) of a WABA chat. - [Send WABA Message in Chat](https://timelines.ai/docs/public-api-reference/waba/send-waba-message-in-existing-chat.md): Send a WABA message in an existing chat. - [Send WABA Message to Phone](https://timelines.ai/docs/public-api-reference/waba/send-waba-message-to-phone-number.md): Send a WABA message to a phone number. - [Get WABA Message](https://timelines.ai/docs/public-api-reference/waba/get-the-details-of-a-waba-message-specified-by-the-messages-uid.md): Get the details of a WABA message specified by its UID. - [Get WABA Message History](https://timelines.ai/docs/public-api-reference/waba/get-the-sending-history-of-a-waba-message-specified-by-the-messages-uid.md): Get the sending/status history of a WABA message specified by its UID. - [Get WABA Reaction](https://timelines.ai/docs/public-api-reference/waba/get-the-current-reaction-for-a-waba-message.md): Get the current reaction for a WABA message. - [Set WABA Reaction](https://timelines.ai/docs/public-api-reference/waba/set-or-clear-the-reaction-for-a-waba-message.md): Set or clear the reaction for a WABA message. - [List WABA Chat Labels](https://timelines.ai/docs/public-api-reference/waba/list-labels-for-the-specified-waba-chat.md): List labels for the specified WABA chat. - [Replace WABA Chat Labels](https://timelines.ai/docs/public-api-reference/waba/replaces-labels-for-the-waba-chat.md): Replace all labels for a WABA chat with the specified set. - [Add WABA Chat Labels](https://timelines.ai/docs/public-api-reference/waba/adds-labels-for-the-waba-chat.md): Add labels to a WABA chat. - [List WABA Accounts](https://timelines.ai/docs/public-api-reference/waba/get-the-list-of-all-waba-accounts-in-the-workspace.md): Get the list of all WABA accounts in the workspace. - [Get WABA Account](https://timelines.ai/docs/public-api-reference/waba/get-details-of-a-waba-account.md): Get details of a specific WABA account. - [Request WABA Account Analytics](https://timelines.ai/docs/public-api-reference/waba/request-waba-account-analytics.md): Request WABA account analytics; returns a handle to poll for the result. - [Poll WABA Account Analytics](https://timelines.ai/docs/public-api-reference/waba/poll-a-waba-account-analytics-request.md): Poll a previously requested WABA account analytics job by its handle. - [List WABA Templates](https://timelines.ai/docs/public-api-reference/waba/get-the-list-of-all-waba-templates-in-the-workspace.md): Get the list of all WABA templates in the workspace. - [Get WABA Template](https://timelines.ai/docs/public-api-reference/waba/get-details-of-a-waba-template.md): Get details of a specific WABA template. - [WABA API Webhooks Overview](https://timelines.ai/docs/webhook-reference/waba-overview.md): Receive real-time notifications for WhatsApp Business Platform (WABA) events in your workspace - [New Incoming WABA Message](https://timelines.ai/docs/webhook-reference/waba_messages/triggered-when-a-new-waba-message-is-received.md): Triggered when a new WABA message is received from a contact on a WABA account in the workspace. - [WABA Message Delivered](https://timelines.ai/docs/webhook-reference/waba_messages/triggered-when-an-outbound-waba-message-is-delivered.md): Triggered when an outbound WABA message is delivered to the contact. - [WABA Message Read](https://timelines.ai/docs/webhook-reference/waba_messages/triggered-when-an-outbound-waba-message-is-read.md): Triggered when an outbound WABA message is read by the contact. - [WABA Message Failed](https://timelines.ai/docs/webhook-reference/waba_messages/triggered-when-an-outbound-waba-message-fails-to-send.md): Triggered when an outbound WABA message fails to send. The payload includes a structured failure_reason with code, title, and details. - [New Incoming WABA Chat](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-there-is-a-new-incoming-waba-chat.md): Triggered when there is a new incoming WABA chat on a WABA account in the workspace. - [New Outgoing WABA Chat](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-there-is-a-new-outgoing-waba-chat.md): Triggered when there is a new outgoing WABA chat on a WABA account in the workspace. - [WABA Chat Assigned](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-a-waba-chat-is-reassigned-to-a-workspace-member.md): Triggered when a WABA chat is assigned or reassigned to a workspace member. - [WABA Chat Unassigned](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-a-waba-chat-is-unassigned.md): Triggered when a WABA chat is unassigned from a workspace member. - [WABA Chat Closed](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-a-waba-chat-is-closed.md): Triggered when a WABA chat is closed. - [WABA Chat Reopened](https://timelines.ai/docs/webhook-reference/waba_chats/triggered-when-a-waba-chat-is-reopened.md): Triggered when a WABA chat is reopened. - [WABA Account Active](https://timelines.ai/docs/webhook-reference/waba_accounts/triggered-when-a-waba-account-becomes-active.md): Triggered when a WABA account becomes active in the workspace. - [WABA Account Disabled](https://timelines.ai/docs/webhook-reference/waba_accounts/triggered-when-a-waba-account-is-disabled.md): Triggered when a WABA account is disabled. - [WABA Account Disconnected](https://timelines.ai/docs/webhook-reference/waba_accounts/triggered-when-a-waba-account-is-disconnected.md): Triggered when a WABA account is disconnected (removed) from the workspace. - [WABA Template Approved](https://timelines.ai/docs/webhook-reference/waba_templates/triggered-when-a-waba-template-is-approved.md): Triggered when a WABA message template is approved by Meta. - [WABA Template Rejected](https://timelines.ai/docs/webhook-reference/waba_templates/triggered-when-a-waba-template-is-rejected.md): Triggered when a WABA message template is rejected by Meta. - [WABA Template Disabled](https://timelines.ai/docs/webhook-reference/waba_templates/triggered-when-a-waba-template-is-disabled.md): Triggered when a WABA message template is disabled or pending deletion. - [PublicAPI Webhooks Overview](https://timelines.ai/docs/webhook-reference/overview.md): Receive real-time notifications for WhatsApp events in your workspace - [New Outgoing Message](https://timelines.ai/docs/webhook-reference/messages/triggered-when-a-new-outgoing-message.md): Triggered when a new outgoing message is sent from a WhatsApp account in the workspace. - [New Incoming Message](https://timelines.ai/docs/webhook-reference/messages/triggered-when-there-is-a-new-incoming-message.md): Triggered when there is a new incoming message received by a WhatsApp account in the workspace. - [New Message](https://timelines.ai/docs/webhook-reference/messages/triggered-when-there-is-a-new-message.md): Triggered when there is any new message (incoming or outgoing) on a WhatsApp account in the workspace. - [Message Reaction](https://timelines.ai/docs/webhook-reference/messages/triggered-when-a-whatsapp-message-reaction-is-set-or-cleared.md): Triggered when a WhatsApp message reaction is set or cleared. The payload includes the full current reactions map for the message after the change. - [Account Reconnected](https://timelines.ai/docs/webhook-reference/whatsapp_accounts/triggered-when-whatsapp-account-was-reconnected.md): Triggered when a WhatsApp account is (re)connected to the workspace. - [Account Disconnected](https://timelines.ai/docs/webhook-reference/whatsapp_accounts/triggered-when-whatsapp-account-was-disconnected.md): Triggered when a WhatsApp account is permanently disconnected from the workspace. - [Message Sync Suspended](https://timelines.ai/docs/webhook-reference/whatsapp_accounts/triggered-when-a-whatsapp-account-message-syncing-is-suspended-for-a-reason-such-as-subscription-cancellation-or-downgrade.md): Triggered when a WhatsApp account message syncing is suspended due to subscription cancellation or downgrade. - [Message Sync Resumed](https://timelines.ai/docs/webhook-reference/whatsapp_accounts/triggered-when-a-whatsapp-account-message-syncing-is-resumed.md): Triggered when a WhatsApp account message syncing is resumed. - [New Chat](https://timelines.ai/docs/webhook-reference/chats/triggered-when-there-is-a-new-direct-or-group-chat.md): Triggered when there is a new direct or group chat. - [New Incoming Chat](https://timelines.ai/docs/webhook-reference/chats/triggered-when-there-is-a-new-incoming-direct-chat.md): Triggered when there is a new incoming direct chat. - [New Outgoing Chat](https://timelines.ai/docs/webhook-reference/chats/triggered-when-there-is-a-new-outgoing-direct-chat.md): Triggered when there is a new outgoing direct chat. - [Chat Assigned](https://timelines.ai/docs/webhook-reference/chats/triggered-when-a-chat-was-reassigned-to-a-workspace-member.md): Triggered when a chat is (re)assigned to a workspace member. - [Chat Unassigned](https://timelines.ai/docs/webhook-reference/chats/triggered-when-a-chat-was-unassigned.md): Triggered when a chat is unassigned from a workspace member. - [Incoming Call Missed](https://timelines.ai/docs/webhook-reference/calls/triggered-when-an-incoming-whatsapp-call-was-missed.md): Triggered when an incoming WhatsApp voice or video call was missed (not answered before the caller ended the call). - [Incoming Call Ended](https://timelines.ai/docs/webhook-reference/calls/triggered-when-an-incoming-whatsapp-call-ended.md): Triggered when an incoming WhatsApp voice or video call ended. Status is Answered when the call was picked up, or Rejected when it was actively declined by the recipient. - [Outgoing Call Ended](https://timelines.ai/docs/webhook-reference/calls/triggered-when-an-outgoing-whatsapp-call-ended.md): Triggered when an outgoing WhatsApp voice or video call ended. Status is Ended for completed calls, No Answer when the recipient never picked up, or Rejected when the recipient actively declined. - [Partner API Overview](https://timelines.ai/docs/partner-api-reference/overview.md): Programmatically manage TimelinesAI workspaces, users, and WhatsApp connections for your platform - [Create a workspace](https://timelines.ai/docs/partner-api-reference/workspaces/create-a-workspace.md): Creates a new partner-managed workspace and automatically provisions an Owner user. The workspace_id identifier is derived from the requested display_name (lowercase, alphanumeric and dashes, up to 30 characters). The workspace is created on the calling partner's plan and linked to that partner for… - [Get workspace details](https://timelines.ai/docs/partner-api-reference/workspaces/get-workspace-details.md): Returns a consolidated, read-only summary of a partner-managed workspace. The payload includes basic workspace identity (workspace_id, display_name), seat allocation and utilization, messaging and API quotas, any non-recurring quota balance, the list of users in the workspace, WhatsApp accounts asso… - [Update workspace](https://timelines.ai/docs/partner-api-reference/workspaces/update-workspace.md): Updates mutable workspace attributes for a partner-managed workspace. Partners can change the human-readable display_name and/or adjust the number of purchased seats (seats_purchased, 1-999). When the purchased seats are reduced below current utilization, the platform may automatically suspend users… - [Create users in workspace](https://timelines.ai/docs/partner-api-reference/workspaces/create-users-in-workspace.md): Bulk-creates placeholder agent users in a partner-managed workspace. Each request specifies a count of users to create. For every user the platform: assigns the agent role and activated status, creates a non-login, system-managed email `-@partners.timelines.ai`, assigns the us… - [Generate QR code for user](https://timelines.ai/docs/partner-api-reference/qr/generate-qr-code-for-user.md): Issues a long-lived WhatsApp QR-code link for a specific user in a partner-managed workspace. If the user already has a connected WhatsApp account, that account is disconnected first and the previous QR link (if any) is revoked. Only one active QR link per user is allowed at any given time; generati… - [Embedding overview](https://timelines.ai/docs/partner-api-reference/qr/embedding-overview.md): Embed the WhatsApp QR connection page in your own product, with default or fully custom UI - [postMessage API](https://timelines.ai/docs/partner-api-reference/qr/embedding-postmessage-api.md): Drive the QR and phone-pairing flows from your own UI via postMessage events - [Disconnect WhatsApp account](https://timelines.ai/docs/partner-api-reference/whatsappaccounts/disconnect-whatsapp-account.md): Forcibly disconnects the WhatsApp account currently linked to a specific user. If the user has an active WhatsApp connection, the session is terminated, sync is stopped and credentials are revoked. The response includes identifiers of the disconnected WhatsApp account and phone number together with… - [Get public API token](https://timelines.ai/docs/partner-api-reference/publicapi/get-public-api-token.md): Retrieves the current Public API token for a partner-managed workspace. If a token already exists it is returned as the raw token value so that the partner can configure it in their integration. If no token exists yet, the platform creates a new one and returns it. Only workspaces owned by the calli… - [Rotate public API token](https://timelines.ai/docs/partner-api-reference/publicapi/rotate-public-api-token.md): Rotates the Public API token for a partner-managed workspace. A new token is generated, persisted according to the platform’s security rules, and the previous token is invalidated immediately. Each successful rotation returns the new raw token value and the rotated_at timestamp. Subsequent calls rot… - [Partner API Webhooks Overview](https://timelines.ai/docs/partner-api-webhook-reference/overview.md): Receive real-time notifications for workspace, account, and quota events across your managed workspaces - [Seats Full](https://timelines.ai/docs/partner-api-webhook-reference/workspaces/triggered-when-all-purchased-seats-in-a-workspace-are-utilized-no-available-seats-remain.md): Triggered when all purchased seats in a workspace are utilized (no available seats remain). - [Messaging Quota Near Full](https://timelines.ai/docs/partner-api-webhook-reference/workspaces/triggered-when-the-messaging-quota-for-a-workspace-reaches-or-exceeds-90-percent-utilization-within-the-current-billing-period.md): Triggered when the messaging quota for a workspace reaches or exceeds 90% utilization within the current billing period. - [Messaging Quota Full](https://timelines.ai/docs/partner-api-webhook-reference/workspaces/triggered-when-the-messaging-quota-for-a-workspace-reaches-or-exceeds-100-percent-utilization-within-the-current-billing-period.md): Triggered when the messaging quota for a workspace reaches or exceeds 100% utilization within the current billing period. - [Transactions Quota Full](https://timelines.ai/docs/partner-api-webhook-reference/workspaces/triggered-when-the-transactions-quota-of-a-workspace-has-been-fully-utilized.md): Triggered when the transactions quota of a workspace has been fully utilized. - [API Calls Quota Full](https://timelines.ai/docs/partner-api-webhook-reference/workspaces/triggered-when-the-public-api-calls-quota-for-a-workspace-reaches-or-exceeds-100-percent-utilization-within-the-current-billing-period.md): Triggered when the Public API calls quota for a workspace reaches or exceeds 100% utilization within the current billing period. - [Account Connected](https://timelines.ai/docs/partner-api-webhook-reference/whatsapp_accounts/triggered-when-a-whatsapp-account-is-successfully-connected-for-a-workspace-user.md): Triggered when a WhatsApp account is successfully connected for a workspace user. - [Account Disconnected](https://timelines.ai/docs/partner-api-webhook-reference/whatsapp_accounts/triggered-when-a-whatsapp-account-is-successfully-disconnected-for-a-workspace-user.md): Triggered when a WhatsApp account is disconnected for a workspace user. - [API Token Rotated](https://timelines.ai/docs/partner-api-webhook-reference/api_tokens/triggered-when-a-workspace-public-api-token-is-rotated-via-the-partner-api.md): Triggered when a workspace Public API token is rotated via the Partner API. ## OpenAPI Specs - [webhook_spec](https://timelines.ai/docs/openapi/webhook_spec.yaml) - [public_api_spec](https://timelines.ai/docs/openapi/public_api_spec.yaml) - [partner_api_webhook_spec](https://timelines.ai/docs/openapi/partner_api_webhook_spec.yaml) - [partner_api_spec](https://timelines.ai/docs/openapi/partner_api_spec.yaml) - [openapi](https://timelines.ai/docs/api-reference/openapi.yaml) ## Optional - [TimelinesAI Dashboard](https://app.timelines.ai) - [Support](mailto:support@timelines.ai)