> ## 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](/ar/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 خيار جيد. وهي **مطلوبة** في نقطتي نهاية الدردشة كلتيهما؛ راجع [التكرار الآمن](/ar/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 ثانية) أو استخدم [نقطة نهاية الرد المتدفق](/ar/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="/ar/guides/streaming">
    اعرض الإجابة أثناء توليدها.
  </Card>

  <Card title="المحادثات" icon="comments" href="/ar/guides/conversations">
    اعرض المحادثات وتصفّح الرسائل صفحةً صفحة.
  </Card>

  <Card title="الأخطاء" icon="triangle-exclamation" href="/ar/guides/errors">
    كل رمز يمكن أن تُرجعه API وما تفعله حياله.
  </Card>

  <Card title="مرجع API" icon="book" href="/ar/api-reference/introduction">
    مخططات الطلب والرد الكاملة، مع ساحة تجربة.
  </Card>
</CardGroup>