Outbound Integration

Table of Contents

Outbound Integration:
Whatsapp > CRM and your other systems

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 in any connected whatsapp account in a workspace. This includes whatsapp messages sent via Whatsapp Mobile App or from within Timelines.

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 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 point in conversations in TimelinesAI), but you can implement your own formatting using the data provided with the webhook.

Screen Shot 2021 11 23 at 12 06 26
Bundle of messages sent via a webhook

To setup the integration using Outbound Webhooks:

  1. Navigate to the Webhooks menu in your TimelinesAI account
  2. Select Outbound tab.

Screen Shot 2021 11 23 at 11.47.21

Your 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 timelines (“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 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: currently, only text and emoji messages are supported. Messages that contain attachments will be skipped.

Errors and troubleshooting

To ensure correct operation of the integration, if more than 10 consecutive errors from the receiving end will be 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 in 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 whatsapp account (and workspace teammate, that connected the account), through which the message was received or sent
    • “phone” – the WA account’s phone number
    • “full_name” – the WA account owner’s full name, as registered in Timelines
    • “email” – the WA account owner’s email, as registered in Timelines
  • “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 Timelines)
    • “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 TimelinesUI
    • “chat_id” – the ID of the chat in TimelinesUI (can be used to construct chat URL or with inbound webhooks)
    • “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)
    • “receiver” – 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 receiver (or empty for group chat)
    • “text” – message text (plaintext)
  • “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”

            },

            “receiver”: {

            “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”

            },

            “receiver”: {

            “full_name”: “Jane Smith”,

            “phone”: “+972550000000”

            },

            “text”: “lorem ipsum”

        }

    ],

    “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 whatsapp account (and workspace teammate, that connected the account), through which the message was received or sent
    • “phone” – the WA account’s phone number
    • “full_name” – the WA account owner’s full name, as registered in Timelines
    • “email” – the WA account owner’s email, as registered in Timelines
  • “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 Timelines)
    • “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 TimelinesUI
    • “chat_id” – the ID of the chat in TimelinesUI (can be used to construct chat URL or with inbound webhooks)
    • “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 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)
    • “receiver” – 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 receiver (or empty for group chat)
    • “text” – message text (plaintext)

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”

            },

            “receiver”: {

            “full_name”: “Jane Smith”,

            “phone”: “+972550000000”

            },

            “text”: “lorem ipsum”

        }

}

Latest posts by admin (see all)