> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PublicAPI Webhooks Overview

> Receive real-time notifications for WhatsApp events in your workspace

# 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

<Steps>
  <Step title="Register a webhook">
    Use `POST /webhooks` to subscribe to an event type and provide your endpoint URL
  </Step>

  <Step title="An event occurs">
    A new message arrives, a chat is created, or an account status changes
  </Step>

  <Step title="You receive a POST request">
    TimelinesAI sends the event payload to your endpoint in real-time
  </Step>

  <Step title="Acknowledge receipt">
    Your server responds with a 2xx status within 5 seconds
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="Auto-reply chatbot" icon="robot">
    Build an automated responder that handles common questions instantly.

    1. Subscribe to `message:received:new`
    2. Parse the incoming message text for keywords
    3. Send an appropriate reply using `POST /chats/{id}/messages`
    4. Escalate complex queries by assigning the chat to a human agent
  </Accordion>

  <Accordion title="Real-time CRM sync" icon="arrows-rotate">
    Keep your CRM updated the moment a conversation happens.

    1. Subscribe to `message:received:new` and `chat:new`
    2. On new chat — create a lead/contact in your CRM
    3. On new message — log the interaction as an activity
    4. Use chat assignment events to sync agent ownership
  </Accordion>

  <Accordion title="Team notification system" icon="bell">
    Alert your team in Slack, Teams, or email when important events happen.

    1. Subscribe to `message:received:new` and `chat:responsible:assigned`
    2. Filter events by label or content keywords
    3. Forward the notification to Slack, Teams, or a custom dashboard
    4. Monitor WhatsApp account events to alert admins about disconnections
  </Accordion>

  <Accordion title="Delivery tracking & analytics" icon="chart-line">
    Track message delivery rates and response times.

    1. Subscribe to `message:sent:new` to track outgoing deliveries
    2. Subscribe to `message:received:new` to measure response times
    3. Aggregate data to build delivery rate dashboards
    4. Alert on anomalies like high failure rates or unusual activity
  </Accordion>
</AccordionGroup>

## Webhook payload example

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

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

<Info>
  **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.
</Info>

<Info>
  **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.
</Info>

## Endpoint requirements

Your webhook endpoint must:

<Check>Be publicly accessible (no localhost in production)</Check>
<Check>Use HTTPS</Check>
<Check>Respond with a 2xx status within 5 seconds</Check>
<Check>Accept POST requests with JSON body</Check>

## 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

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

## 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](/guides/webhooks) for setup instructions and code examples.

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks guide" icon="book" href="/guides/webhooks">
    Step-by-step setup with code examples
  </Card>

  <Card title="Public API" icon="code" href="/public-api-reference/overview">
    Explore all API endpoints
  </Card>
</CardGroup>