> For the complete documentation index, see [llms.txt](https://docs.athenachat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.athenachat.ai/api-reference/en/guides/webhooks.md). # Webhooks Receive new messages, completed tasks and status changes from Athena AI Athena AI can send events about a channel's chats to your server: new messages, completed agent tasks and task status changes. Webhooks work for every channel — Telegram, WhatsApp, Instagram, Facebook, the Chat Widget and the [API channel](/api-reference/en/guides/api-channel.md). ## Set up a webhook **Action:** In [your Athena account](https://app.athenachat.ai), open **Channels**, open the settings of the channel and go to the **Webhook** tab. Enter your endpoint in **Webhook URL**, click **Webhook test** and save the settings. **Result:** Athena sends a sample `new_messages` event to your URL, and then sends real events of this channel as they happen. Each channel has its own webhook URL. {% hint style="info" %} With a webhook URL set, you can turn on **Disable agent responses** on the same tab. The AI agent stops answering in this channel, but customer messages keep arriving at your webhook, so you can answer them in your own system. {% endhint %} *** ## Delivery * Athena sends a `POST` request with a JSON body and the headers `Content-Type: application/json` and `User-Agent: API-Gate-Webhook/1.0`. * Your endpoint must respond with a `2xx` status within **2 seconds**. Save the event and process it in the background so that you respond quickly. * If delivery fails, Athena retries: **3 attempts** in total, with growing pauses between them (2 and 4 seconds). * Events can arrive more than once and out of order. Make your handler idempotent: deduplicate messages by `messages[].id` and status changes by `eventId`. ## Secure your endpoint Athena doesn't sign webhook requests, so make your endpoint hard to abuse: * Use HTTPS. * Include a long random secret in the URL, for example `https://example.com/athena-webhook/3f9c1e7a5b…`, and reject requests to any other path. * Treat event data as untrusted input. To check an event, look the chat up in the [chat list](/api-reference/en/endpoints/chats.md#list-chats) with your API key. *** ## Events The `event` field tells you the type of the event. | Event | When it's sent | | ------------------------------------------------- | ------------------------------------------------------------ | | [`new_messages`](#new_messages) | A customer writes, or Athena sends a message to the customer | | [`task_trigger`](#task_trigger) | The AI agent completes its task and the task trigger fires | | [`dialog_status_changed`](#dialog_status_changed) | The task status of a chat changes between done and not done | ### new\_messages Sent for every message a customer writes, and for every message Athena delivers to the customer — the AI agent's replies and messages sent by your team from the **Inbox**. ```json { "event": "new_messages", "chat": { "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "name": "Emma Clark", "uniqueId": "348148573_0252558b-0280-4db0-a159-734e1821fcac", "externalChatId": "348148573", "channelName": "telegram" }, "messages": [ { "id": "c2e2e738-7b81-4b6d-a5a2-be8f1f4acae5", "role": "user", "senderName": "Emma Clark", "attachments": [ { "contentType": "image/jpeg", "url": "https://storage.googleapis.com/…/photo.jpg", "fileSize": 32458, "name": "photo.jpg" } ], "text": "Here is a photo of the damaged box", "createdAt": "2026-10-09T09:40:57.000Z" } ], "settings": { "behavior": "Be friendly and brief.", "role": "Customer support agent of a furniture store", "task": "Answer questions about delivery and take orders", "greeting": "Hello! How can I help?", "isActive": true, "aiLang": "en" }, "timestamp": "2026-10-09T09:40:57.420Z" } ``` ### task\_trigger Sent when the AI agent decides that its task is complete and the task trigger fires. `message` is the customer's last message, and `summary` is a short summary of the conversation (it can be `null`). ```json { "event": "task_trigger", "chat": { "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "name": "Emma Clark", "uniqueId": "348148573_0252558b-0280-4db0-a159-734e1821fcac", "externalChatId": "348148573", "channelName": "telegram" }, "message": { "id": "9d1b7c3e-2a4f-4c8e-b6d0-5e3a8f1c7b29", "role": "user", "senderName": "Emma Clark", "attachments": [], "text": "Great, please book delivery for Saturday.", "createdAt": "2026-10-09T09:45:03.000Z" }, "summary": "The customer ordered a sofa and asked for Saturday delivery.", "settings": { "behavior": "Be friendly and brief.", "role": "Customer support agent of a furniture store", "task": "Answer questions about delivery and take orders", "greeting": "Hello! How can I help?", "isActive": true, "aiLang": "en" }, "timestamp": "2026-10-09T09:45:04.120Z" } ``` ### dialog\_status\_changed Sent when the task status of a chat actually changes: from not done to done or back. Setting the status a chat already has doesn't send an event. The status can be changed by the task trigger, by your team in the **Inbox**, or through the API ([done](/api-reference/en/endpoints/chats.md#mark-the-task-as-done), [undone](/api-reference/en/endpoints/chats.md#mark-the-task-as-not-done)). ```json { "event": "dialog_status_changed", "eventId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-10-09T09:45:04.420Z", "chat": { "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "name": "Emma Clark", "uniqueId": "348148573_0252558b-0280-4db0-a159-734e1821fcac", "externalChatId": "348148573", "channelName": "telegram" }, "settings": { "behavior": "Be friendly and brief.", "role": "Customer support agent of a furniture store", "task": "Answer questions about delivery and take orders", "greeting": "Hello! How can I help?", "isActive": true, "aiLang": "en" }, "status": { "type": "task", "previous": "not_done", "current": "done", "changedAt": "2026-10-09T09:45:04.000Z", "source": { "type": "trigger", "operatorEmail": null } } } ``` *** ## Fields ### chat | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Chat ID — use it with the [chat](/api-reference/en/endpoints/chats.md) and [tag](/api-reference/en/endpoints/tags.md) endpoints | | `name` | string | Chat name, usually the customer's name | | `uniqueId` | string | Chat key — use it to [ban or unban](/api-reference/en/endpoints/chats.md#ban-a-chat) the chat | | `externalChatId` | string | Chat ID in the messenger, or your `externalChatId` for the API channel. May be absent | | `channelName` | string | Channel type: `telegram`, `whatsapp`, `instagram`, `facebook`, `viber`, `widget`, `custom` | ### messages\[] and message | Field | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------- | | `id` | string | Message ID — use it for [answer feedback](/api-reference/en/endpoints/answer-feedback.md) | | `role` | string | `user` — the customer; `assistant` — the AI agent or your team | | `senderName` | string | Sender's name. Can be `null` | | `text` | string | Message text | | `attachments` | array | Files: `contentType`, `url`, `fileSize` (bytes) and `name` | | `createdAt` | string | When the message was created | ### settings The AI agent settings of the channel at the time of the event. | Field | Type | Description | | ---------- | ------- | --------------------------------------------------------------------------------------------------------------- | | `behavior` | string | Behavior instructions | | `role` | string | AI agent's role | | `task` | string | AI agent's task | | `greeting` | string | Greeting | | `isActive` | boolean | Whether the agent is turned on in the channel settings. It isn't the task status and doesn't show a paused chat | | `aiLang` | string | Agent's language | ### status (dialog\_status\_changed) | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------------------------------------------------- | | `type` | string | Always `task` | | `previous`, `current` | string | `done` or `not_done` | | `changedAt` | string | When the status changed | | `source.type` | string | Who changed it: `trigger` — the task trigger, `manual` — your team in Athena, `api` — the API | | `source.operatorEmail` | string | Email of the team member for `manual`; `null` otherwise | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.athenachat.ai/api-reference/en/guides/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.