PublicAPI Webhooks

PublicAPI Webhooks deliver real-time notifications to your application when events occur in your TimelinesAI workspace. Instead of polling the API for changes, your server receives instant HTTP POST callbacks whenever messages arrive, chats are created, accounts change status, and more.

How it works

Use POST /webhooks to subscribe to an event type and provide your endpoint URL

An event occurs

A new message arrives, a chat is created, or an account status changes

You receive a POST request

TimelinesAI sends the event payload to your endpoint in real-time

Acknowledge receipt

Your server responds with a 2xx status within 5 seconds

Available events

Message events

Real-time notifications for all message activity in your workspace.

Event	Trigger	Description
`message:new`	Any new message	Fires for both incoming and outgoing messages
`message:received:new`	Incoming message	A customer or contact sends you a message
`message:sent:new`	Outgoing message	A message you sent is processed
`message:reaction`	Reaction set or cleared	An emoji reaction is added to or removed from a message

Chat events

Track conversation lifecycle and assignment changes.

Event	Trigger	Description
`chat:new`	New chat (any)	A new direct or group chat appears
`chat:incoming:new`	New incoming chat	A contact initiates a conversation with you
`chat:outgoing:new`	New outgoing chat	You start a new conversation
`chat:responsible:assigned`	Chat reassigned	A chat is assigned to a team member
`chat:responsible:unassigned`	Chat unassigned	A chat’s assignment is removed

Call events

Receive call history events for WhatsApp voice and video calls. Fired only after the call ends.

Event	Trigger	Description
`call:incoming:missed`	Incoming call missed	The recipient never picked up before the caller ended
`call:incoming:ended`	Incoming call ended	Status `Answered` (call was picked up) or `Rejected` (actively declined)
`call:outgoing:ended`	Outgoing call ended	Status `Ended` (completed), `No Answer`, or `Rejected`

WhatsApp account events

Monitor the connection status of your WhatsApp numbers.

Event	Trigger	Description
Account reconnected	WhatsApp reconnects	A previously disconnected account comes back online
Account disconnected	WhatsApp disconnects	An account loses its connection
Syncing suspended	Syncing paused	Message syncing stops (e.g., subscription change)
Syncing resumed	Syncing restarted	Message syncing resumes after suspension

Use case examples

Auto-reply chatbot

Build an automated responder that handles common questions instantly.

Subscribe to message:received:new
Parse the incoming message text for keywords
Send an appropriate reply using POST /chats/{id}/messages
Escalate complex queries by assigning the chat to a human agent

Real-time CRM sync

Keep your CRM updated the moment a conversation happens.

Subscribe to message:received:new and chat:new
On new chat — create a lead/contact in your CRM
On new message — log the interaction as an activity
Use chat assignment events to sync agent ownership

Team notification system

Alert your team in Slack, Teams, or email when important events happen.

Subscribe to message:received:new and chat:responsible:assigned
Filter events by label or content keywords
Forward the notification to Slack, Teams, or a custom dashboard
Monitor WhatsApp account events to alert admins about disconnections

Delivery tracking & analytics

Track message delivery rates and response times.

Subscribe to message:sent:new to track outgoing deliveries
Subscribe to message:received:new to measure response times
Aggregate data to build delivery rate dashboards
Alert on anomalies like high failure rates or unusual activity

Webhook payload example

When a new message arrives, your endpoint receives a payload like:

{
  "event_type": "message:received:new",
  "chat": {
    "full_name": "John Doe",
    "chat_url": "https://app.timelines.ai/chat/123456/messages/",
    "chat_id": 123456,
    "is_group": false,
    "phone": "+15551234567",
    "responsible_name": "Agent Brown",
    "responsible_email": "agent-brown@example.com"
  },
  "whatsapp_account": {
    "full_name": "Agent Brown",
    "email": "agent-brown@example.com",
    "phone": "+15559876543"
  },
  "message": {
    "text": "Hi, here is the signed contract",
    "direction": "received",
    "origin": "WhatsApp",
    "timestamp": "2024-01-15 10:30:00 +0200",
    "message_uid": "a5bbb005-37f2-402c-96fa-e479a2e09b02",
    "reply_to_uid": "c7ec509d-0171-1ead-a84b-c6943a644768",
    "sender": {
      "full_name": "John Doe",
      "phone": "+15551234567"
    },
    "recipient": {
      "full_name": "Agent Brown",
      "phone": "+15559876543"
    },
    "attachments": [
      {
        "temporary_download_url": "https://example.s3.amazonaws.com/att/...",
        "filename": "contract.pdf",
        "size": 1234567,
        "mimetype": "application/pdf"
      }
    ]
  }
}

Attachments — The temporary_download_url for each attachment is a pre-signed URL valid for 15 minutes from the moment the webhook is delivered. Download or forward attachment files immediately upon receiving the webhook. After expiration, you can retrieve the file again using the Public API.

Reactions — Emoji reactions on messages are delivered via the dedicated message:reaction event, not on message:new. The payload includes the full current reactions map for the message (emoji → integer count) along with the action (set or clear) and the reactor’s identity.

Endpoint requirements

Your webhook endpoint must:

Be publicly accessible (no localhost in production)

Use HTTPS

Respond with a 2xx status within 5 seconds

Accept POST requests with JSON body

Retry policy

If your endpoint returns a non-2xx status or the request times out, TimelinesAI retries the delivery 2 additional times (3 attempts total). If all attempts fail, the webhook’s errors_counter increments.

Best practices

Respond immediately — return 200 first, then process the event asynchronously
Handle duplicates — use message_uid to deduplicate events that may be delivered more than once
Monitor errors — check errors_counter on your webhooks to catch delivery failures early
Use a queue — for high-volume workspaces, push events to a message queue (Redis, SQS, RabbitMQ) and process separately

If your endpoint consistently fails, TimelinesAI will notify the workspace owner via email. Fix endpoint issues promptly to avoid missing events.

Managing webhooks

Webhook subscriptions are managed via the Public API:

Action	Endpoint
List all	`GET /webhooks`
Create	`POST /webhooks`
Get details	`GET /webhooks/{id}`
Update	`PUT /webhooks/{id}`
Delete	`DELETE /webhooks/{id}`

See the Webhooks guide for setup instructions and code examples.

Next steps

Webhooks guide

Step-by-step setup with code examples

Public API

Explore all API endpoints

Overview

messages

whatsapp_accounts

chats

calls

PublicAPI Webhooks Overview

PublicAPI Webhooks

How it works

Available events

Message events

Chat events

Call events

WhatsApp account events

Use case examples

Webhook payload example

Endpoint requirements

Retry policy

Best practices

Managing webhooks

Next steps

Webhooks guide

Public API

​PublicAPI Webhooks

​How it works

​Available events

​Message events

​Chat events

​Call events

​WhatsApp account events

​Use case examples

​Webhook payload example

​Endpoint requirements

​Retry policy

​Best practices

​Managing webhooks

​Next steps

Webhooks guide

Public API

PublicAPI Webhooks

How it works

Available events

Message events

Chat events

Call events

WhatsApp account events

Use case examples

Webhook payload example

Endpoint requirements

Retry policy

Best practices

Managing webhooks

Next steps