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

# إرسال رسالة إلى Gorbit

> إرسال الرسائل برمجيًا إلى Gorbit

<Note>
  نوصي بترحيل أي استخدام لـ `/chat/send-message` و `/chat/send-message-simple-api` إلى هذه الواجهة الجديدة بحلول
  1 فبراير 2026.
</Note>

واجهة `/chat/send-chat-message` API تُستخدم لإرسال رسالة إلى Gorbit.
إنها نفس الواجهة التي تستخدمها الواجهة الأمامية لـ Gorbit لإرسال واستلام الرسائل.
لديك خيار تلقي استجابة مبثوثة أو الاستجابة الكاملة كسلسلة.

سيرشدك هذا الدليل إلى جميع المعلمات التي يمكنك تمريرها إلى الواجهة ويوفر نموذج رمز.

## معلمات الطلب

| المعلمة              | الوصف                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `message`            | رسالة المستخدم لإرسالها إلى الوكيل.                                                                                                                                                                                                                                                                                                                                                        |
| `llm_override`       | تمرير كائن لتجاوز إعدادات LLM الافتراضية لهذا الطلب. إذا `None`، ستحصل على سلوك Gorbit الافتراضي. <br /><br />يمكنك تمرير أو استبعاد أي من الحقول التالية: <br />• `model_provider` <br />• `model_version` <br />• `temperature` <br /><br />إذا مررت تكوينًا غير صالح (مثل تحديد `claude-sonnet-4.5` عندما يكون `model_provider` الافتراضي هو OpenAI)، سيفشل طلبك.                       |
| `allowed_tool_ids`   | يتم إنشاء الوكلاء مع مجموعة من الإجراءات المسموح لهم باستدعاؤها. يمكنك تكوين هذه المجموعة بشكل أكبر لتفاعلك الفوري باستخدام هذه المعلمة. راجع قائمة الإجراءات ومعرفاتها عبر نقطة النهاية [GET /tool](/developers/api_reference/actions/list_tools). مرر قائمة فارطة لتعطيل جميع الإجراءات. مرر `None` للسماح بجميع الإجراءات المكونة للوكيل.                                               |
| `forced_tool_id`     | إجبار الوكيل على استخدام إجراء محدد لهذا الطلب. قد يقوم الوكيل بتشغيل إجراءات أخرى قبل إرجاع استجابته النهائية، لكنه مضمون لاستخدام هذا الإجراء. اتركه فارغًا للسماح للوكيل بتحديد الإجراءات التي سيستخدمها.                                                                                                                                                                               |
| `file_descriptors`   | قائمة الملفات لتضمينها مع طلبك. يمكن العثور على معرفات الملفات عبر نقاط النهاية [POST /user/projects/file/upload](/developers/api_reference/projects/upload_user_files) و [GET /user/projects/file/{file_id}](/developers/api_reference/projects/get_user_file).                                                                                                                           |
| `search_filters`     | مرشحات لتضييق نتائج البحث الداخلية المستخدمة من قبل الوكيل. جميع معاملات المرشح اختيارية ويمكن دمجها: <br /><br />• `source_type` – أنواع المصادر مثل `web`، `slack`، `google_drive`، `confluence` <br />• `document_set` – اسم مجموعات المستندات للبحث فيها <br />• `time_cutoff` – تنسيق ISO 8601: `YYYY-MM-DDTHH:MM:SSZ` <br />• `tags` – التنسيق: `{"tag_key": "tag_value"}`           |
| `deep_research`      | تفعيل وضع البحث العميق لهذا الطلب. <br /><br />**ملاحظة:** هذا الوضع يستهلك رموزًا أكثر بكثير، لذا كن حذرًا عند الوصول إليه عبر API.                                                                                                                                                                                                                                                       |
| `parent_message_id`  | معرف الرسالة الأصل في سجل المحادثة (المفتاح الأساسي للرسالة السابقة في شجرة سجل المحادثة). إذا لم يتم تمريره، يُفترض أن رسالتك الجديدة تأتي تسلسليًا بعد الرسالة الأخيرة. <br /><br />**تحذير:** إذا تم التعيين على `None`، يتم إعادة تعيين سجل المحادثة وتُعتبر الرسالة الجديدة أول رسالة في سجل المحادثة.                                                                                |
| `chat_session_id`    | لمتابعة محادثة موجودة، مرر معرف جلسة المحادثة التي يجب إرسال الرسالة إليها. إذا تُرك فارغًا، سيتم إنشاء جلسة محادثة جديدة وفقًا لـ `chat_session_info`.                                                                                                                                                                                                                                    |
| `chat_session_info`  | تفاصيل حول جلسة المحادثة التي سيتم استخدامها لجميع الرسائل في الجلسة. يمكن ترك الحقول فارغة لاستخدام الإعدادات الافتراضية. <br /><br />• `persona_id` – معرف الوكيل المراد استخدامه لجلسة المحادثة <br />• `project_id` – معرف المشروع إذا كان يجب تحديد نطاق المحادثة إلى مشروع                                                                                                           |
| `stream`             | إذا كان صحيحًا، يستجيب بدفق SSE من الحزم الفردية (نفس المجموعة المستخدمة لواجهة Gorbit). يجب تجميع حقول مثل الإجابة، والرموز المميزة للتفكير، واستدعاءات الأداة التكرارية من الرموز المميزة المبثوثة.                                                                                                                                                                                      |
| `include_citations`  | إذا كان صحيحًا، ستتضمن الردود استشهادات للمصادر المستخدمة لإنشاء الإجابة.                                                                                                                                                                                                                                                                                                                  |
| `additional_context` | سلسلة من السياق الإضافي المحقونة في استدعاء LLM لهذا الطلب. يتم تمرير السياق إلى النموذج لكنه **غير مخزن في قاعدة البيانات** ولن يظهر في سجل المحادثة.<br />استخدم هذا لتوفير معلومات مؤقتة محددة النطاق بالطلب (مثل URL الصفحة الحالية للمستخدم، أو بيانات الجلسة الوصفية، أو أي سياق وقت التشغيل) دون تلويث سجل المحادثة المستمر.<br />مرر `null` أو احذف الحقل لعدم استخدام سياق إضافي. |

## تنسيق الاستجابة

### الاستجابة المبثوثة

تُرجع Gorbit أنواعًا مختلفة من الحزم في الاستجابة المبثوثة اعتمادًا على سلوك LLM.

راجع
[streaming\_models.py](https://github.com/gorbit-dot-app/gorbit/blob/main/backend/gorbit/server/query_and_chat/streaming_models.py)
على GitHub للحصول على القائمة الكاملة لأنواع الحزم وحقولها المقابلة.

```python expandable theme={null}
class StreamingType(Enum):
    """تعداد يحدد جميع أنواع حزم البث."""

    SECTION_END = "section_end"
    STOP = "stop"
    TOP_LEVEL_BRANCHING = "top_level_branching"
    ERROR = "error"

    MESSAGE_START = "message_start"
    MESSAGE_DELTA = "message_delta"
    SEARCH_TOOL_START = "search_tool_start"
    SEARCH_TOOL_QUERIES_DELTA = "search_tool_queries_delta"
    SEARCH_TOOL_DOCUMENTS_DELTA = "search_tool_documents_delta"
    OPEN_URL_START = "open_url_start"
    OPEN_URL_URLS = "open_url_urls"
    OPEN_URL_DOCUMENTS = "open_url_documents"
    IMAGE_GENERATION_START = "image_generation_start"
    IMAGE_GENERATION_HEARTBEAT = "image_generation_heartbeat"
    IMAGE_GENERATION_FINAL = "image_generation_final"
    PYTHON_TOOL_START = "python_tool_start"
    PYTHON_TOOL_DELTA = "python_tool_delta"
    CUSTOM_TOOL_START = "custom_tool_start"
    CUSTOM_TOOL_DELTA = "custom_tool_delta"
    REASONING_START = "reasoning_start"
    REASONING_DELTA = "reasoning_delta"
    REASONING_DONE = "reasoning_done"
    CITATION_INFO = "citation_info"

    DEEP_RESEARCH_PLAN_START = "deep_research_plan_start"
    DEEP_RESEARCH_PLAN_DELTA = "deep_research_plan_delta"
    RESEARCH_AGENT_START = "research_agent_start"
    INTERMEDIATE_REPORT_START = "intermediate_report_start"
    INTERMEDIATE_REPORT_DELTA = "intermediate_report_delta"
    INTERMEDIATE_REPORT_CITED_DOCS = "intermediate_report_cited_docs"
```

### الاستجابة غير المبثوثة

```python theme={null}
class ChatFullResponse(BaseModel):
    """استجابة كاملة غير مبثوثة مع جميع البيانات المتاحة."""

    # حقول الاستجابة الأساسية
    answer: str
    answer_citationless: str
    pre_answer_reasoning: str | None = None
    tool_calls: list[ToolCallResponse] = []

    # المستندات والاستشهادات
    top_documents: list[SearchDoc]
    citation_info: list[CitationInfo]

    # البيانات الوصفية
    message_id: int
    chat_session_id: UUID | None = None
    error_msg: str | None = None
```

## نموذج طلب

<CodeGroup>
  ```python Python expandable theme={null}
  import requests

  API_BASE_URL = "https://cloud.gorbit.app/api"  # أو نطاقك الخاص
  API_KEY = "YOUR_KEY_HERE"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  response = requests.post(
      f"{API_BASE_URL}/chat/send-chat-message",
      headers=headers,
      json={
          "message": "ما هو Gorbit؟",
      }
  )

  data = response.json()
  print("الإجابة:", data["answer"])
  print("معرف الرسالة:", data["message_id"])
  ```

  ```bash Shell expandable theme={null}
  #!/bin/bash

  API_BASE_URL="https://cloud.gorbit.app/api"  # أو نطاقك الخاص
  API_KEY="YOUR_KEY_HERE"

  RESPONSE=$(curl -s -X POST "${API_BASE_URL}/chat/send-chat-message" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "ما هو Gorbit؟"
    }'
  )

  echo "الإجابة:" $(echo "$RESPONSE" | jq -r '.answer')
  echo "معرف الرسالة:" $(echo "$RESPONSE" | jq -r '.message_id')
  ```
</CodeGroup>

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="الدليل: استخدام واجهة الاستيعاب" icon="upload" href="/developers/guides/index_files_ingestion_api">
    استخدم واجهة الاستيعاب الخفيفة لفهرسة المستندات
  </Card>

  <Card title="الدليل: إنشاء موصل" icon="link" href="/developers/guides/create_connector">
    تعلم كيفية إنشاء وتكوين الموصلات برمجيًا
  </Card>
</CardGroup>