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

# نظرة عامة

> تحدّث مع أي وكيل Chattler من كودك الخاص عبر REST API صغيرة.

يمكن الوصول إلى أي وكيل Chattler عبر HTTPS باستخدام مفتاح API. الطلب عبر API يشغّل نفس بيئة التشغيل التي تعمل بها Telegram وWhatsApp وصفحة الدردشة: يُطبَّق موجّه النظام الخاص بالوكيل وقاعدة معرفته وأدواته وسجل الحوار، وتُدفع تكلفة الردود من رصيد المالك بالطريقة نفسها.

## ما الذي تقدمه API

<CardGroup cols={2}>
  <Card title="الدردشة" icon="message" href="/api-reference/public-api/send-a-message-to-the-agent-and-wait-for-the-reply">
    أرسل رسالة مستخدم واحدة واحصل على رد الوكيل، مع استهلاك الرموز والمبلغ المحصّل.
  </Card>

  <Card title="الرد المتدفق" icon="bolt" href="/ar/guides/streaming">
    الطلب نفسه، لكن الرد يصل رمزًا تلو الآخر كأحداث مُرسَلة من الخادم.
  </Card>

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

  <Card title="البداية السريعة" icon="rocket" href="/ar/get-started/quickstart">
    أول رد خلال خمس دقائق باستخدام curl أو Python أو Node.
  </Card>
</CardGroup>

## الأساسيات

|              |                                                                           |
| ------------ | ------------------------------------------------------------------------- |
| عنوان الأساس | `https://api.chattler.ai`                                                 |
| بادئة المسار | `/v1`                                                                     |
| المصادقة     | `Authorization: Bearer cht_live_<key_id>.<secret>`                        |
| الصيغة       | JSON في الطلب، JSON في الرد؛ `text/event-stream` لنقطة نهاية الرد المتدفق |
| الأخطاء      | غلاف واحد: `{"error": {"code", "message", "request_id"}}`                 |
| حد المعدل    | 120 طلبًا كل 60 ثانية لكل مفتاح                                           |

المفتاح ينتمي إلى وكيل واحد بالضبط. صلاحيته إما `read-only` (عرض المحادثات وقراءة الرسائل) أو `full` (الدردشة أيضًا).

## نقاط النهاية

| الطريقة | المسار                                                           | الصلاحية              |
| ------- | ---------------------------------------------------------------- | --------------------- |
| `POST`  | `/v1/agents/{agent_id}/chat`                                     | `full`                |
| `POST`  | `/v1/agents/{agent_id}/chat/stream`                              | `full`                |
| `GET`   | `/v1/agents/{agent_id}/conversations`                            | `read-only` أو `full` |
| `GET`   | `/v1/agents/{agent_id}/conversations/{conversation_id}/messages` | `read-only` أو `full` |

## كيف تعمل المحادثات

أنت لا تنشئ المحادثات بنفسك. كل طلب دردشة يحدد `external_user_id`، وهو المعرّف الثابت للمستخدم النهائي لديك. كل رسالة من المستخدم الخارجي نفسه عبر المفتاح نفسه تواصل المحادثة نفسها؛ أما المفتاح المختلف، حتى للوكيل نفسه، فله سجل منفصل خاص به. راجع [المحادثات](/ar/guides/conversations).

<Note>
  هذا الإصدار نصي فقط: الرسالة سلسلة نصية، والمرفقات غير مقبولة. كل رد يحمل ترويسة `X-Request-ID`؛ اذكرها عند الإبلاغ عن مشكلة.
</Note>