Native Zapier Integration
TimelinesAI Zapier Integration allows to synchronize your WhatsApp communications with external systems (such as CRMs) and to automate messaging as a part of your business flows.
With TimelinesAI, you can connect and dynamically select the WhatsApp account to be used for receiving and sending text messages, file attachments, messaging in groups, and much more.
Before you start, please make sure that you are well acquainted with Zapier automation concepts: Welcome to Zapier Platform UI
Actions that involve sending messages and attachments utilize TimelinesAI Message Sending Quota (each message = 1 quota unit).
We use WhatsApp Web API to deliver messages. In some cases, a message may not be delivered to a recipient due to technical reasons related to the WhatsApp Web platform. When such delivery failure is detected, we will restore your Message Sending quota.
Events and actions, other than sending messages, don’t utilize Message Sending quota but they still are subject to a fair usage limit of 100,000 API calls per month. In order to increase this limit, please contact us for a Business Plan quote.
Each event activation uses Zapier tasks, therefore, use “New message” events with care; a large volume of WhatsApp communication can exhaust task credits in your Zapier account.
In order to send a file as an attachment, you need to make it available as a publicly accessible and downloadable URL, that can be supplied in an appropriate action. Note: due to recent security policy changes, Google Drive or a similar file hosting platforms may not allow to produce direct downloaded links.
When receiving a message with an attachment, the latter will be available for download by means of a publicly accessible and downloadable URL, that will remain valid for 15 minutes from the moment the event was triggered. Don’t store this URL for a longer period of time, as it will expire.
When testing an event, most recent message in your workspace will be loaded (either outgoing or incoming message, belonging to any account).
It’s imperative to send files using Direct Download Links. This allows the recipient to actually receive the file.
Whereas a file hosting service should be used so that it can supply a direct download link. Such a link is best tested via incognito/private browsing; by pasting the link in the search bar. If the file download starts right away, the link is acceptable. If instead, any kind of web page is displayed, then, the link cannot be used for sending files.
The case with File Hosting Service links is that files cannot be downloaded. What’s downloaded and sent instead, is a sharing web page, which may lead to a “corrupted” file.
This, in turn, will affect your message as recipients cannot access the media you send them, making the files unusable. Thus, it is crucial that you ensure that you’re sending direct download links, as this will allow them to access the file without any issues.
You can also run this test by sending a Zap message to one of your test numbers. You’ll be able to determine how the file will behave based on what we've reviewed here; if you get an error message like “File is Corrupted”, “Incompatible File”; or “Failed to load X document”, after clicking on the attachment, then this is a File Hosting Service Link and must be replaced with a Direct Download Link.
In order to connect Zapier with TimelinesAI, navigate to the Zapier Integration section, within your TimelinesAI workspace, and generate new token (“Generate new token”). This token should be used for authentication when setting up your Zapier integration.
Don’t share your token or send it by means of unsafe communication. It can be used by anyone to read your communication or send message on your behalf!
Generating new token will instantly disable existing token. This will instantly affect your running Zaps; they will stop working and you’ll need to manually update them with the new token to restore them to operation.
All chat/message-related events supply the following output fields (that can be used in subsequent steps) in addition to trigger-specific fields:
chat_id: ID of a chat in TimelinesAI, that can be used to specify chat in “send message”/“send file” actions
responsible_email: Email address of Timelines user, to whom this chat is assigned in Timelines (empty, if unassigned)
responsible_name: Full name of Timelines user, to whom this chat is assigned in Timelines (empty, if unassigned)
whatsapp_account_phone: Phone number of a WhatsApp account for which the event was triggered
whatsapp_account_timelines_email: Email address of Timelines user, that connected the WhatsApp account in Timelines workspace
whatsapp_account_timelines_name: Full name of Timelines user, that connected the WhatsApp account in Timelines workspace
whatsapp_account_wid: WhatsApp Web API account identifier (for internal use)
whatsapp_chat_jid: WhatsApp Web API chat identifier (for internal use)
Triggered when a new chat was started via incoming message.
Output:
name: Name of a chat or a group (if renamed manually via TimelinesAI, chat name in TimelinesAI)
New Outgoing Chat
Triggered when a new chat was started via outgoing message.
Note: This will also be triggered when Zapier action “start new chat” is used (if new chat was created as a result of that action).
Output:
name: Name of a chat or a group (if renamed manually via TimelinesAI, chat name in TimelinesAI).
Triggered when a new incoming message is received in any WhatsApp account connected to the workspace.
Output:
whatsapp_message_id: Unique message identifier in Timelines
chat_name: Name of a chat or a group (if renamed via Timelines, chat name in Timelines) into which the message was received
sender_name: Name of the sender of the message (usually the same as chat_name, except for group chats)
sender_phone: Phone number of the sender of the message
message_text: Plaintext message
attachment_url: Url of attachment (if present), valid for 15 minutes from the moment of triggering the event.
attachment_filename: Filename of attachment (if present)
Triggered when a new incoming message is sent (including from WhatsApp Web or WhatsApp Desktop session) from any WhatsApp account connected to the workspace.
Note: This event won’t be triggered if a message was sent by means of one of Zapier “Send message” actions.
Output:
whatsapp_message_id: Unique message identifier in Timelines
chat_name: Name of a chat or a group (if renamed via Timelines, chat name in Timelines) into which the message was received
sender_name: Name of the sender of the message (registered name of the WhatsApp account used to send the message)
sender_phone: Phone number of the sender of the message
recipient_phone: Phone number of the recipient (empty if the chat is a group chat)
message_text: Plaintext message
attachment_url: Url of attachment (if present), valid for 15 minutes from the moment of triggering the event.
attachment_filename: Filename of attachment (if present)
Triggered when a chat (individual or group) is renamed in WhatsApp mobile app (usually, as a result of change in contact name).
Note: This event will not be triggered, if the chat was renamed manually via Timelines UI.
Output:
name: New name of the chat.
previous_name: Previous name of the chat.
Starts a new chat by sending a message to a recipient, specified by a phone number in international format. If the chat with recipient already exists, the message will be sent to that chat. The action will accept the message for sending, after verifying the correctness of the recipient's phone number format and the status of the connected WhatsApp account. Actual sending attempt will be performed asynchronously (usually within few seconds). Message status can be checked later via UI.
Starting a new chat, by sending an attachment, is not supported. If you need to send attachment to a new chat, send text message first and then use “chat_id” from previous action’s output in conjunction with “Send File to Existing Chat” action.
Input:
Whatsapp Account: WhatsApp account to be used to send the message. Can be selected from all WhatsApp accounts in the current workspace, or specified as a phone number in international format. If the selected WhatsApp account becomes disconnected or the phone number doesn’t correspond to a connected WhatsApp account, the action will fail instantly.
Phone number: Phone number of a recipient's WhatsApp account, in international format (with leading “+” and country code).
Message text: Plain message text (no markup supported). Newlines can be added via Zapier text field formatting. Text size is subject to WhatsApp's platform limit (which is currently 65,534 characters). URLs will be automatically displayed as links in the recipient’s WhatsApp client.
Output:
chat_id: ID of a chat in TimelinesAI, can be used to specify chat in “send message”/“send file” actions.
whatsapp_message_id: ID of a message, that will be sent, a unique message identifier in TimelinesAI.
whatsapp_chat_jid: WhatsApp Web API chat identifier (for internal use).
Instant failure reasons (with appropriate error message):
Specified WhatsApp account not found.
Destination phone number is in invalid format.
Message text can not be empty
Monthly mass sending quota exceeded.
Sends a message into an existing chat, that can be specified either by "chat_id" (recommended) or by combination of the WhatsApp Account and the WhatsApp chat jid. The action will accept the message for sending. Actual sending attempt will be performed asynchronously. Message status can later be checked via UI.
Input:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Whatsapp Account Phone: Phone number of WhatsApp account to be used for sending message.
Whatsapp chat jid: WhatsApp Web API chat identifier, returned as an output of previous trigger or action or lookup.
Message text: Plain message text (no markup supported). Newlines can be added via Zapier text field formatting. Text size is subject to WhatsApp platform limit (which is currently 65,534 characters). URLs will be automatically displayed as links in recipient’s WhatsApp client.
Output:
whatsapp_message_id: ID of a message that will be sent; a unique message identifier in TimelinesAI
Instant failure reasons (with appropriate error messages):
Monthly mass sending quota exceeded.
Specified Whatsapp account not found.
Specified jid not found.
Specified chat_id not found.
Sends file attachment into existing chat, that can be specified either by chat_id (recommended) or by combination of WhatsApp Account and WhatsApp chat jid. Files can be sent by means of specifying a combination of downloadable publicly accessible URL and filename (can be different from the name in the URL).
Note: Supported file size is limited to 2 Megabytes (this restriction is shared with other Mass Sending and Automation options on TimelinesAI and doesn’t apply to sending messages manually via UI of TimelinesAI, where files up to 100 Megabytes can be sent).
At the time of sending, the file will be downloaded and cached for subsequent sending attempts. The action will accept the message for sending, however, the availability or size of the file will not be checked at this time. Actual sending attempt will be performed asynchronously and may fail due to inability to invalid the file URL or size. Message status can later be checked via UI.
Input:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Whatsapp Account Phone: Phone number of WhatsApp account to be used for sending message.
Whatsapp chat jid: WhatsApp Web API chat identifier, returned as an output of previous trigger or action or lookup.
Attachment URL: Downloadable, publicly accessible URL.
Name of attached file: The name of the file, as received by the recipient.
Output:
whatsapp_message_id: ID of a message, that will be sent, a unique message identifier in TimelinesAI
Instant failure reasons (with appropriate error message):
Monthly mass sending quota exceeded.
Specified Whatsapp account not found.
Specified jid not found.
Specified chat_id not found.
Attachment URL is invalid.
Searches for a chat (including group chats) and fetches its details. Same output is returned, as for “New Incoming Chat” trigger. Only one search field should be specified:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Name: Name of a chat as appears in TimelinesAI (corresponds to the name of the chat as appears in WhatsApp Mobile App, unless renamed in TimelinesAI).
Phone: Phone number in international format (with leading “+” and country code), that specifies the second party in the chat (not supported for group chats)
Searches for a WhatsApp Account in the current TimelinesAI workspace and fetches its details. Same output is returned, as for “Whatsapp Accounts” trigger. Only one search field should be specified:
Phone: Phone number in international format (with leading “+” and country code), that corresponds to a WhatsApp account connected in the current workspace.
Email: Registration email address of TimelinesAI user, belonging to the current workspace, whose WhatsApp account is to be searched for.
With TimelinesAI, you can connect and dynamically select the WhatsApp account to be used for receiving and sending text messages, file attachments, messaging in groups, and much more.
Before you start, please make sure that you are well acquainted with Zapier automation concepts: Welcome to Zapier Platform UI
Few things to keep in mind:
Actions that involve sending messages and attachments utilize TimelinesAI Message Sending Quota (each message = 1 quota unit).
We use WhatsApp Web API to deliver messages. In some cases, a message may not be delivered to a recipient due to technical reasons related to the WhatsApp Web platform. When such delivery failure is detected, we will restore your Message Sending quota.
Events and actions, other than sending messages, don’t utilize Message Sending quota but they still are subject to a fair usage limit of 100,000 API calls per month. In order to increase this limit, please contact us for a Business Plan quote.
Each event activation uses Zapier tasks, therefore, use “New message” events with care; a large volume of WhatsApp communication can exhaust task credits in your Zapier account.
In order to send a file as an attachment, you need to make it available as a publicly accessible and downloadable URL, that can be supplied in an appropriate action. Note: due to recent security policy changes, Google Drive or a similar file hosting platforms may not allow to produce direct downloaded links.
When receiving a message with an attachment, the latter will be available for download by means of a publicly accessible and downloadable URL, that will remain valid for 15 minutes from the moment the event was triggered. Don’t store this URL for a longer period of time, as it will expire.
When testing an event, most recent message in your workspace will be loaded (either outgoing or incoming message, belonging to any account).
Sending Files via Zapier
Sending a File: Direct Download vs File Hosting Services
It’s imperative to send files using Direct Download Links. This allows the recipient to actually receive the file.
Whereas a file hosting service should be used so that it can supply a direct download link. Such a link is best tested via incognito/private browsing; by pasting the link in the search bar. If the file download starts right away, the link is acceptable. If instead, any kind of web page is displayed, then, the link cannot be used for sending files.
The case with File Hosting Service links is that files cannot be downloaded. What’s downloaded and sent instead, is a sharing web page, which may lead to a “corrupted” file.
This, in turn, will affect your message as recipients cannot access the media you send them, making the files unusable. Thus, it is crucial that you ensure that you’re sending direct download links, as this will allow them to access the file without any issues.
You can also run this test by sending a Zap message to one of your test numbers. You’ll be able to determine how the file will behave based on what we've reviewed here; if you get an error message like “File is Corrupted”, “Incompatible File”; or “Failed to load X document”, after clicking on the attachment, then this is a File Hosting Service Link and must be replaced with a Direct Download Link.
Setup and authentication
In order to connect Zapier with TimelinesAI, navigate to the Zapier Integration section, within your TimelinesAI workspace, and generate new token (“Generate new token”). This token should be used for authentication when setting up your Zapier integration.
Don’t share your token or send it by means of unsafe communication. It can be used by anyone to read your communication or send message on your behalf!
Generating new token will instantly disable existing token. This will instantly affect your running Zaps; they will stop working and you’ll need to manually update them with the new token to restore them to operation.
Events
All chat/message-related events supply the following output fields (that can be used in subsequent steps) in addition to trigger-specific fields:
chat_id: ID of a chat in TimelinesAI, that can be used to specify chat in “send message”/“send file” actions
responsible_email: Email address of Timelines user, to whom this chat is assigned in Timelines (empty, if unassigned)
responsible_name: Full name of Timelines user, to whom this chat is assigned in Timelines (empty, if unassigned)
whatsapp_account_phone: Phone number of a WhatsApp account for which the event was triggered
whatsapp_account_timelines_email: Email address of Timelines user, that connected the WhatsApp account in Timelines workspace
whatsapp_account_timelines_name: Full name of Timelines user, that connected the WhatsApp account in Timelines workspace
whatsapp_account_wid: WhatsApp Web API account identifier (for internal use)
whatsapp_chat_jid: WhatsApp Web API chat identifier (for internal use)
New Incoming Chat
Triggered when a new chat was started via incoming message.
Output:
name: Name of a chat or a group (if renamed manually via TimelinesAI, chat name in TimelinesAI)
New Outgoing Chat
Triggered when a new chat was started via outgoing message.
Note: This will also be triggered when Zapier action “start new chat” is used (if new chat was created as a result of that action).
Output:
name: Name of a chat or a group (if renamed manually via TimelinesAI, chat name in TimelinesAI).
New Received Message
Triggered when a new incoming message is received in any WhatsApp account connected to the workspace.
Output:
whatsapp_message_id: Unique message identifier in Timelines
chat_name: Name of a chat or a group (if renamed via Timelines, chat name in Timelines) into which the message was received
sender_name: Name of the sender of the message (usually the same as chat_name, except for group chats)
sender_phone: Phone number of the sender of the message
message_text: Plaintext message
attachment_url: Url of attachment (if present), valid for 15 minutes from the moment of triggering the event.
attachment_filename: Filename of attachment (if present)
New Sent Message
Triggered when a new incoming message is sent (including from WhatsApp Web or WhatsApp Desktop session) from any WhatsApp account connected to the workspace.
Note: This event won’t be triggered if a message was sent by means of one of Zapier “Send message” actions.
Output:
whatsapp_message_id: Unique message identifier in Timelines
chat_name: Name of a chat or a group (if renamed via Timelines, chat name in Timelines) into which the message was received
sender_name: Name of the sender of the message (registered name of the WhatsApp account used to send the message)
sender_phone: Phone number of the sender of the message
recipient_phone: Phone number of the recipient (empty if the chat is a group chat)
message_text: Plaintext message
attachment_url: Url of attachment (if present), valid for 15 minutes from the moment of triggering the event.
attachment_filename: Filename of attachment (if present)
Chat Renamed
Triggered when a chat (individual or group) is renamed in WhatsApp mobile app (usually, as a result of change in contact name).
Note: This event will not be triggered, if the chat was renamed manually via Timelines UI.
Output:
name: New name of the chat.
previous_name: Previous name of the chat.
Actions
Send Message to New Chat
Starts a new chat by sending a message to a recipient, specified by a phone number in international format. If the chat with recipient already exists, the message will be sent to that chat. The action will accept the message for sending, after verifying the correctness of the recipient's phone number format and the status of the connected WhatsApp account. Actual sending attempt will be performed asynchronously (usually within few seconds). Message status can be checked later via UI.
Starting a new chat, by sending an attachment, is not supported. If you need to send attachment to a new chat, send text message first and then use “chat_id” from previous action’s output in conjunction with “Send File to Existing Chat” action.
Input:
Whatsapp Account: WhatsApp account to be used to send the message. Can be selected from all WhatsApp accounts in the current workspace, or specified as a phone number in international format. If the selected WhatsApp account becomes disconnected or the phone number doesn’t correspond to a connected WhatsApp account, the action will fail instantly.
Phone number: Phone number of a recipient's WhatsApp account, in international format (with leading “+” and country code).
Message text: Plain message text (no markup supported). Newlines can be added via Zapier text field formatting. Text size is subject to WhatsApp's platform limit (which is currently 65,534 characters). URLs will be automatically displayed as links in the recipient’s WhatsApp client.
Output:
chat_id: ID of a chat in TimelinesAI, can be used to specify chat in “send message”/“send file” actions.
whatsapp_message_id: ID of a message, that will be sent, a unique message identifier in TimelinesAI.
whatsapp_chat_jid: WhatsApp Web API chat identifier (for internal use).
Instant failure reasons (with appropriate error message):
Specified WhatsApp account not found.
Destination phone number is in invalid format.
Message text can not be empty
Monthly mass sending quota exceeded.
Send Message to Existing Chat
Sends a message into an existing chat, that can be specified either by "chat_id" (recommended) or by combination of the WhatsApp Account and the WhatsApp chat jid. The action will accept the message for sending. Actual sending attempt will be performed asynchronously. Message status can later be checked via UI.
Input:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Whatsapp Account Phone: Phone number of WhatsApp account to be used for sending message.
Whatsapp chat jid: WhatsApp Web API chat identifier, returned as an output of previous trigger or action or lookup.
Message text: Plain message text (no markup supported). Newlines can be added via Zapier text field formatting. Text size is subject to WhatsApp platform limit (which is currently 65,534 characters). URLs will be automatically displayed as links in recipient’s WhatsApp client.
Output:
whatsapp_message_id: ID of a message that will be sent; a unique message identifier in TimelinesAI
Instant failure reasons (with appropriate error messages):
Monthly mass sending quota exceeded.
Specified Whatsapp account not found.
Specified jid not found.
Specified chat_id not found.
Send File to Existing Chat
Sends file attachment into existing chat, that can be specified either by chat_id (recommended) or by combination of WhatsApp Account and WhatsApp chat jid. Files can be sent by means of specifying a combination of downloadable publicly accessible URL and filename (can be different from the name in the URL).
Note: Supported file size is limited to 2 Megabytes (this restriction is shared with other Mass Sending and Automation options on TimelinesAI and doesn’t apply to sending messages manually via UI of TimelinesAI, where files up to 100 Megabytes can be sent).
At the time of sending, the file will be downloaded and cached for subsequent sending attempts. The action will accept the message for sending, however, the availability or size of the file will not be checked at this time. Actual sending attempt will be performed asynchronously and may fail due to inability to invalid the file URL or size. Message status can later be checked via UI.
Input:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Whatsapp Account Phone: Phone number of WhatsApp account to be used for sending message.
Whatsapp chat jid: WhatsApp Web API chat identifier, returned as an output of previous trigger or action or lookup.
Attachment URL: Downloadable, publicly accessible URL.
Name of attached file: The name of the file, as received by the recipient.
Output:
whatsapp_message_id: ID of a message, that will be sent, a unique message identifier in TimelinesAI
Instant failure reasons (with appropriate error message):
Monthly mass sending quota exceeded.
Specified Whatsapp account not found.
Specified jid not found.
Specified chat_id not found.
Attachment URL is invalid.
Searches
Find Chat
Searches for a chat (including group chats) and fetches its details. Same output is returned, as for “New Incoming Chat” trigger. Only one search field should be specified:
Chat Id: ID of a chat in TimelinesAI, returned as an output of previous trigger or action or lookup.
Name: Name of a chat as appears in TimelinesAI (corresponds to the name of the chat as appears in WhatsApp Mobile App, unless renamed in TimelinesAI).
Phone: Phone number in international format (with leading “+” and country code), that specifies the second party in the chat (not supported for group chats)
Find WhatsApp Account
Searches for a WhatsApp Account in the current TimelinesAI workspace and fetches its details. Same output is returned, as for “Whatsapp Accounts” trigger. Only one search field should be specified:
Phone: Phone number in international format (with leading “+” and country code), that corresponds to a WhatsApp account connected in the current workspace.
Email: Registration email address of TimelinesAI user, belonging to the current workspace, whose WhatsApp account is to be searched for.
Updated on: 06/12/2023
Thank you!