> ## 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 ачкычын алу](/tt/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 — яхшы сайлау. Ул ике чат эндпоинтында да **мәҗбүри**; [Идемпотентлык](/tt/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 секунд) яки текстны ясалган саен күрсәтү өчен [агымлы эндпоинтны](/tt/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?"}'
```

Агент элекке алмашуны тарих буларак күрә. Алдагы җавабы әле ясалып торган тышкы кулланучы өчен хәбәр җибәрү `Retry-After: 2` белән `409 conversation_busy` кайтара; көтегез һәм кабатлагыз.

## Киләсе адымнар

<CardGroup cols={2}>
  <Card title="Агымлы җавап" icon="bolt" href="/tt/guides/streaming">
    Җавапны ясалган саен күрсәтегез.
  </Card>

  <Card title="Диалоглар" icon="comments" href="/tt/guides/conversations">
    Диалоглар исемлеген алыгыз һәм хәбәрләрне битләп карагыз.
  </Card>

  <Card title="Хаталар" icon="triangle-exclamation" href="/tt/guides/errors">
    API кайтара алган һәр код һәм аның белән нәрсә эшләргә.
  </Card>

  <Card title="API белешмәсе" icon="book" href="/tt/api-reference/introduction">
    Тулы сорау һәм җавап схемалары, уен мәйданчыгы белән.
  </Card>
</CardGroup>