> ## 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` բանալիները:

| Հարցման պարամետր       | Նշանակություն                                                  |
| ---------------------- | -------------------------------------------------------------- |
| `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` հաղորդագրությունները; գործիքների փոխանակումները, գործիքների գործունեության տողերը և համակարգային հրահանգը երբեք չեն բացահայտվում:

| Հարցման պարամետր       | Նշանակություն                                                  |
| ---------------------- | -------------------------------------------------------------- |
| `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_from`-ից ավելի վաղ `date_to`-ն `422 validation_error` է: