> ## 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 `409 conversation_busy` бо `Retry-After: 2` ҷавоб медиҳад. Интизор шавед ва аз нав фиристед.

## Рӯйхати муколамаҳо

`GET /v1/agents/{agent_id}/conversations` муколамаҳои калидро бармегардонад, аввал охирин навшуда. Ҳам калидҳои `read-only` ва ҳам `full` метавонанд онро даъват кунанд.

| Параметри query        | Маъно                                                        |
| ---------------------- | ------------------------------------------------------------ |
| `external_user_id`     | Танҳо муколамаҳои ин корбари беруна                          |
| `date_from`, `date_to` | Ҳудуди ISO-8601 барои `updated_at`; `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` бармегарданд; мубодилаи абзорҳо, сатрҳои фаъолияти абзорҳо ва system prompt ҳеҷ гоҳ ошкор намешаванд.

| Параметри query        | Маъно                                                      |
| ---------------------- | ---------------------------------------------------------- |
| `date_from`, `date_to` | Ҳудуди ISO-8601 барои `created_at`; `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` мешавад, қатъ кунед. Курсорҳо норавшананд; курсори нодуруст `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_to`, ки аз `date_from` пештар аст, `422 validation_error` аст.