مساعد الدردشة عبر API

آخر تحديث: 2026-09-072 دقيقة قراءة

المستشار نفسه الذي يعمل في اللوحة متاح من تطبيقك. تنشئ جلسة، وترسل رسالة، ويصل رد المساعد قطعة قطعة عبر تدفق مفتوح.

يتطلب النطاق tools:chat. العنوان الأساسي: https://developers.grem.capital/api/v1.

كيف يعمل

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

والترتيب مهم: افتح التدفق قبل إرسال الرسالة، وإلا فاتتك القطع الأولى من الرد.

الجلسات

POST   /chat/sessions            create
GET    /chat/sessions            list
PATCH  /chat/sessions/{id}       rename, pin
DELETE /chat/sessions/{id}       move to the archive

الإنشاء:

curl -X POST https://developers.grem.capital/api/v1/chat/sessions \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Client question about a mortgage"}'

يحمل الرد معرف الجلسة الذي تمرره في كل استدعاء لاحق.

تمنحك الواجهة البرمجية المستشار العام. أما وضع الرد الآلي الذي يعمل داخل 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": "…",
    "text": "What does a two-room flat in Podil cost?",
    "clientMessageId": "msg-0001"
  }'

وclientMessageId هو معرفك أنت للرسالة. يربط ما أرسلته بما يصل عبر التدفق، فلا يظهر شيء مرتين عند إعادة الاتصال.

ويحدد الحقل الاختياري style طول الرد: short أو normal أو detailed.

تدفق الرد

GET /chat/stream?sessionId=…
Authorization: Bearer gsk_live_...
Accept: text/event-stream

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

الحدث	ماذا يعني
`assistant.started`	بدأ المساعد بالرد؛ وتتبعه قطع النص
`assistant.delta`	قطعة النص التالية، في الحقل `delta`
`assistant.done`	اكتمل الرد؛ ويحمل `text` النص كاملا

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

السجل

GET /chat/history?sessionId=…&limit=50

يعيد رسائل الجلسة المحفوظة. استخدمه لاستعادة المحادثة بعد إعادة تحميل واجهتك.

كم يكلف

يحتسب إرسال الرسالة وحده (POST /chat/messages). أما إنشاء الجلسة وقائمة الجلسات والسجل والتدفق نفسه فمجانية ولا تعد استدعاءات API.