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

# Диалоглар

> Диалоглар ничек билгеләнә, аерыла һәм кире укыла.

## Һәр тышкы кулланучыга бер диалог

Диалог ике нәрсә белән билгеләнә: API ачкычы һәм сез җибәргән `external_user_id`. Сез диалогны беркайчан да үзегез ясамыйсыз; яңа `external_user_id` өчен беренче чат соравы аны ясый, ә шул ук тышкы кулланучыдан шул ук ачкыч аша килгән һәр соңгы хәбәр аны дәвам итә.

Белергә кирәкле нәтиҗәләр:

* **Ачкыч буенча аерымлык.** Ике төрле ачкыч аша килгән бер үк `external_user_id` — ике төрле диалог, хәтта ике ачкыч та бер агентныкы булса да. Ачкыч башка ачкычның яки башка каналның (Telegram, виджет һ.б.) диалогларын беркайчан күрми.
* **Яңарту тарихны саклый.** Ачкычны яңарту аның серен үзгәртә, идентификаторын түгел, шуңа күрә диалоглары аңа беркетелгән килеш кала.
* **`external_user_id` — сезнеке.** Үз системагыздан 1-255 символлы тотрыклы идентификатор кулланыгыз. Аңа диалог янында сакланырга тиеш булмаган шәхси мәгълүматны салмагыз.
* **Бер вакытта бер җавап.** Алдагы җавап әле ясалып торганда тышкы кулланучы өчен хәбәр килсә, API `Retry-After: 2` белән `409 conversation_busy` җавабын бирә. Көтегез һәм яңадан җибәрегез.

## Диалоглар исемлеге

`GET /v1/agents/{agent_id}/conversations` ачкычның диалогларын кайтара, иң соңгы яңартылганнары башта. Аны `read-only` һәм `full` ачкычлар да чакыра ала.

| Сорау параметры        | Мәгънәсе                                                          |
| ---------------------- | ----------------------------------------------------------------- |
| `external_user_id`     | Бу тышкы кулланучының диалоглары гына                             |
| `date_from`, `date_to` | `updated_at` буенча ISO-8601 чикләре; `date_to` керми (эксклюзив) |
| `limit`                | Бит зурлыгы, 1-100 (килешү буенча 20)                             |
| `cursor`               | Алдагы биттәге `next_cursor`; беренче бит өчен төшереп калдырыгыз |

```bash theme={null}
curl "$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/conversations?limit=50" \
  -H "Authorization: Bearer $CHATTLER_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "1c2e...",
      "external_user_id": "customer-123",
      "created_at": "2026-09-13T11:58:02Z",
      "updated_at": "2026-09-13T12:00:00Z",
      "last_message_preview": "The basic plan is $19 per month..."
    }
  ],
  "next_cursor": null
}
```

`last_message_preview` — 160 символга кадәр кыскартылган соңгы кулланучы яки ассистент тексты, яки буш диалог өчен `null`.

## Хәбәрләрне уку

`GET /v1/agents/{agent_id}/conversations/{conversation_id}/messages` бер диалогның хәбәрләрен кайтара, иң яңалары башта. `user` һәм `assistant` хәбәрләре генә кайтарыла; кораллар белән алмашулар, корал эшчәнлеге язмалары һәм система промпты беркайчан да ачылмый.

| Сорау параметры        | Мәгънәсе                                                          |
| ---------------------- | ----------------------------------------------------------------- |
| `date_from`, `date_to` | `created_at` буенча ISO-8601 чикләре; `date_to` керми (эксклюзив) |
| `limit`                | Бит зурлыгы, 1-100 (килешү буенча 20)                             |
| `cursor`               | Алдагы биттәге `next_cursor`                                      |

Һәр хәбәрдә `id`, `role` (`user` яки `assistant`), `type` (`text`, `image`, `file`, ...), `content` (текст; текст булмаган эчтәлек тексты яки исеме белән бирелә) һәм `created_at` бар.

Башка ачкычка яки каналга караган, яисә бөтенләй булмаган диалог идентификаторы — `404 conversation_not_found`. API бу ике очракны аермый.

## Битләү

Һәр исемлек — `{"data": [...], "next_cursor": "..." | null}`. Киләсе битне алу өчен `next_cursor` кыйммәтен `cursor` буларак кире җибәрегез һәм ул `null` булганда туктагыз. Курсорлар ябык (opaque); дөрес булмаган курсор — `422 validation_error`.

<CodeGroup>
  ```bash curl theme={null}
  # Walks every page; stops when next_cursor is null.
  cursor=""
  while :; do
    url="$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/conversations?limit=100"
    [ -n "$cursor" ] && url="$url&cursor=$cursor"
    page=$(curl -s "$url" -H "Authorization: Bearer $CHATTLER_API_KEY")
    echo "$page" | jq -c '.data[]'
    cursor=$(echo "$page" | jq -r '.next_cursor // empty')
    [ -z "$cursor" ] && break
  done
  ```

  ```python Python theme={null}
  import os

  import httpx

  BASE_URL = os.environ["CHATTLER_BASE_URL"]
  AGENT_ID = os.environ["CHATTLER_AGENT_ID"]
  HEADERS = {"Authorization": f"Bearer {os.environ['CHATTLER_API_KEY']}"}


  def iter_conversations():
      cursor = None
      while True:
          params = {"limit": 100}
          if cursor:
              params["cursor"] = cursor
          page = httpx.get(
              f"{BASE_URL}/v1/agents/{AGENT_ID}/conversations",
              headers=HEADERS,
              params=params,
          ).json()
          yield from page["data"]
          cursor = page["next_cursor"]
          if not cursor:
              break
  ```

  ```javascript Node theme={null}
  async function* iterConversations() {
    let cursor = null;
    for (;;) {
      const url = new URL(`${baseUrl}/v1/agents/${agentId}/conversations`);
      url.searchParams.set("limit", "100");
      if (cursor) url.searchParams.set("cursor", cursor);
      const page = await (
        await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } })
      ).json();
      yield* page.data;
      cursor = page.next_cursor;
      if (!cursor) break;
    }
  }
  ```
</CodeGroup>

## Даталар

Даталар — ISO-8601. Вакыт поясы күрсәтелгән кыйммәтләр UTC-га күчерелә, күрсәтелмәгәннәре UTC дип укыла, ә `date_to` керми (эксклюзив). `date_from` кыйммәтеннән иртәрәк `date_to` — `422 validation_error`.