مساعد المحادثة عبر API

آخر تحديث: 2026-10-033 دقيقة قراءة

المستشار نفسه الذي يعمل في لوحة التحكم متاح من تطبيقك. تنشئ جلسة، وتفتح التدفق، وترسل رسالة، وتتلقى الرد على أجزاء. يتطلب النطاق tools:chat.

كيف يعمل

أنشئ جلسة: تحفظ سياق المحادثة.
افتح تدفق أحداث الجلسة.
أرسل رسالة.
يصل الرد عبر التدفق على أجزاء حتى يكتمل.

افتح التدفق قبل إرسال الرسالة، وإلا فاتتك الأجزاء الأولى من الرد.

الجلسات

الطلب	ماذا يفعل
`POST /chat/sessions`	إنشاء جلسة
`GET /chat/sessions`	جلساتك: `limit` من 1 إلى 50 (الافتراضي 20، والأكثر يعطي `400`)، و`cursor`، و`q` (بحث في العناوين)، و`projectId`، و`archivedOnly`، و`sort` (`recent`، `title`)
`PATCH /chat/sessions/{id}`	تعديل جلسة؛ حقل واحد على الأقل
`DELETE /chat/sessions/{id}`	الأرشفة

جسم POST /chat/sessions (كل الحقول اختيارية):

الحقل	الوصف
`title`	اسم الجلسة، حتى 200 حرف
`projectId`	المشروع الذي تنتمي إليه الجلسة
`mode`	`chat_consult` (افتراضي)؛ أي قيمة أخرى تُستبدل بـ `chat_consult`

حقول PATCH /chat/sessions/{id}:

الحقل	الوصف
`title`	اسم جديد، حتى 200 حرف
`projectId`	نقل إلى مشروع؛ `null` إخراج من المشروع
`isPinned`	التثبيت أو إلغاؤه
`isUnread`	وضع علامة غير مقروءة أو مقروءة
`isArchived`	`false` فقط: استعادة جلسة مؤرشفة؛ والأرشفة عبر `DELETE`

curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"سؤال عميل عن الرهن العقاري"}'

يحتوي الرد على sessionId: مرره في كل الاستدعاءات التالية. يتطلب إنشاء الجلسة ملف حساب مكتملا، وإلا فالرد 400.

توفر API وضع المستشار العام. وضع الرد التلقائي الذي يعمل داخل CRM لوحة التحكم لا يمكن تفعيله من الخارج.

إرسال رسالة

curl -X POST https://developers.grem.capital/api/v1/chat/messages \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"SESSION_ID","text":"كم سعر شقة من غرفتين في Podil؟","clientMessageId":"msg-0001"}'

clientMessageId: معرّف رسالتك، إلزامي. يُجاب على المعرّف نفسه ويُخصم مرة واحدة: أعد استخدامه عند الإعادة؛ إنه Idempotency-Key الخاص بالمحادثة.
style (اختياري): طول الرد، short أو normal أو detailed.

الرد مجرد إقرار بالاستلام؛ ويصل رد المساعد عبر التدفق.

تدفق الرد

GET /chat/stream?sessionId=SESSION_ID
Authorization: Bearer gsk_live_xxx
Accept: text/event-stream

الاتصال طويل الأمد، وتصل الأحداث أثناء توليد الرد:

الحدث	المعنى
`assistant.started`	بدأ المساعد الرد
`assistant.delta`	الجزء التالي من النص، في `delta`
`assistant.done`	اكتمل الرد، والنص الكامل في `text`

إذا انقطع الاتصال فأعد الاتصال بالقيمة sessionId نفسها: يعيد الخادم تشغيل الرد الحالي من بدايته. لذلك امسح عند assistant.started النص الذي جمعته لهذه الرسالة، وإلا تكرر.

GET /chat/history?sessionId=SESSION_ID&limit=50: الرسائل المحفوظة في الجلسة، من الأقدم إلى الأحدث. وlimit من 1 إلى 200 (الافتراضي 50)؛ والصفحة التالية عبر cursor بقيمة nextCursor من الرد السابق. استخدمه لاستعادة المحادثة بعد إعادة تحميل واجهتك.

الفوترة

الإجراء	الخصم
`POST /chat/messages`	استدعاء API + سعر الرسالة
`POST`، `PATCH`، `DELETE` على الجلسات	استدعاء API
`GET` القائمة، والسجل، والتدفق	مجاني

لخطة Free حد يومي للرسائل. بعده يصل 429: تابع غدا أو غيّر الخطة. ويحمل الرد code: free_daily_limit وRetry-After حتى الساعة 00:00 UTC حين يُعاد ضبط الحد.

كيف يعمل

الجلسات

إرسال رسالة

تدفق الرد

السجل

الفوترة

مقالات ذات صلة