> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/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/en/api/messages.md).

# Conversation history

Returns the message history between the bot and its users — the same content that appears in the Telegram chat: incoming messages from users and outgoing messages sent by the bot. You can look up the conversation with a specific chat, search by message text, and filter by date and direction.

### Request

{% hint style="info" %}
Don't forget to add the authorization header for the request. More details in [this](/en/api/auth.md) section
{% endhint %}

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

If your API key is tied to a single bot (a regular key from the "My Bots" section), you don't need to specify anything extra.

If you use a key from the [«API Keys»](https://app.graspil.com/api-keys) section, issued for several bots at once, you must explicitly specify which bot it's for in every request — via the `Resource-Key` header or the `resource_key` field in the request body. The value is the bot's public key (the part before the colon in the bot's API key, found in "My Bots").

#### Pagination parameters

| Parameter | Type | Default | Description                                      |
| --------- | ---- | ------- | ------------------------------------------------ |
| `limit`   | int  | 20      | Number of records (max. 500)                     |
| `offset`  | int  | 0       | Offset — how many records to skip from the start |

#### Filters

All filters are optional and are passed directly in the request body (no nested object).

| Filter             | Type   | Description                                                              |
| ------------------ | ------ | ------------------------------------------------------------------------ |
| `filter_chat_id`   | int    | Show only the conversation with one chat (Telegram `chat_id`)            |
| `filter_way`       | int    | Direction: `1` — incoming (from the user), `2` — outgoing (from the bot) |
| `filter_type`      | string | Message/method type, e.g. `message` or `sendMessage`                     |
| `filter_search`    | string | Search by message text (matches a substring)                             |
| `filter_date_from` | string | Start of the period, format `YYYY-MM-DD HH:MM:SS`                        |
| `filter_date_to`   | string | End of the period, format `YYYY-MM-DD HH:MM:SS`                          |

{% hint style="info" %}
If you don't specify `filter_date_from`/`filter_date_to`, only messages from the last 30 days are returned by default. To get older history, set the period explicitly.
{% endhint %}

Results are always sorted from newest to oldest — custom sorting isn't supported.

#### Example request

{% 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": "promo code"
}
```

{% endcode %}

### Response

{% 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": "Hi, do I still have a promo code?",
        "data": {
          "message_id": 4821,
          "text": "Hi, do I still have a promo code?"
        }
      }
    ]
  }
}
```

{% endcode %}

#### Response fields

| Field       | Type         | Description                                                                                           |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `total`     | int          | Total number of messages matching the filters (regardless of `limit`/`offset`)                        |
| `rows`      | array        | List of messages, see the fields below                                                                |
| `id`        | string       | Internal message identifier                                                                           |
| `chat_id`   | int          | Telegram `chat_id` — who the conversation is with                                                     |
| `way`       | int          | Direction: `1` — incoming, `2` — outgoing                                                             |
| `direction` | string       | The same direction as text: `in` / `out`                                                              |
| `type`      | string       | Message/method type (e.g. `message`, `sendMessage`, `editmessagetext`, etc.)                          |
| `date`      | string       | Message date and time                                                                                 |
| `get_date`  | string       | Date and time the message was received by the platform (usually the same as `date` or slightly later) |
| `text`      | string\|null | Message text. `null` if the message has no text (e.g. a photo without a caption)                      |
| `data`      | object       | The full raw Telegram message object — may contain media, buttons, and other fields                   |

> `data` is the raw message object from the Telegram Bot API; its contents depend on the message type (text, photo, document, poll, etc.).

### Error codes

| Code  | Description                                              |
| ----- | -------------------------------------------------------- |
| `400` | A required parameter is missing or has an invalid format |
| `401` | The API key is missing or invalid                        |
| `403` | The resource is not accessible to this key               |
| `500` | Internal server error                                    |

**Error example:**

{% code overflow="wrap" %}

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

{% endcode %}