> 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/endpoints/chats.md).

# Chats

List chats, mark them as read or unread, set the task status and block spam

## List chats

`GET /chats/chat`

Returns the chats of your account, newest activity first.

### Query parameters

| Parameter       | Type    | Description                                                                                                                 |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `limit`         | integer | Number of chats to return. Default: `500`                                                                                   |
| `offset`        | integer | Number of chats to skip, for pagination. Default: `0`                                                                       |
| `channelName`   | string  | Only chats of this channel type: `telegram`, `whatsapp`, `instagram`, `facebook`, `viber`, `widget`, `custom` (API channel) |
| `channelId`     | string  | Only chats of this channel                                                                                                  |
| `tag`           | string  | Only chats with this tag. Pass several tags separated by commas to get chats that have all of them                          |
| `complitedTask` | boolean | `true` — only chats where the AI agent's task is done. Note the spelling of the parameter                                   |

### Request

```bash
curl "https://hub.athenachat.ai/api/v1/chats/chat?channelName=telegram&limit=20" \
  -H "Authorization: YOUR_API_KEY"
```

### Response

`200 OK`

```json
{
  "chats": [
    {
      "id": "a646fb76-3675-4451-9b92-d85863e4e2a1",
      "uniqueId": "348148573_0252558b-0280-4db0-a159-734e1821fcac",
      "channelName": "telegram",
      "channelId": "0252558b-0280-4db0-a159-734e1821fcac",
      "channelSettingsName": "Support bot",
      "chatId": "348148573",
      "dialogName": "Emma Clark",
      "text": "Yes, we deliver on Saturdays from 10:00 to 16:00.",
      "lastMessageDate": "2026-10-09T09:41:12.000Z",
      "unreadCount": 2,
      "customUnread": false,
      "isTriggered": false,
      "paused": false,
      "isGroup": false,
      "email": null,
      "photo_100": null,
      "userTags": [
        { "tags": { "id": "17344594-73c5-407b-a8b9-6d09053700aa", "name": "VIP" } }
      ],
      "createdAt": "2026-10-02T14:20:04.000Z",
      "updatedAt": "2026-10-09T09:41:12.000Z"
    }
  ],
  "count": 1
}
```

| Field                 | Type    | Description                                                            |
| --------------------- | ------- | ---------------------------------------------------------------------- |
| `count`               | integer | Total number of chats that match the filters, for pagination           |
| `id`                  | string  | Chat ID                                                                |
| `uniqueId`            | string  | Chat key                                                               |
| `channelName`         | string  | Channel type                                                           |
| `channelId`           | string  | ID of the Athena channel                                               |
| `channelSettingsName` | string  | Channel name as you set it in Athena. Can be `null`                    |
| `chatId`              | string  | Chat ID in the messenger, or your `externalChatId` for the API channel |
| `dialogName`          | string  | Chat name, usually the customer's name                                 |
| `text`                | string  | Text of the last message                                               |
| `lastMessageDate`     | string  | Time of the last message                                               |
| `unreadCount`         | integer | Number of unread messages                                              |
| `customUnread`        | boolean | The chat was marked as unread                                          |
| `isTriggered`         | boolean | The AI agent's task is done                                            |
| `paused`              | boolean | The AI agent is paused in this chat                                    |
| `isGroup`             | boolean | It's a group chat                                                      |
| `email`               | string  | Customer's email, if known. Can be `null`                              |
| `photo_100`           | string  | Customer's avatar URL. Can be `null`                                   |
| `userTags`            | array   | Tags of the chat                                                       |

{% hint style="info" %}
When you filter by several tags, `count` can also include chats that have only some of the tags. Use the length of `chats` when you need the exact number.
{% endhint %}

***

## Mark a chat as read

`GET /chats/chat/read`

Marks all messages of the chat as read and resets its unread counter.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Chat ID     |

```bash
curl "https://hub.athenachat.ai/api/v1/chats/chat/read?id=a646fb76-3675-4451-9b92-d85863e4e2a1" \
  -H "Authorization: YOUR_API_KEY"
```

`200 OK`

```json
{ "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "success": true }
```

## Mark a chat as unread

`GET /chats/chat/unread`

Marks the chat as unread in the **Inbox**, so your team doesn't miss it.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Chat ID     |

`200 OK`

```json
{ "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "success": true }
```

***

## Mark the task as done

`GET /chats/chat/done`

Sets the AI agent's task in this chat to **done** — for example, when the order was paid in your CRM.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Chat ID     |

```bash
curl "https://hub.athenachat.ai/api/v1/chats/chat/done?id=a646fb76-3675-4451-9b92-d85863e4e2a1" \
  -H "Authorization: YOUR_API_KEY"
```

`202 Accepted`

```json
{ "id": "a646fb76-3675-4451-9b92-d85863e4e2a1", "success": true }
```

The command is processed in the background. If the status actually changes, Athena sends a [`dialog_status_changed`](/api-reference/en/guides/webhooks.md#dialog_status_changed) webhook event with `source.type: "api"`. If the task is already done, nothing changes and no event is sent.

If you get `503 Service Unavailable`, the command wasn't accepted — retry later.

## Mark the task as not done

`GET /chats/chat/undone`

Sets the AI agent's task in this chat back to **not done**. Works the same way as [Mark the task as done](#mark-the-task-as-done): `202 Accepted`, a `dialog_status_changed` event if the status changes, and `503` if you need to retry.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id`      | string | Yes      | Chat ID     |

***

## Ban a chat

`GET /chats/chat/ban`

Blocks the chat: Athena ignores new messages from this customer, and the AI agent doesn't answer them. Use it for spam. Works for messenger and Chat Widget chats.

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `uniqueId` | string | Yes      | Chat key    |

```bash
curl "https://hub.athenachat.ai/api/v1/chats/chat/ban?uniqueId=348148573_0252558b-0280-4db0-a159-734e1821fcac" \
  -H "Authorization: YOUR_API_KEY"
```

`200 OK`

```json
{ "success": true }
```

If the chat is already banned, you get `400` with the message `Chat already banned`.

## Unban a chat

`GET /chats/chat/unban`

Unblocks the chat, so Athena processes the customer's messages again.

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `uniqueId` | string | Yes      | Chat key    |

`200 OK`

```json
{ "success": true }
```

If the chat isn't banned, you get `400` with the message `Chat not banned`.

***

## Errors

If the chat doesn't exist in your account, these endpoints return `400` with the message `Chat not found`. See [Errors and limits](/api-reference/en/errors-and-limits.md) for the other errors.


---

# 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/endpoints/chats.md?ask=<question>&goal=<user_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.