Webhook Integration
Webhook Integration: WhatsApp → CRM and your other systems
This article applies only to version 1 (v1) of webhooks, which is now outdated. For the latest information on v2 webhooks, please refer to this article.
Share this article with your developer or use Zapier to integrate your system with WhatsApp
Setup
TimelinesAI allows to notify an external system when a new message is received or sent to any connected WhatsApp account in a workspace. This includes WhatsApp messages sent via WhatsApp Mobile App and/or from within TimelinesAI.
It’s often the case that such integration is used via some intermediary service such as Zapier, where each activation of a webhook counts towards task quota utilization.
To make the usage of tasks quota more efficient, TimelinesAI provides a possibility to aggregate multiple messages sent or received in a specific chat over the selected period of time. The messages are sent via the webhook as a single “bundle”. For your convenience, such “bundle” contains a field with the pre-formatted aggregation of messages (and a link to the section in conversations in TimelinesAI), but you can implement your own formatting using the data provided with the webhook.
To setup the integration using Webhooks:
Navigate to the Integrations section within your TimelinesAI workspace
Select the Webhooks tab
You will be presented with the following settings:
Aggregation Granularity: The messages will be aggregated and sent using the webhook according to the selection (every 1, 6, 12, 24 hours) or will be sent as soon as they appear in TimelinesAI ("Don’t aggregate")
Webhook URL: Here you need to input the actual URL that needs to be notified.
Webhook enabled: You can disable the webhook here, if you want to stop the integration.
Once a Webhook becomes enabled and some messages get sent, an activity log will be displayed (up to 10 most recent actions).
Note: file attachments are fully supported.
Errors and Troubleshooting
To ensure the correct operation of the integration, if more than 10 consecutive errors from the receiving end are encountered (any error, ranging from invalid URL to response code that is not 200), the system will automatically disable the integration. In such case, the workspace owner will receive an email notification.
In case you need to troubleshoot an error, you can download a detailed log (the link will become available at the bottom of the page), where up to 100 most recent requests will show up with all the details of the data sent and the response received.
Data Format
The data will be sent to a Webhook’s URL by means of HTTP POST request, in JSON format. The data is provided in 2 different formats, depending on the Aggregation Granularity setting, as described below.
Aggregate every X hours
Messages will be aggregated into a “bundle”. The following data will be available:
“whatsapp account”: The details of the WhatsApp account (and workspace team member, that connected the account), through which the message was received or sent
“phone”: The WhatsApp account’s phone number
“full_name”: The WhatsApp account owner’s full name, as registered in TimelinesAI
“email”: The WhatsApp account owner’s email, as registered in TimelinesAI
“chat”: The details of the chat (direct chat or group), in which the message was sent or received
“full_name”: The chat name (as appears in TimelinesAI)
“responsible_name”: The name of a teammate that is assigned as a responsible to this chat
“responsible_email”: The email of a teammate that is assigned as a responsible to this chat
“chat_url”: The URL, at which the chat can be accessed in Timelines UI
“chat_id”: The ID of the chat in Timelines UI (can be used to construct chat URL or with Public API integration)
“is_new_chat”: True, if this chat was just created, false otherwise
“is_group”: True, if this chat is a direct chat, false otherwise
“phone”: Chat’s phone number (empty for group chat)
“messages”: A list of messages, where each message object contains the following fields
“direction”: Can be “received” or “sent”
“timestamp”: Timestamp of a message, in UTC timezone
“message_id”: Internal unique ID of the message
“sender”: Details of a sender (chat’s participant) of a message
→ “full_name”: Title of a chat or teammate’s name in Timelines (if sent from within the Timelines)
→ “phone”: Phone number of the sender (or empty for group chat)
“recipient”: Details of a sender (chat’s participant) of a message
→ “full_name”: Title of a chat or teammate’s name in Timelines
→ “phone”: Phone number of the recipient (or empty for group chat)
“text”: Message text (plaintext)
“attachment” - an object describing message attachment, including the following fields
→“temporary_download_url” - a temporary download URL, valid for 15 minutes
→“filename” - name of the file
→“size” - size of the file, in bytes
→“mimetype” - mime-type of the file
“first_message_timestamp”: Timestamp of the earliest message in the bundle, in UTC timezone
“last_message_timestamp”: Timestamp of the most recent message in the bundle, in UTC timezone
"aggregation": Aggregated text of the message, in HTML format, suitable for use with CRMs or similar systems as a content for notes, including the direct link to the first message in Timelines.
Example
{
"whatsapp_account" :
{
"full_name" : "Amnon Haha",
"email" : "Amnon@acme.com",
"phone" : "+972500000000"
},
"chat":
{
"full_name": "John Doe>",
"responsible_name": "Amnon",
"responsible_email": "Amnon@acme.com",
"chat_url" : "https://app.timelines.ai/chat/10010001/messages/",
"chat_id" : "10010001",
"is_new_chat" : true,
"is_group": false,
"phone": "+97254000000"
},
"messages" :
[
{
"direction": "sent",
"timestamp": "2021-02-24T16:25:29+0000",
"message_id": "ddfskhsd76dsfs6dsd5skjsdhf",
"sender": {
"full_name": "John Doe",
"phone": "+972540000000"
},
"recipient": {
"full_name": "Jane Smith",
"phone": "+972550000000"
},
"text": "lorem ipsum"
},
{
"direction": "received",
"timestamp": "2021-02-24T16:30:29+0000",
"message_id": "ddfskhsd76dsfs6dsd5skjsdhf",
"sender": {
"full_name": "John Doe",
"phone": "+972540000000"
},
"recipient": {
"full_name": "Jane Smith",
"phone": "+972550000000"
},
"text": "lorem ipsum",
"attachment": {
"temporary_download_url": "https://acme.com/path",
"filename": "someimage.png",
"size": 128909,
"mimetype": "image/png"
}
}
],
"first_message_timestamp" : "2021-02-24T16:25:29+0000",
"last_message_timestamp" : "2021-02-24T16:30:29+0000",
"aggregation":
"from John Doe on 2021-02-24 16:25: Hi! How are you?<br/>from Jane Smith on 2021-02-24 16:30: I am fine, how are you?<br/>Click <a href='https://app.timelines.ai/permalink/77a28d55-5345-5435-8c72-3a7bcad8ded9/'>here</h> to open the conversation in TimelinesAI"
}Don’t aggregate
Each message is sent individually, as soon as it becomes available. No “bundling” takes place. The following data will be available:
“whatsapp account”: The details of the WhatsApp account (and workspace team member, that connected the account), through which the message was received or sent
“phone”: The WhatsApp account’s phone number
“full_name”: The WhatsApp account owner’s full name, as registered in TimelinesAI
“email”: The WhatsApp account owner’s email, as registered in TimelinesAI
“chat”: The details of the chat (direct chat or group), in which the message was sent or received
“full_name”: The chat name (as appears in TimelinesAI)
“responsible_name”: The name of a team member that is assigned as a responsible to this chat
“responsible_email”: The email of a team member that is assigned as a responsible to this chat
“chat_url”: The URL, at which the chat can be accessed in Timelines UI
“chat_id”: The ID of the chat in Timelines UI (can be used to construct chat URL or with Public API integration)
“is_new_chat”: True, if this chat was just created, false otherwise
“is_group”: True, if this chat is a direct chat, false otherwise
“phone”: Chat’s phone number (empty for group chat)
“message”: The details of the message
“direction”: Can be “received” or “sent”
“timestamp”: Timestamp of a message, in UTC time zone
“message_id”: Internal unique ID of the message
“sender”: Details of a sender (chat’s participant) of a message
→ “full_name”: Title of a chat or team member's name in TimelinesAI (if sent from within the TimelinesAI)
→ “phone”: Phone number of the sender (or empty for group chat)
“recipient”: Details of a sender (chat’s participant) of a message
→ “full_name”: Title of a chat or team member's name in TimelinesAI
→ “phone”: Phone number of the recipient (or empty for group chat)
“text”: Message text (plaintext)
“attachment” - an object describing message attachment, including the following fields
→ “temporary_download_url” - a temporary download URL, valid for 15 minutes
→ “filename” - name of the file
→ “size” - size of the file, in bytes
→ “mimetype” - mime-type of the file
Example
{
"whatsapp_account" :
{
"full_name" : "Amnon Haha",
"email" : "Amnon@acme.com",
"phone" : "+972500000000"
},
"chat":
{
"full_name": "John Doe>",
"responsible_name": "Amnon",
"responsible_email": "Amnon@acme.com",
"chat_url" : "https://app.timelines.ai/chat/10010001/messages/",
"chat_id" : "10010001",
"is_new_chat" : true,
"is_group": false,
"phone": "+97251111111"
},
"message" :
{
"direction": "sent",
"timestamp": "2021-02-24T06:25:29+0000",
"message_id": "ddfskhsd76dsfs6dsd5skjsdhf",
"sender": {
"full_name": "John Doe",
"phone": "+972540000000"
},
"recipient": {
"full_name": "Jane Smith",
"phone": "+972550000000"
},
"text": "lorem ipsum",
"attachment": {
"temporary_download_url": "https://acme.com/path",
"filename": "someimage.png",
"size": 128909,
"mimetype": "image/png"
}
}
}Updated on: 12/06/2024
Thank you!