> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/api/messages.md).

# История переписки

Возвращает историю сообщений между ботом и пользователями — то же, что попадает в переписку в Telegram: входящие сообщения от пользователей и исходящие от бота. Можно смотреть переписку конкретного чата, искать по тексту сообщений и фильтровать по дате и направлению.

### Запрос

{% hint style="info" %}
Не забудьте добавить заголовок для авторизации запроса. Подробней в [этом](/ru/api/auth.md) разделе
{% endhint %}

<mark style="color:blue;">`POST`</mark> `/v1/messages/list`

Если ваш API-ключ привязан к одному боту (обычный ключ из раздела «Мои боты») — ничего дополнительно указывать не нужно.

Если вы используете ключ из раздела [«API-ключи»](https://app.graspil.com/api-keys), выданный сразу на несколько ботов, в каждом запросе нужно явно указать, какого бота он касается — заголовком `Resource-Key` либо полем `resource_key` в теле запроса. Значение — публичный ключ бота (часть до двоеточия в API-ключе бота из раздела «Мои боты»).

#### Параметры пагинации

| Параметр | Тип | По умолчанию | Описание                                       |
| -------- | --- | ------------ | ---------------------------------------------- |
| `limit`  | int | 20           | Количество записей (макс. 500)                 |
| `offset` | int | 0            | Смещение — сколько записей пропустить с начала |

#### Фильтры

Все фильтры необязательны и передаются прямо в теле запроса (без вложенного объекта).

| Фильтр             | Тип    | Описание                                                                 |
| ------------------ | ------ | ------------------------------------------------------------------------ |
| `filter_chat_id`   | int    | Показать переписку только с одним чатом (Telegram `chat_id`)             |
| `filter_way`       | int    | Направление: `1` — входящие (от пользователя), `2` — исходящие (от бота) |
| `filter_type`      | string | Тип сообщения/метода, например `message` или `sendMessage`               |
| `filter_search`    | string | Поиск по тексту сообщения (ищет вхождение подстроки)                     |
| `filter_date_from` | string | Начало периода, формат `YYYY-MM-DD HH:MM:SS`                             |
| `filter_date_to`   | string | Конец периода, формат `YYYY-MM-DD HH:MM:SS`                              |

{% hint style="info" %}
Если не указать `filter_date_from`/`filter_date_to`, по умолчанию возвращаются сообщения только за последние 30 дней. Чтобы получить более старую переписку, явно задайте нужный период.
{% endhint %}

Результат всегда отсортирован по дате от новых к старым — своя сортировка не поддерживается.

#### Пример запроса

{% code overflow="wrap" %}

```json
POST /v1/messages/list
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "limit": 20,
  "offset": 0,
  "filter_chat_id": 123456789,
  "filter_search": "промокод"
}
```

{% endcode %}

### Ответ

{% code overflow="wrap" %}

```json
{
  "ok": true,
  "data": {
    "total": 42,
    "rows": [
      {
        "id": "a1b2c3d4-...",
        "chat_id": 123456789,
        "way": 1,
        "direction": "in",
        "type": "message",
        "date": "2026-07-05 14:30:00",
        "get_date": "2026-07-05 14:30:01",
        "text": "Привет, у меня остался промокод?",
        "data": {
          "message_id": 4821,
          "text": "Привет, у меня остался промокод?"
        }
      }
    ]
  }
}
```

{% endcode %}

#### Поля ответа

| Поле        | Тип          | Описание                                                                                          |
| ----------- | ------------ | ------------------------------------------------------------------------------------------------- |
| `total`     | int          | Общее количество сообщений, подходящих под фильтры (без учёта `limit`/`offset`)                   |
| `rows`      | array        | Список сообщений, см. поля ниже                                                                   |
| `id`        | string       | Внутренний идентификатор сообщения                                                                |
| `chat_id`   | int          | Telegram `chat_id` — с кем велась переписка                                                       |
| `way`       | int          | Направление: `1` — входящее, `2` — исходящее                                                      |
| `direction` | string       | То же самое направление словами: `in` / `out`                                                     |
| `type`      | string       | Тип сообщения/метода (например `message`, `sendMessage`, `editmessagetext` и т. д.)               |
| `date`      | string       | Дата и время сообщения                                                                            |
| `get_date`  | string       | Дата и время, когда сообщение было получено платформой (обычно совпадает с `date` или чуть позже) |
| `text`      | string\|null | Текст сообщения. `null`, если в сообщении нет текста (например, это фото без подписи)             |
| `data`      | object       | Полный исходный объект сообщения Telegram — может содержать медиа, кнопки и другие поля           |

> `data` — это необработанный объект сообщения из Telegram Bot API, его состав зависит от типа сообщения (текст, фото, документ, опрос и т. д.).

### Коды ошибок

| Код   | Описание                                                         |
| ----- | ---------------------------------------------------------------- |
| `400` | Не передан обязательный параметр либо параметр неверного формата |
| `401` | API-ключ не передан или недействителен                           |
| `403` | Ресурс недоступен этому ключу                                    |
| `500` | Внутренняя ошибка сервера                                        |

**Пример ошибки:**

{% code overflow="wrap" %}

```json
{
  "ok": false,
  "error": { "errors": "resource_key is required" },
  "error_code": 400
}
```

{% endcode %}