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, Recruitment systems, etc.

“Send message” Event

It is possible to instruct TimelinesAI to send a message (with or without file attachment) to a specific contact (can be a group). 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 “Integrations / Inbound Webhooks” screen 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.

Credit Utilization

  • Sending a message consumes 1 credit from message sending quota.
  • Sending a message with non-empty text and attachment consumes 2 credits from message sending quota.
  • If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), message 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 activate webhooks with frequency of less than 2 seconds, messages be queued and sent out with delay. Each queued message will consume a message sending credit, so the number of queued messages cannot exceed the available 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"
    }
    Table of Contents