Skip to main content

Webhooks Integration on TimelinesAI

TimelinesAI webhooks notify external systems (that you have connected through Webhooks endpoints) about events happening in a TimelinesAI workspace in real time: new messages and chats, delivery and read receipts, edits and deletions, calls, chat assignments and WhatsApp account status. Use them to keep a CRM, a spreadsheet, or a Make, Zapier, n8n or any other external system in sync without polling.

Info: For developers: event payloads, examples and the full event list are in the webhook technical documentation. You can also create and manage webhooks with the Public API.

Webhooks are available on paid plans and during the trial. A workspace can have up to 10 endpoints. If you need more, contact support about the add-on.

How to subscribe to a webhook event

  1. Open Integrations → Webhooks in TimelinesAI.

  2. Click Add endpoint.

  3. Paste the Endpoint URL, the address that should receive the events. For example, a Make or Zapier webhook URL or your own server.

  4. Choose the Event type (see Webhook events).

  5. Leave Endpoint activated on and click Add endpoint.

  6. You're all set. Each time the event happens, TimelinesAI sends an HTTP POST request with a JSON body to your URL. The exact payload of each event is in the webhook technical documentation.

Note: each endpoint receives one event type. To receive several events, add one endpoint per event. Your endpoint should reply with a success status within 5 seconds. If it keeps failing, workspace owners and admins get a warning (see Endpoint warnings).

Webhook event types

Message and chat events cover every WhatsApp number in your workspace, whether the message was sent from the phone, another linked device, WhatsApp Web or TimelinesAI. Incoming and outgoing are relative to the WhatsApp number as a whole. Payload examples for every event are in the webhook reference.

Message events

  • message:new: a new message, incoming or outgoing.

  • message:received:new: a new incoming message.

  • message:sent:new: a new outgoing message.

  • message:reaction: a reaction was set on a message or removed.

  • message:delivered: an outgoing message reached the contact's phone. Sent once per message. Incoming, failed and pending messages don't send it.

  • message:read: the contact read an outgoing message. Sent once per message, after message:delivered.

  • message:edited: the text or caption of a message was edited, by you or the contact. Includes the new and the previous text.

  • message:deleted: a message was deleted for everyone, from your phone, another linked device or by the contact. deleted_by_me says who deleted it. Delete for me doesn't send it. TimelinesAI itself can't delete messages for everyone, so this event always comes from a phone or linked device.

Note: message:delivered, message:read, message:edited, message:deleted and chat:renamed work for WhatsApp numbers connected by QR code. Their payloads are compact: the message or chat ID, what changed and when. To get the chat, the WhatsApp number or the message text, call GET /messages/{uid} or GET /chats/{id} in the Public API.

Chat events

  • chat:new: a new 1-to-1 or group chat.

  • chat:incoming:new: a new 1-to-1 chat started by the contact.

  • chat:outgoing:new: a new 1-to-1 chat started from your number.

  • chat:responsible:assigned: a chat was assigned or reassigned to a teammate.

  • chat:responsible:unassigned: a chat was unassigned.

  • chat:renamed: the chat's name changed. Includes the new and the previous name, and the reason: renamed in TimelinesAI, group subject changed, contact name added or changed in the phone book, WhatsApp profile name changed, or business name set. Renames made in TimelinesAI are sent for every number, including WABA numbers.

Call events

  • call:incoming:missed: an incoming WhatsApp call was missed.

  • call:incoming:ended: an incoming WhatsApp call ended.

  • call:outgoing:ended: an outgoing WhatsApp call ended.

WhatsApp account events

  • whatsapp:account:connected: a WhatsApp number was connected or reconnected.

  • whatsapp:account:disconnected: a WhatsApp number was disconnected from the workspace.

  • whatsapp:account:suspended: message syncing was paused, for example after a subscription was cancelled or downgraded.

  • whatsapp:account:resumed: message syncing resumed.

  • whatsapp:account:reachout_timelock:active: WhatsApp started restricting the number from messaging people it hasn't spoken to before. Existing conversations keep working.

  • whatsapp:account:reachout_timelock:cleared: that restriction was lifted.

Tip: We recommend subscribing to both disconnected and suspended so you know whenever messaging stops.

WhatsApp Business API (WABA) events

WABA numbers have their own events. The message, chat and call events above don't fire for WABA numbers, except chat:renamed for renames made in TimelinesAI.

  • Messages: waba:message:received, waba:message:delivered, waba:message:read, waba:message:failed

  • Chats: waba:chat:incoming, waba:chat:outgoing, waba:chat:assigned, waba:chat:unassigned, waba:chat:closed, waba:chat:reopened

  • Account: waba:account:active, waba:account:disabled, waba:account:disconnected

  • Templates: waba:template:approved, waba:template:rejected, waba:template:disabled

Manage webhooks

All created endpoints are listed in Integrations → Webhooks. For each endpoint you can see its URL, event type, number of activations, error rate, last response, who edited it last and its status.

  • To edit: In Actions, click Edit (pencil icon). Change the Endpoint URL or Event type and click Update endpoint.

  • To activate/deactivate: open Edit (pencil icon), switch off Endpoint activated and click Update endpoint. Switch it back on to resume.

  • To delete: In Actions, click Delete, then Delete webhook. This can't be undone.

Download logs

  • Download Log (on each endpoint): the latest calls to that endpoint and the response your system returned. Up to 1,000 calls are kept, for up to 10 days.

  • Download webhooks change log: who created, edited, activated or deleted endpoints, and when.

Endpoint warnings

A call counts as failed when your endpoint doesn't reply with a 2xx status within 5 seconds. If an endpoint fails 5 times in a row, or 30% or more of its last 50 calls fail, or 40% or more of them are slow, workspace owners and admins get an email and an in-app notification. The endpoint stays active and TimelinesAI keeps sending events, so fix the endpoint or deactivate it yourself. See Troubleshooting Webhooks.

Troubleshooting

Start with the endpoint's Error rate and Last response in the list, then download its log to see the exact error your system returned. For step-by-step help, see Troubleshooting Webhooks.

Use webhooks with automation tools

FAQ

The same message on several WhatsApp numbers

When several of your numbers see the same message, for example in a group they are all members of, each number gets its own copy with its own message_uid. Message events also include whatsapp_message_id, WhatsApp's own ID for the message. It is the same on every copy, so you can use it to remove duplicates.

Webhooks on an unpaid plan

On an unpaid plan you can still open the Webhooks page, see your endpoints and download logs. You can't add, edit or delete endpoints, and no events are sent until you upgrade.

Related Articles
Did this answer your question?