Inbound Webhook Integration

Table of Contents

With proper configuration, TimelinesAI can enable your team to send Whatsapp messages from the tools you’re already using: CRM, recruitment systems, etc. or even automate the replies.

“Send message” Event

It is possible to tell Timelines to send a message. The message will be sent to a contact specified by contact name (can be group name) or the phone number. It is also possible to specify particular account (if multiple accounts are connected to the workspace) to use for sending the message. Please find format requirements of the message below.

In order to setup the integration, a workspace owner should navigate to “Integration / Inbound” screen and generate new URL. The external system should post message in specific format (see details below) to that URL.

Limitations

  • Attachments sending is not supported at this time. Use UI instead to send attachments.
  • Multiple contacts cannot be specified per message.
  • There will be no error response, if contact name or phone number are invalid. The message will still show up in Timelines UI in a any case, where it’s sending / read status can be checked manually.

Rate limiting

  • Messages will be sent with random delay of 200 to 2000 ms between each two messages (internal anti-abuse measure).
  • Message sending is rate limited to 10 messages / minute and 1000 messages / day to prevent abuse. Webhook URL will respond with 429 status code if this limit is exceeded. The client will have to resend rejected messages via the Webhook at later time.

Available actions in UI

  • “Webhook enabled” – allows to disable the webhook without removing it entirely
  • “Event” – right now there’s only one selection: “Send message”
  • “Generate new URL” – will create a new unique URL, that will accept notifications. Previous URL will be discarded.
  • “Last sending attempts” – summary of last attempts to notify the webhook (reload the page to refresh the list)
  • “Download log” – a details log of 100 last attempts, in json format, with request payload and sending status details.

Webhook request format

The Webhook accepts data in JSON format, by means of POST request.

The following data items are mandatory:

  • “action” – currently, only one possible value “send” is supported
  • “text” – a plain text UTF-8 encoded message to be sent (no markdown supported, except “\n” line separator)
  • one of the following options to specify the recipient:
    “phone” – a phone number formatted according to international phone number standard: [+][country code][area code][local phone number] (for example: +14151231234)
    “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.
    “chat_name” – an exact name of the chat as as appears in TimelinesAI. This supports sending messages to a group.

The following data items are optional:

  • “whatsapp account phone” – specifies the whatsapp account to usе for sending (for example, if multiple accounts are connected in the workspace). If omitted, the most recently connected active Whatsapp account in the workspace will be used.

Response

In case of success (the request was validated and accepted for sending), the Webhook will respond with HTTP status 200 and JSON:

{
"status": "success",
"data": {}
}

In case of error, which may include the following:

  • Webhook URL disabled
  • Malformed JSON
  • Invalid chat_id

the Webhook will respond with HTTP status 40X and JSON with details of the error, for example:
{
"status": 404,
"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 via default WA account to a chat (or group) specified by id

{
"action": "send", 
"chat_id": "77234"
"text": "lorem ipsum"
}

Example 3 – sending a message via default WA account to a chat (or group) specified by a name

{
"action": "send", 
"chat_name": "John Doe and his friends"
"text": "lorem ipsum"
}

Latest posts by admin (see all)