> ## 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.

# Оғози зуд

> Аввалин паёми худро ба агент фиристед ва ҷавобро хонед.

Ба шумо идентификатори агент ва калид бо иҷозати `full` лозим аст (ниг. [Калиди API-ро гиред](/tj/get-started/api-key)). Ҳамаи мисолҳо онҳоро аз се тағйирёбандаи муҳит мехонанд:

```bash theme={null}
export CHATTLER_BASE_URL="https://api.chattler.ai"
export CHATTLER_AGENT_ID="<your agent id>"
export CHATTLER_API_KEY="cht_live_<key_id>.<secret>"
```

## Фиристодани паём

`POST /v1/agents/{agent_id}/chat` як паёми корбарро мефиристад ва ҷавобро интизор мешавад. Ғайр аз `Content-Type` ду сарлавҳа муҳим аст:

* `Authorization: Bearer <key>`
* `Idempotency-Key`: ҳар қимати беназир аз 1-255 аломат барои ҳар дархости мантиқӣ. UUID интихоби хуб аст. Он дар ҳарду эндпоинти чат **ҳатмӣ** аст; ниг. [Идемпотентӣ](/tj/guides/idempotency).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/chat" \
    -H "Authorization: Bearer $CHATTLER_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{"external_user_id": "customer-123", "message": "I want to know the price"}'
  ```

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

  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 chat(external_user_id: str, message: str) -> dict:
      response = httpx.post(
          f"{BASE_URL}/v1/agents/{AGENT_ID}/chat",
          headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
          json={"external_user_id": external_user_id, "message": message},
          timeout=120,
      )
      if response.status_code >= 400:
          error = response.json()["error"]
          raise RuntimeError(f"{error['code']}: {error['message']} ({error['request_id']})")
      return response.json()


  print(chat("customer-123", "I want to know the price")["message"]["content"])
  ```

  ```javascript Node theme={null}
  const baseUrl = process.env.CHATTLER_BASE_URL;
  const agentId = process.env.CHATTLER_AGENT_ID;
  const apiKey = process.env.CHATTLER_API_KEY;

  async function chat(externalUserId, message) {
    const response = await fetch(`${baseUrl}/v1/agents/${agentId}/chat`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ external_user_id: externalUserId, message }),
    });
    const body = await response.json();
    if (!response.ok) {
      throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
    }
    return body;
  }

  const reply = await chat("customer-123", "I want to know the price");
  console.log(reply.message.content);
  ```
</CodeGroup>

## Хондани ҷавоб

```json theme={null}
{
  "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0",
  "conversation_id": "1c2e...",
  "message": {
    "id": "66e0...",
    "role": "assistant",
    "content": "...",
    "created_at": "2026-09-13T12:00:00Z"
  },
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165,
    "charged_usd": "0.00123400"
  }
}
```

* `request_id` инчунин ҳамчун сарлавҳаи `X-Request-ID` бармегардад.
* `conversation_id` муколамаест, ки мубодила дар он нигоҳ дошта шудааст. Паёми дигарро бо ҳамон `external_user_id` фиристед ва он дар ҳамон ҷо идома меёбад.
* `usage.charged_usd` сатри даҳӣ бо 8 рақам пас аз вергул аст: ин дархост ба баланси соҳиб чӣ қадар арзид.

<Tip>
  Вақте ки агент абзорҳо ё пойгоҳи дониши калонро истифода мебарад, ҷавоб метавонад вақти зиёд гирад. Ба дархост мӯҳлати саховатманд диҳед (мисолҳо 120 сонияро истифода мебаранд) ё [эндпоинти ҷараёнӣ](/tj/guides/streaming)-ро истифода баред, то матнро ҳангоми тавлид нишон диҳед.
</Tip>

## Идомаи муколама

Паёми дуюмро бо ҳамон `external_user_id` ва `Idempotency-Key`-и **нав** фиристед:

```bash theme={null}
curl -X POST "$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/chat" \
  -H "Authorization: Bearer $CHATTLER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "customer-123", "message": "And is delivery included?"}'
```

Агент мубодилаи пешинаро ҳамчун таърих мебинад. Фиристодани паём барои корбари берунае, ки ҷавоби пешинаи ӯ ҳанӯз тавлид мешавад, `409 conversation_busy` бо `Retry-After: 2` бармегардонад; интизор шавед ва такрор кунед.

## Қадамҳои навбатӣ

<CardGroup cols={2}>
  <Card title="Ҷавоби ҷараёнӣ" icon="bolt" href="/tj/guides/streaming">
    Ҷавобро ҳангоми тавлид нишон диҳед.
  </Card>

  <Card title="Муколамаҳо" icon="comments" href="/tj/guides/conversations">
    Муколамаҳоро рӯйхат кунед ва паёмҳоро саҳифа ба саҳифа хонед.
  </Card>

  <Card title="Хатоҳо" icon="triangle-exclamation" href="/tj/guides/errors">
    Ҳар коде, ки API бармегардонад, ва бо он чӣ бояд кард.
  </Card>

  <Card title="Маълумотномаи API" icon="book" href="/tj/api-reference/introduction">
    Схемаҳои пурраи дархост ва ҷавоб, бо майдони озмоиш.
  </Card>
</CardGroup>