TimelinesAI Public API
The TimelinesAI Public API enables you to automate WhatsApp messaging by connecting your existing systems, such as CRMs, to TimelinesAI. With this API, you can configure your systems to send messages automatically whenever a specific trigger or action occurs, such as adding a new lead to your CRM or a status update.
This integration streamlines communication, saves time, and ensures your messages are sent immediately without manual intervention. In this document, we will explore and understand the processes and steps required for effectively using the Public API.
Generate API Token
Testing with Swagger Playground
Share Files via API
Monitoring API Usage
Where to Find Chat ID?
Let’s get started 🚀
The first step in working with the Public API is generating your unique API Token. This token is a secure identifier that links your workspace to external systems, such as your CRM or support platforms. Once generated, this token is used to authorize your systems to interact with the Public API, ensuring all actions are performed securely and within the permissions set for your workspace. If you suspect that your API Token has been exposed, it can be regenerated at any time, and the old token will be immediately disabled to maintain security.
After generating your API Token, you can use it to connect TimelinesAI with your systems, like CRM, Support, or Recruitment platforms, to send automated WhatsApp messages. This makes it easy to trigger message delivery directly from your existing tools.
Before integrating, we recommend testing how the API works using the Swagger Playground tool available in the Public API section of your TimelinesAI account. This tool helps you experiment with sending messages in different formats and understand the request structures effectively.
The Swagger Playground is a testing environment where you can experiment with various request formats and message configurations without fully integrating the API into your system. By testing here, you can validate how messages are sent and ensure your integration setup will work as expected. Here are a few important points to keep in mind while using the Swagger tool:
Any API calls or mass-sending actions performed using the Swagger tool will count toward your credit usage.
Refreshing the page will reset any changes or progress you have made within the Swagger tool.
Before using the Swagger Playground tool, it’s important to understand the basics of how the Public API works. You can access this information by clicking the API Documentation button in the Public API section of your TimelinesAI account.
Before you can test or interact with the API using Swagger, you need to authorize your session using your API Token. This step ensures that only authorized requests are processed by the API. Authorization provides secure access and ensures that your interactions remain within the permissions of your workspace.
Once authorized, you can test API requests through the Swagger interface. This involves selecting specific API endpoints, such as sending messages or retrieving data and experimenting with request configurations. Testing API requests in this controlled environment allows you to fine-tune your integrations and identify any adjustments needed before live deployment.
To test some API requests, specify the chat ID of the contact you want to send messages to via the Public API. To find the chat ID, please refer to the section Where to Find Chat ID? So, here are some API requests you can make:
For more information regarding Timelines Public API, you can refer to the embedded iframe documentation provided below: along with the details regarding its functionality and usage:
Once you have executed the request successfully, you can view the chat conversation in your TimelinesAI workspace. The message sent via the Public API will appear under the respective contact's chat timeline, allowing you to confirm the delivery and review the interaction.
TimelineAI’s public API provides powerful tools for managing messages, chats, and attachments efficiently. With these endpoints, you can track message statuses, monitor chat responses, update chat details, and send files or voice messages seamlessly. Here is a closer look at how these features can enhance your workflows.
TimelineAI’s public API helps you check the message statuses after they have been sent or received. This means you can find out if a message was sent, delivered, read, or failed. For instance, you can send an initial message, and after a delay, retrieve the details of that message. If the message has not been read, you can proceed to send another message or a reminder. The available endpoints allow you to obtain the details of a message by its Unique Identifier (UID) and to access the sending history of a message using its UID.
TimelinesAI public API endpoints can also retrieve details about specific chats. This capability is beneficial for tracking customer responses in ongoing conversations.
Example:
After sending an initial message, you can use the API to get the details of the chat where the message was sent. If the last message's UID or timestamp matches the initial message's UID and timestamp, it indicates that the customer has not responded. Based on this information, you can follow up with another message or reminder. The endpoint provided for this use case retrieves comprehensive chat details.
The API enables the management of existing chats in the TimelinesAI Shared Inbox, facilitating actions such as labeling chats or adding notes to enhance organization and monitoring.
Example:
When a specific event occurs in your CRM or a particular automated message is sent, you can apply a corresponding label to the related chat in TimelinesAI. This allows for easier filtering and tracking of chats by label. The available endpoints support updating chat details, adding labels to chats, and appending notes to existing chats.
TimelinesAI public API endpoints allow sending files and voice messages to WhatsApp contacts, including individual users and groups.
Example:
You can send an image to a WhatsApp contact using a publicly accessible downloadable link. Additionally, you can send voice notes within existing WhatsApp chats or groups. The API also supports listing files uploaded in your TimelinesAI workspace, uploading files in x-form, and retrieving details or temporary download URLs for specific uploaded files. These endpoints streamline the process of managing and sending attachments.
To send files through API integration, ensure your API request includes the necessary file details, such as file identifiers and supported formats. For more information on sharing files/attachments via API, refer to the documentation on Sharing Files via Public API.
To effectively manage and track your API interactions, it's important to monitor your usage and understand the available limits and reporting tools.
You can download log reports to analyze the details and status of your API requests. These logs provide insights into the most recent interactions within your workspace. To retrieve a log file containing the latest 1,000 requests, simply click on the "Download log" option available in the API section of your workspace. This feature helps you review any errors, successes, or anomalies in your API usage.
Each workspace is allocated 200,000 API calls monthly. This limit resets at the beginning of your billing cycle, ensuring you have a fresh quota each month. Additionally, the API is designed with a rate limit, allowing up to 50 requests per minute to maintain system efficiency and prevent overloading.
If your usage exceeds the allocated limit, or if you anticipate requiring additional API calls due to higher demand, you can reach out to the support team for assistance in increasing your API limits or exploring suitable solutions. You can also view the current utilization of your monthly API call limit in the “Public API” dashboard, showing how many API calls have been used out of the total allocated 200,000.
The mass-sending quota is essential for enabling automated message delivery through the API. It ensures that your workspace can efficiently manage and send messages at scale. If a message fails to send, the quota units associated with that attempt will be restored, ensuring you do not lose the quota unnecessarily. Each workspace is assigned a specific quota, which is reset at the beginning of the billing cycle. The unused quota does not carry over to the next cycle. If your current quota is insufficient for your needs, you can increase it by upgrading your subscription plan.
You can track your remaining mass-sending quota and manage your message delivery efficiently. If needed, you can upgrade your subscription to increase the quota. For more detailed information on mass sending quota, refer to the Mass Sending Quota: Overview documentation.
Remember, if you need to increase your API Calls and/or API rate limit, you may request this via our Chat Support or email at hello@timelines.ai.
You can find the Chat ID in the URL of the specific chat or contact page within your TimelinesAI workspace, or in the payload of the outbound webhook linked to the contact.
This integration streamlines communication, saves time, and ensures your messages are sent immediately without manual intervention. In this document, we will explore and understand the processes and steps required for effectively using the Public API.
Generate API Token
Testing with Swagger Playground
Share Files via API
Monitoring API Usage
Where to Find Chat ID?
Let’s get started 🚀
Generate API Token
The first step in working with the Public API is generating your unique API Token. This token is a secure identifier that links your workspace to external systems, such as your CRM or support platforms. Once generated, this token is used to authorize your systems to interact with the Public API, ensuring all actions are performed securely and within the permissions set for your workspace. If you suspect that your API Token has been exposed, it can be regenerated at any time, and the old token will be immediately disabled to maintain security.
How to Use it?
After generating your API Token, you can use it to connect TimelinesAI with your systems, like CRM, Support, or Recruitment platforms, to send automated WhatsApp messages. This makes it easy to trigger message delivery directly from your existing tools.
Before integrating, we recommend testing how the API works using the Swagger Playground tool available in the Public API section of your TimelinesAI account. This tool helps you experiment with sending messages in different formats and understand the request structures effectively.
Testing with Swagger Playground
The Swagger Playground is a testing environment where you can experiment with various request formats and message configurations without fully integrating the API into your system. By testing here, you can validate how messages are sent and ensure your integration setup will work as expected. Here are a few important points to keep in mind while using the Swagger tool:
Any API calls or mass-sending actions performed using the Swagger tool will count toward your credit usage.
Refreshing the page will reset any changes or progress you have made within the Swagger tool.
Before using the Swagger Playground tool, it’s important to understand the basics of how the Public API works. You can access this information by clicking the API Documentation button in the Public API section of your TimelinesAI account.
Token Authorization in Swagger
Before you can test or interact with the API using Swagger, you need to authorize your session using your API Token. This step ensures that only authorized requests are processed by the API. Authorization provides secure access and ensures that your interactions remain within the permissions of your workspace.
Testing API Requests
Once authorized, you can test API requests through the Swagger interface. This involves selecting specific API endpoints, such as sending messages or retrieving data and experimenting with request configurations. Testing API requests in this controlled environment allows you to fine-tune your integrations and identify any adjustments needed before live deployment.
To test some API requests, specify the chat ID of the contact you want to send messages to via the Public API. To find the chat ID, please refer to the section Where to Find Chat ID? So, here are some API requests you can make:
For more information regarding Timelines Public API, you can refer to the embedded iframe documentation provided below: along with the details regarding its functionality and usage:
Once you have executed the request successfully, you can view the chat conversation in your TimelinesAI workspace. The message sent via the Public API will appear under the respective contact's chat timeline, allowing you to confirm the delivery and review the interaction.
Use Cases And Practical Scenarios
TimelineAI’s public API provides powerful tools for managing messages, chats, and attachments efficiently. With these endpoints, you can track message statuses, monitor chat responses, update chat details, and send files or voice messages seamlessly. Here is a closer look at how these features can enhance your workflows.
Get Message Details
TimelineAI’s public API helps you check the message statuses after they have been sent or received. This means you can find out if a message was sent, delivered, read, or failed. For instance, you can send an initial message, and after a delay, retrieve the details of that message. If the message has not been read, you can proceed to send another message or a reminder. The available endpoints allow you to obtain the details of a message by its Unique Identifier (UID) and to access the sending history of a message using its UID.
| Sr. No. | HTTP Method | API Endpoints | Description |
|---|---|---|---|
| 1 | GET | /messages/{messge_uid} | Get the details of a message specified by the message’s UID. |
| 2 | GET | /messages/{messge_uid}/status_history | Get the sending history of a message, specified by the message’s UID. |
Get Chat Details
TimelinesAI public API endpoints can also retrieve details about specific chats. This capability is beneficial for tracking customer responses in ongoing conversations.
Example:
After sending an initial message, you can use the API to get the details of the chat where the message was sent. If the last message's UID or timestamp matches the initial message's UID and timestamp, it indicates that the customer has not responded. Based on this information, you can follow up with another message or reminder. The endpoint provided for this use case retrieves comprehensive chat details.
| Sr. No. | HTTP Method | API Endpoints | Description |
|---|---|---|---|
| 1 | GET | /chats/{chat_id} | Get the details of a chat |
Update Chat Details In TimelinesAI
The API enables the management of existing chats in the TimelinesAI Shared Inbox, facilitating actions such as labeling chats or adding notes to enhance organization and monitoring.
Example:
When a specific event occurs in your CRM or a particular automated message is sent, you can apply a corresponding label to the related chat in TimelinesAI. This allows for easier filtering and tracking of chats by label. The available endpoints support updating chat details, adding labels to chats, and appending notes to existing chats.
| Sr. No. | HTTP Method | API Endpoints | Description |
|---|---|---|---|
| 1 | PATCH | /chats/{chat_id} | Update Chat |
| 2 | PUT | /chats/{chat_id}/labels | Add labels for the chat |
| 3 | POST | /chats/{chat_id}/notes | Add a note to the existing chat |
Add Attachments To Your Messages
TimelinesAI public API endpoints allow sending files and voice messages to WhatsApp contacts, including individual users and groups.
Example:
You can send an image to a WhatsApp contact using a publicly accessible downloadable link. Additionally, you can send voice notes within existing WhatsApp chats or groups. The API also supports listing files uploaded in your TimelinesAI workspace, uploading files in x-form, and retrieving details or temporary download URLs for specific uploaded files. These endpoints streamline the process of managing and sending attachments.
| Sr. No. | HTTP Method | API Endpoints | Description |
|---|---|---|---|
| 1 | POST | /chats/{chat_id}/voice_message | Send voice notes into existing WhatsApp chat (or group) specified by chat_id. |
| 2 | GET | /files | List files uploaded in your TimelinesAI workspace |
| 3 | POST | /files_upload | Upload a file in x-form |
| 4 | GET | /files/{files_uid} | Get details and a temporary download URL for a specified uploaded file |
Share Files via API
To send files through API integration, ensure your API request includes the necessary file details, such as file identifiers and supported formats. For more information on sharing files/attachments via API, refer to the documentation on Sharing Files via Public API.
Monitoring API Usage
To effectively manage and track your API interactions, it's important to monitor your usage and understand the available limits and reporting tools.
Review and Download API Log Reports
You can download log reports to analyze the details and status of your API requests. These logs provide insights into the most recent interactions within your workspace. To retrieve a log file containing the latest 1,000 requests, simply click on the "Download log" option available in the API section of your workspace. This feature helps you review any errors, successes, or anomalies in your API usage.
Understanding API Call Limits
Each workspace is allocated 200,000 API calls monthly. This limit resets at the beginning of your billing cycle, ensuring you have a fresh quota each month. Additionally, the API is designed with a rate limit, allowing up to 50 requests per minute to maintain system efficiency and prevent overloading.
If your usage exceeds the allocated limit, or if you anticipate requiring additional API calls due to higher demand, you can reach out to the support team for assistance in increasing your API limits or exploring suitable solutions. You can also view the current utilization of your monthly API call limit in the “Public API” dashboard, showing how many API calls have been used out of the total allocated 200,000.
Mass Sending Quota
The mass-sending quota is essential for enabling automated message delivery through the API. It ensures that your workspace can efficiently manage and send messages at scale. If a message fails to send, the quota units associated with that attempt will be restored, ensuring you do not lose the quota unnecessarily. Each workspace is assigned a specific quota, which is reset at the beginning of the billing cycle. The unused quota does not carry over to the next cycle. If your current quota is insufficient for your needs, you can increase it by upgrading your subscription plan.
You can track your remaining mass-sending quota and manage your message delivery efficiently. If needed, you can upgrade your subscription to increase the quota. For more detailed information on mass sending quota, refer to the Mass Sending Quota: Overview documentation.
Remember, if you need to increase your API Calls and/or API rate limit, you may request this via our Chat Support or email at hello@timelines.ai.
Where to Find Chat ID?
You can find the Chat ID in the URL of the specific chat or contact page within your TimelinesAI workspace, or in the payload of the outbound webhook linked to the contact.
Updated on: 13/01/2025
Thank you!