Inbound Webhook Integration
TimelinesAI allows you to automate sending WhatsApp messages in response to events or actions in tools you're already using: CRM, Support and Recruitment systems, etc.
It's possible to instruct TimelinesAI to send a message (with or without file attachment) to a specific contact (or a group chat). If multiple WhatsApp accounts are connected in your workspace, it is also possible to specify a particular WhatsApp account to use for sending the message.
In order to setup the integration, a workspace owner should navigate to Webhooks → Inbound Webhooks and generate new URL. The external system should post message in specific format (see details below) to that URL.
Maximum attachment size is 2 MB.
There is no immediate validation of recipient's phone number format or connection to WhatsApp. Navigate to Timelines UI to verify "sending/read" status of messages.
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 webhook 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.
Sending a message consumes 1 unit of mass sending quota.
Sending a message with non-empty text and attachment consumes 2 units of mass sending quota.
If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), mass sending quota will be restored (usually within a couple of hours).
Messages will be sent with random delay of about 2 seconds between each two messages (to avoid WhatsApp spam detection mechanisms).
If you enable webhooks with frequency of less than 2 seconds, messages be queued and sent out with a delay. Each queued message will consume a mass sending unit, so the number of queued messages cannot exceed the available mass sending quota.
“Webhook enabled”: Allows to disable the webhook without removing it entirely
“Generate new URL”: Will create a new unique URL, that will accept notifications. Previous URL will no longer be available
“Last sending attempts”: Status of last webhook activation attempts
“Download log”: A detailed log of 100 last activation attempts, helpful to troubleshoot formatting issues.
The Webhook accepts data in JSON format, by means of POST request.
"action" (mandatory): Currently, only one possible value "send" is supported
"text" (mandatory): A plain text UTF-8 encoded message to be sent (no markdown supported, except "\n" line separator), can be left empty, if file is specified.
"file_url" (optional): A publicly accessible URL of a file that will be downloaded and sent as an attachment.
"file_name" (optional): A name for the attachment (must be provided, if URL is specified).
Recipient can be specified by providing one of the following parameters:
"chat_id": An ID of the chat as appears in TimelinesAI (can be found in the URL of the chat page, or in the payload of outbound webhook). This supports sending messages to a group.
"jid": A WhatsApp JID that specifies contact or group
"phone": A phone number, formatted according to international phone number standard, i.e.: [+][country code][area code][local phone number] (for example: +14151231234)
"chat_name": An exact name of the chat as as appears in TimelinesAI
If multiple WhatsApp accounts are connected in the workspace, use the following additional parameter to specify WhatsApp account to be used:
"whatsapp account phone" (optional): Specifies (as a phone number, in international format) the WhatsApp account to usе for sending. If omitted, the most recently connected active WhatsApp account in the workspace will be used for sending.
Note: if "chat_id" parameter is specified, "whatsapp account phone" will be disregarded, because each chat is already connected to a specific WhatsApp account.
In case of success (the request was validated and accepted for sending), the Webhook will respond with HTTP status 200 and JSON, containing message_id of the created message:
{
"status": "success",
"data": {
"message_id": "wa_backend:3EB09FCC85FE99662E46"
}
}
In case of error, the Webhook will respond with HTTP status 40X and JSON with details of the error, for example:
{
"status": 40X,
"data": {},
"message": "Webhook not found"
}
Example 1: Sending a message via specific WA account to a specific phone number:
{
"action": "send",
"whatsapp account phone" : "+15105566777",
"phone": "+14151231234",
"text": "lorem ipsum"
}
Example 2: Sending a message with text and attachment to a chat (or group) specified by id:
{
"action": "send",
"chat_id": "77234",
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
“Send message” Event
It's possible to instruct TimelinesAI to send a message (with or without file attachment) to a specific contact (or a group chat). If multiple WhatsApp accounts are connected in your workspace, it is also possible to specify a particular WhatsApp account to use for sending the message.
In order to setup the integration, a workspace owner should navigate to Webhooks → Inbound Webhooks and generate new URL. The external system should post message in specific format (see details below) to that URL.
Limitations
Maximum attachment size is 2 MB.
There is no immediate validation of recipient's phone number format or connection to WhatsApp. Navigate to Timelines UI to verify "sending/read" status of messages.
Sending Files via Inbound Webhooks
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 webhook 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.
Credit Utilization
Sending a message consumes 1 unit of mass sending quota.
Sending a message with non-empty text and attachment consumes 2 units of mass sending quota.
If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), mass sending quota will be restored (usually within a couple of hours).
Message sending rate
Messages will be sent with random delay of about 2 seconds between each two messages (to avoid WhatsApp spam detection mechanisms).
If you enable webhooks with frequency of less than 2 seconds, messages be queued and sent out with a delay. Each queued message will consume a mass sending unit, so the number of queued messages cannot exceed the available mass sending quota.
Webhook configuration and actions
“Webhook enabled”: Allows to disable the webhook without removing it entirely
“Generate new URL”: Will create a new unique URL, that will accept notifications. Previous URL will no longer be available
“Last sending attempts”: Status of last webhook activation attempts
“Download log”: A detailed log of 100 last activation attempts, helpful to troubleshoot formatting issues.
Webhook request format
The Webhook accepts data in JSON format, by means of POST request.
"action" (mandatory): Currently, only one possible value "send" is supported
"text" (mandatory): A plain text UTF-8 encoded message to be sent (no markdown supported, except "\n" line separator), can be left empty, if file is specified.
"file_url" (optional): A publicly accessible URL of a file that will be downloaded and sent as an attachment.
"file_name" (optional): A name for the attachment (must be provided, if URL is specified).
Recipient can be specified by providing one of the following parameters:
"chat_id": An ID of the chat as appears in TimelinesAI (can be found in the URL of the chat page, or in the payload of outbound webhook). This supports sending messages to a group.
"jid": A WhatsApp JID that specifies contact or group
"phone": A phone number, formatted according to international phone number standard, i.e.: [+][country code][area code][local phone number] (for example: +14151231234)
"chat_name": An exact name of the chat as as appears in TimelinesAI
If multiple WhatsApp accounts are connected in the workspace, use the following additional parameter to specify WhatsApp account to be used:
"whatsapp account phone" (optional): Specifies (as a phone number, in international format) the WhatsApp account to usе for sending. If omitted, the most recently connected active WhatsApp account in the workspace will be used for sending.
Note: if "chat_id" parameter is specified, "whatsapp account phone" will be disregarded, because each chat is already connected to a specific WhatsApp account.
Webhook Response
In case of success (the request was validated and accepted for sending), the Webhook will respond with HTTP status 200 and JSON, containing message_id of the created message:
{
"status": "success",
"data": {
"message_id": "wa_backend:3EB09FCC85FE99662E46"
}
}
In case of error, the Webhook will respond with HTTP status 40X and JSON with details of the error, for example:
{
"status": 40X,
"data": {},
"message": "Webhook not found"
}
Examples
Example 1: Sending a message via specific WA account to a specific phone number:
{
"action": "send",
"whatsapp account phone" : "+15105566777",
"phone": "+14151231234",
"text": "lorem ipsum"
}
Example 2: Sending a message with text and attachment to a chat (or group) specified by id:
{
"action": "send",
"chat_id": "77234",
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
Updated on: 16/01/2023
Thank you!