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

<Note>
  هذه الواجهة قيد الإهمال لصالح واجهة [/chat/send-chat-message](/developers/guides/chat_new_guide) API،
  وستتم إزالتها بحلول نهاية يناير 2026.
</Note>

## تدفق المحادثة البسيط

*واجهة إرسال الرسالة البسيطة* هي أسرع طريقة للتفاعل مع Gorbit برمجيًا.

تحتوي نقطة النهاية هذه على معلمات مطلوبة أقل وتعيد حمولة JSON مختصرة موصوفة بواسطة `ChatBasicResponse`.

<Note>
  يجب تحديد إما `chat_session_id` أو `persona_id` في طلبك.
</Note>

<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"
  }

  '''
  - لإنشاء جلسة محادثة، راجع دليل تدفق المحادثة الكامل أدناه.
  - للعثور على persona_id الخاص بك، راجع نقطة نهاية قائمة الوكلاء في مرجع واجهة برمجة تطبيقات الوكلاء.
  '''

  response = requests.post(
    f"{API_BASE_URL}/chat/send-message-simple-api",
    headers=headers,
    json={
      "message": "ما هو Gorbit؟",
      "persona_id": 0  # وكيل بحث Gorbit الافتراضي (int)
    }
  )

  data = response.json()
  answer = data.get("answer")
  answer_citationless = data.get("answer_citationless")
  message_id = data.get("message_id")
  docs = data.get("top_documents") or []
  top_documents = [
    {
      "id": doc.get("document_id"),
      "title": doc.get("semantic_identifier"),
      "link": doc.get("link")
    } for doc in docs
  ]
  cited_docs_map = data.get("cited_documents") or {}

  print(f"الإجابة: {answer}")
  print(f"الإجابة (بدون استشهادات): {answer_citationless}")
  print(f"معرف الرسالة: {message_id}")
  print(f"أهم المستندات: {top_documents[:5]}") # طباعة أهم 5 مستندات
  print(f"خريطة الاستشهادات: {cited_docs_map}")
  ```

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

  API_BASE_URL="https://cloud.gorbit.app/api"
  API_KEY="YOUR_KEY_HERE"

  echo "جارٍ إرسال رسالة إلى Gorbit..."
  RESPONSE=$(curl -s -X POST "${API_BASE_URL}/chat/send-message-simple-api" \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "ما هو Gorbit؟",
      "persona_id": 0
    }'
  )

  echo "الإجابة:"
  echo $RESPONSE | jq -r '.answer'

  echo -e "\nالإجابة (بدون استشهادات):"
  echo $RESPONSE | jq -r '.answer_citationless'

  echo -e "\nمعرف الرسالة:"
  echo $RESPONSE | jq -r '.message_id'

  echo -e "\nأهم المستندات:"
  echo $RESPONSE | jq '.top_documents | .[] | {id: .document_id, title: .semantic_identifier, link: .link}'
  ```
</CodeGroup>

## تدفق المحادثة المتقدم

نقطة النهاية `/send-message` هي ما تستخدمه واجهة Gorbit الأمامية لإرسال واستلام الرسائل.
يتم بث الردود في حزم من كائنات JSON.

لفهم تنسيق الاستجابة، راجع [توثيق المفاهيم الأساسية](/developers/core_concepts/#chat).

<Steps>
  <Step title="تحضير طلبك">
    <CodeGroup>
      ```python Python 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"
      }
      ```

      ```bash Shell theme={null}
      API_BASE_URL="https://cloud.gorbit.app/api"
      API_KEY="YOUR_KEY_HERE"
      ```
    </CodeGroup>
  </Step>

  <Step title="إنشاء جلسة محادثة">
    <CodeGroup>
      ```python Python theme={null}
      session_response = requests.post(
        f"{API_BASE_URL}/chat/create-chat-session",
        headers=headers,
        json={
          "persona_id": 0, # وكيل بحث Gorbit الافتراضي
          "description": "جلسة محادثة دليل Gorbit API"
        }
      )

      chat_session_id = session_response.json()["chat_session_id"]
      ```

      ```bash Shell theme={null}
      CHAT_SESSION_RESPONSE=$(curl -s -X POST "${API_BASE_URL}/chat/create-chat-session" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "persona_id": 0,
          "description": "جلسة محادثة دليل Gorbit API"
        }'
      )

      # استخراج معرف جلسة المحادثة (يتطلب jq لتحليل JSON)
      CHAT_SESSION_ID=$(echo $CHAT_SESSION_RESPONSE | jq -r '.chat_session_id')
      ```
    </CodeGroup>
  </Step>

  <Step title="إرسال رسالة">
    <CodeGroup>
      ```python Python theme={null}
      payload = {
        "chat_session_id": chat_session_id,
        "parent_message_id": None,
        "message": "ما هو Gorbit؟",
        "file_descriptors": [],
        "search_doc_ids": [],
        "retrieval_options": {}
      }

      # استهلاك الحزم المبثوثة بالكامل ثم طباعة ملخص
      # ملاحظة: الحزمة الأولى تحتوي دائمًا على معرفات الرسائل:
      #   {"user_message_id": int, "reserved_assistant_message_id": int}
      with requests.post(
        f"{API_BASE_URL}/chat/send-message",
        headers=headers,
        json=payload,
        stream=True,
      ) as resp:
        resp.raise_for_status()

        full_text = []
        docs_raw = None
        citations_map = {}
        user_message_id = None
        reserved_assistant_message_id = None

        # كل سطر هو حزمة JSON: { ind: int, obj: { type: "...", ... } }
        for line in resp.iter_lines(decode_unicode=True):
          if not line:
            continue
          try:
            packet = json.loads(line)
          except Exception:
            continue

          # الحزمة الأولى: معرفات الرسائل
          if "user_message_id" in packet and "reserved_assistant_message_id" in packet:
            user_message_id = packet.get("user_message_id")
            reserved_assistant_message_id = packet.get("reserved_assistant_message_id")
            continue

          obj = packet.get("obj", {})
          ptype = obj.get("type")

          if ptype == "message_start":
            # تتضمن مستندات البحث النهائية حسب مواصفات API
            docs_raw = obj.get("final_documents") or docs_raw
          elif ptype == "message_delta":
            delta = obj.get("content", "")
            full_text.append(delta)
          elif ptype == "citation_delta":
            # تحديث خريطة الاستشهادات باستخدام أزواج citation_num -> document_id
            if isinstance(obj.get("citations"), list):
              for c in obj["citations"]:
                cnum = c.get("citation_num")
                did = c.get("document_id")
                if cnum is not None and did is not None:
                  citations_map[str(cnum)] = str(did)
          elif ptype == "stop":
            break

      # تحضير المستندات (id/title/link) إذا كانت موجودة
      top_documents = []
      if isinstance(docs_raw, list):
        for d in docs_raw:
          top_documents.append(
            {
              "id": d.get("document_id") or d.get("id"),
              "title": d.get("semantic_identifier") or d.get("title"),
              "link": d.get("link") or d.get("url"),
            }
          )

      print("الإجابة النهائية:\n" + "".join(full_text))
      if user_message_id is not None:
        print(f"\nمعرف رسالة المستخدم: {user_message_id}")
      if reserved_assistant_message_id is not None:
        print(f"معرف رسالة المساعد المحجوز: {reserved_assistant_message_id}")
      print("\nأهم المستندات:")
      print(json.dumps(top_documents, indent=2))
      print("\nخريطة الاستشهادات (citation_num -> document_id):")
      print(json.dumps(citations_map, indent=2))
      ```

      ```bash Shell theme={null}
      # قراءة الاستجابة المبثوثة حتى الاكتمال (بدون عرض الرموز المميزة المباشر)
      curl -s -N -X POST "${API_BASE_URL}/chat/send-message" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d "{
          \"chat_session_id\": \"${CHAT_SESSION_ID}\",
          \"parent_message_id\": null,
          \"message\": \"ما هو Gorbit؟\",
          \"file_descriptors\": [],
          \"search_doc_ids\": [],
          \"retrieval_options\": {}
        }" \
        | (
          TEXT=""
          DOCS_JSON=""
          CITS_JSON='{}'
          USER_MSG_ID=""
          RESERVED_ASST_ID=""
          while IFS= read -r line; do
            [ -z "$line" ] && continue
            # الحزمة الأولى تحتوي على معرفات الرسائل
            uid=$(echo "$line" | jq -r '.user_message_id // empty')
            rid=$(echo "$line" | jq -r '.reserved_assistant_message_id // empty')
            if [ -n "$uid" ] || [ -n "$rid" ]; then
              [ -n "$uid" ] && USER_MSG_ID="$uid"
              [ -n "$rid" ] && RESERVED_ASST_ID="$rid"
              continue
            fi

            type=$(echo "$line" | jq -r '.obj.type // empty')
            if [ "$type" = "message_start" ]; then
              docs=$(echo "$line" | jq -c '(.obj.final_documents) // empty')
              if [ -n "$docs" ] && [ -z "$DOCS_JSON" ]; then
                DOCS_JSON="$docs"
              fi
            elif [ "$type" = "message_delta" ]; then
              delta=$(echo "$line" | jq -r '.obj.content // empty')
              TEXT+="$delta"
            elif [ "$type" = "citation_delta" ]; then
              newmap=$(echo "$line" | jq -c '
                if (.obj.citations // empty) then
                  (reduce (.obj.citations // [])[] as $c ({}; .[($c.citation_num|tostring)] = ($c.document_id|tostring)))
                else
                  {}
                end')
              CITS_JSON=$(jq -c --argjson A "$CITS_JSON" --argjson B "$newmap" '$A * $B' <<< '{}')
            elif [ "$type" = "stop" ]; then
              break
            fi
          done

          echo "الإجابة النهائية:"
          printf "%s\n" "$TEXT"

          echo
          if [ -n "$USER_MSG_ID" ]; then
            echo "معرف رسالة المستخدم: $USER_MSG_ID"
          fi
          if [ -n "$RESERVED_ASST_ID" ]; then
            echo "معرف رسالة المساعد المحجوز: $RESERVED_ASST_ID"
          fi

          echo
          echo "أهم المستندات:"
          if [ -z "$DOCS_JSON" ]; then
            echo "[]"
          else
            echo "$DOCS_JSON" | jq -c '[.[] | {id: (.document_id // .id), title: (.semantic_identifier // .title), link: (.link // .url)}]'
          fi

          echo
          echo "خريطة الاستشهادات (citation_num -> document_id):"
          echo "$CITS_JSON" | jq '.'
        )
      ```
    </CodeGroup>
  </Step>
</Steps>

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

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