> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات دردشة التدفق الحواري

> استخدم نقاط نهاية الدردشة في النشر لتشغيل تدفقات حوارية متعددة الأدوار على CrewAI AMP

## نظرة عامة

تعرض التدفقات الحوارية المنشورة واجهة برمجة تطبيقات لجلسة الدردشة على عنوان URL الخاص بالأتمتة. بدلًا من تشغيل `/kickoff` واحد، تنشئ جلسة، وترسل رسائل المستخدم كأدوار (turns)، ويمكنك اختياريًا بث الرموز والأحداث أثناء التشغيل، واستئناف توقفات HITL عندما يحتاج الدور إلى ملاحظات بشرية.

<Note>
  دردشة التدفق الحواري **تجريبية**. تتوفر نقاط النهاية فقط عندما يُبلغ التدفق المنشور عن `conversational: true` و`handle_turn: true` من [`GET /inspect`](#اكتشاف-قدرة-الدردشة).
</Note>

لبناء التدفق نفسه (`conversational = True` و`handle_turn` والموجّهات والتتبع)، راجع دليل المصادر المفتوحة [Conversational Flows](https://docs.crewai.com/en/guides/flows/conversational-flows).

## المتطلبات الأساسية

1. انشر أتمتة Flow تنفّذ الأدوار الحوارية (`handle_turn`).
2. انسخ رمز Bearer من علامة تبويب **Status** للأتمتة (نفس الرمز المستخدم مع `/kickoff`).
3. أكّد تفعيل الدردشة عبر `/inspect` (أدناه).

تستخدم جميع الطلبات:

```bash theme={null}
Authorization: Bearer YOUR_FLOW_TOKEN
```

تستخدم أمثلة هذا الدليل القاعدة `https://your-flow-url.crewai.com`.

## اكتشاف قدرة الدردشة

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect
```

ابحث عن `flow.chat`:

```json theme={null}
{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}
```

إذا كانت أي من العلامتين false، تُرجع نقاط نهاية الدردشة `404` مع `"Conversational flow chat is not available"`.

## حلقة الدردشة من البداية للنهاية

<Steps>
  <Step title="بدء جلسة">
    أنشئ جلسة دردشة. يمكنك اختياريًا تسجيل webhook لانتهاء الدور وwebhooks للأحداث طوال عمر الجلسة.

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
        "webhooks": {
          "url": "https://your-server.com/webhooks/events",
          "events": ["*"],
          "realtime": false,
          "authentication": {
            "strategy": "bearer",
            "token": "my-secret-token"
          }
        }
      }' \
      https://your-flow-url.crewai.com/chat/start
    ```

    الاستجابة:

    ```json theme={null}
    { "session_id": "11111111-2222-3333-4444-555555555555" }
    ```

    الجسم الفارغ (`{}` أو بدون جسم) صالح عندما لا تحتاج إلى webhooks.
  </Step>

  <Step title="إرسال رسالة مستخدم">
    ضع دورًا واحدًا في قائمة الانتظار للجلسة:

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "message": "Where is my order?",
        "stream": true
      }' \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message
    ```

    الاستجابة:

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "queued"
    }
    ```

    | الحقل            | الوصف                                                                                                                                  |
    | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | `message`        | مطلوب. سطر المستخدم الحالي لهذا الدور.                                                                                                 |
    | `stream`         | الافتراضي `true`. عند `true` تُنشر إطارات الرمز/الحدث لعملاء WebSocket/SSE.                                                            |
    | `messageHistory` | نص احتياطي اختياري (`[{ "role", "content" }, ...]`). سجل الجلسة على الخادم هو المرجع؛ يُستخدم هذا فقط عندما يكون السجل المخزّن فارغًا. |

    الأدوار المقبولة في `messageHistory`: `user` و`assistant` و`system` و`tool`.
  </Step>

  <Step title="انتظار انتهاء الدور">
    راقب الدور باستخدام `kickoff_id` المُعاد (نفس واجهة حالة kickoff العادية للتدفق):

    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    ```

    يمكن أن يكون دور واحد فقط نشطًا لكل جلسة. طلب `/message` ثانٍ أثناء تعيين `active_kickoff_id` يُرجع `409`:

    ```json theme={null}
    {
      "detail": {
        "code": "session_busy",
        "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
    }
    ```

    انتظر حتى يُظهر السجل `active_kickoff_id: null` (أو يصل الدور إلى حالة نهائية / توقف) قبل إرسال الرسالة التالية.
  </Step>

  <Step title="قراءة سجل الجلسة">
    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history
    ```

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "messages": [
        { "role": "user", "content": "Where is my order?" },
        { "role": "assistant", "content": "Your order is on the way." }
      ],
      "active_kickoff_id": null
    }
    ```
  </Step>
</Steps>

## بث دور

البث اختياري. استخدمه عندما تحتاج الواجهة إلى رموز أو أحداث runtime أثناء تشغيل الدور. تتضمن الإطارات دائمًا أنواع دورة الحياة (`turn_started` و`turn_completed` و`turn_failed` و`token` و`error`). يمكن تصفية إطارات `event` الإضافية بمعلمة الاستعلام `events` (`*` أو قائمة مفصولة بفواصل).

### الخيار أ: رسالة HTTP + إرفاق SSE

1. `POST /chat/{session_id}/message` مع `"stream": true`.
2. اربط بالدور النشط:

```bash theme={null}
curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"
```

يُرجع SSE إطارات JSON من نوع `text/event-stream` (`data: {...}`) مع تعليقات keepalive. ينتهي البث عند `turn_completed` أو `turn_failed`.

إذا لم يكن هناك دور نشط، تُرجع هذه النقطة `409` (`No active chat turn`).

### الخيار ب: WebSocket (إرفاق أو إرسال)

```text theme={null}
wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0
```

المصادقة: مرّر رمز Bearer كمعامل استعلام `token`، أو كترويسة `Authorization: Bearer ...` عندما يدعم عميلك ترويسات WebSocket.

السلوك:

* **دور نشط قيد التشغيل بالفعل** — يتصل المقبس ويُرسل أولًا `turn_started` مع `data.status: "attached"`، ثم يبث الإطارات حتى نوع نهائي.
* **لا يوجد دور نشط** — أرسل رسالة JSON لوضع دور في قائمة الانتظار ثم استهلك البث:

```json theme={null}
{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}
```

يستجيب الخادم بـ `turn_started` (`status: "queued"`) ثم إطارات البث لذلك `kickoff_id`.

استخدم `last_event_id` / `lastEventId` للاستئناف بعد انقطاع الاتصال.

### أمثلة على إطارات البث

```json theme={null}
{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}
```

```json theme={null}
{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}
```

```json theme={null}
{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}
```

## HITL داخل جلسة دردشة

إذا توقف دور لانتظار ملاحظات بشرية (`status` / الحالة `PAUSED`)، استأنفه بنفس نقطة استئناف Flow المستخدمة في التشغيلات غير الحوارية:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback
```

ثم راقب `kickoff_id` الخاص بالاستئناف من الاستجابة. انتظر حتى يُظهر `/history` القيمة `active_kickoff_id: null` قبل إرسال رسالة الدردشة التالية.

راجع [سير عمل HITL](/platform/ar/guides/human-in-the-loop) و[إدارة HITL للتدفقات](/platform/ar/features/flow-hitl-management) لواجهة المراجعة على المنصة.

## مرجع واجهة البرمجة

| الطريقة | المسار                             | الغرض                                      |
| ------- | ---------------------------------- | ------------------------------------------ |
| `GET`   | `/inspect`                         | اكتشاف ما إذا كانت الدردشة الحوارية مفعّلة |
| `POST`  | `/chat/start`                      | إنشاء جلسة دردشة                           |
| `POST`  | `/chat/{session_id}/message`       | وضع دور مستخدم في قائمة الانتظار           |
| `GET`   | `/chat/{session_id}/history`       | قراءة الرسائل ومعرّف الدور النشط           |
| `GET`   | `/chat/{session_id}/stream/events` | بث SSE للدور النشط                         |
| `WS`    | `/chat/{session_id}/stream`        | بث WebSocket (إرفاق أو إرسال + بث)         |
| `GET`   | `/status/{kickoff_id}`             | مراقبة حالة تنفيذ الدور (أو الاستئناف)     |
| `POST`  | `/resume_feedback`                 | استئناف دور HITL متوقف                     |

### أخطاء شائعة

| الحالة | متى                                                                     |
| ------ | ----------------------------------------------------------------------- |
| `400`  | `message` فارغ                                                          |
| `404`  | الدردشة غير مفعّلة على هذا النشر، أو `session_id` غير معروف             |
| `409`  | الجلسة لديها دور نشط بالفعل (`session_busy`)، أو إرفاق SSE بدون دور نشط |
| `422`  | `session_id` ليس UUID صالحًا                                            |
| `503`  | تخزين جلسة الدردشة أو البث غير متاح                                     |

## ذات صلة

<CardGroup cols={2}>
  <Card title="Conversational Flows" href="https://docs.crewai.com/en/guides/flows/conversational-flows" icon="comments">
    ابنِ تدفقات متعددة الأدوار باستخدام `handle_turn` والموجّهات والتتبع.
  </Card>

  <Card title="Kickoff Crew / Flow" href="/platform/ar/guides/kickoff-crew" icon="flag-checkered">
    تشغيل kickoff واحد ومراقبة الحالة على عنوان URL للنشر.
  </Card>

  <Card title="Webhook Streaming" href="/platform/ar/features/webhook-streaming" icon="webhook">
    شكل حمولة webhook للأحداث وخيارات المصادقة.
  </Card>

  <Card title="إدارة HITL للتدفقات" href="/platform/ar/features/flow-hitl-management" icon="users-gear">
    مراجعة بشرية بالبريد الإلكتروني أولًا لخطوات التدفق المتوقفة.
  </Card>
</CardGroup>