للمطورين
API للذكاء الاصطناعي بالعربي: اربط وكيل جنتال بأنظمتك
عندك تطبيق أو CRM أو نظام داخلي وتبي الوكيل يرد فيه؟ قناة API في جنتال تخلي أنظمتك تبدأ محادثة مع الوكيل، ترسل رسالة العميل، وتستلم الإجابة مع مصادرها، وكل المحادثات تظهر في صندوق الوارد مثل أي قناة.
آخر تحديث
وش تقدر تسوي بواجهة API لوكيل جنتال؟
مفاتيح API بصلاحيات
كل مفتاح له صلاحيات تختارها، وتقدر تحصره على وكلاء معينين. يظهر مرة وحدة بس، وإلغاؤه يوقفه على طول.
REST وردود متدفقة
استلم الإجابة كاملة بصيغة JSON مع المصادر، أو متدفقة كلمة كلمة عبر Server-Sent Events عشان تعرضها وهي تنكتب.
ملفات وصور
ارفع صورة أو ملف من عميلك داخل المحادثة، والوكيل يقرأه ويجاوب عليه.
Webhooks موقّعة
رسائل جديدة، ردود، تحويل لموظف، عملاء محتملين، وحالة الأرقام المربوطة. كل طلب موقّع بـ HMAC-SHA256، ويُعاد إرساله لو فشل.
تحويل لفريقك
لو موظف ماسك المحادثة، الـ API يخبرك، ورد الموظف يوصلك عبر Webhook.
الأرقام المربوطة من نظامك
أرسل رسائل من رقم واتساب مربوط، وأدِر جهات الاتصال، وحدد مين يرد على المحادثة: الوكيل أو شخص من فريقك.
كيف تربط الوكيل بنظامك خطوة بخطوة
التدفق باختصار، بدون تفاصيل الأخطاء والحدود:
أنشئ مفتاح API
من الإعدادات ثم المطورين، اختر صلاحية المحادثة مع الوكلاء، وانسخ المفتاح واحفظه في خادمك (مو في المتصفح أو تطبيق الجوال).
انشر الوكيل على قناة API
من صفحة الوكيل شغّل النشر على API. النسخة المنشورة بس هي اللي ترد، والمسودة تبقى عندك.
ابدأ محادثة
نظامك يطلب POST على /agents/{agentId}/conversations ويستلم رقم المحادثة.
أرسل رسالة العميل
POST على /conversations/{conversationId}/messages بنص الرسالة، وتستلم الإجابة مع المصادر وهل انجابت أو تحتاج موظف. أضف Accept: text/event-stream لو تبيها متدفقة.
استقبل الأحداث
أضف رابط Webhook، تحقق من التوقيع في كل طلب، وتجاهل التكرار برقم الحدث.
صلاحيات مفاتيح API
| الصلاحية | تسمح بـ |
|---|---|
| agents.chat | عرض الوكلاء، بدء المحادثات، وإرسال الرسائل وقراءتها |
| whatsapp.read | عرض الأرقام المربوطة وجهات اتصالها وحالة الإرسال |
| whatsapp.send | إرسال رسائل، إلغاء إرسال، وتحويل المحادثة لشخص أو للوكيل |
| whatsapp.contacts | حفظ وحذف جهات الاتصال، والتأكد إن الرقم عليه واتساب |
الأرقام المربوطة تحتاج تشغيل «الوصول عبر API» على الرقم نفسه. الربط غير رسمي وقد تقيّد Meta الرقم.
مصمم للأنظمة الحقيقية
- مفتاح Idempotency-Key على كل طلب كتابة، عشان إعادة المحاولة ما تكرر الرسالة.
- رسائل الأخطاء بالعربي أو الإنجليزي حسب Accept-Language.
- حدود واضحة للطلبات، مع Retry-After لما توصل الحد.
- إعادة إرسال الـ Webhook تلقائيًا لو فشل، مع سجل التسليم في لوحة التحكم.
- ما نسجّل مفاتيحك ولا روابط الـ Webhook ولا الأسرار في السجلات.
الأسئلة الشائعة
أسئلة تتكرر علينا
هل عند جنتال API للشات بوت؟
إيه. قناة API تخلي نظامك يبدأ محادثات مع الوكيل ويرسل الرسائل ويستلم الإجابات بـ REST أو متدفقة، ويستقبل الأحداث عبر Webhooks موقّعة.
من أي باقة تتوفر قناة API؟
من باقة Growth، ومع Business وEnterprise. كل إجابة عبر API تنحسب رد مثل باقي القنوات. التفاصيل في صفحة الأسعار.
هل أقدر أستخدم المفتاح من المتصفح؟
لا. خلّ المفتاح في خادمك فقط، وتطبيقك أو موقعك يكلم خادمك، وخادمك يكلم جنتال.
كيف أتأكد إن الـ Webhook جاي من جنتال؟
كل طلب فيه توقيع HMAC-SHA256 على الوقت ونص الطلب بسرّك الخاص. ارفض أي طلب توقيعه غلط أو وقته أقدم من 5 دقائق.
هل المحادثات عبر API تظهر لفريقي؟
إيه، تظهر في صندوق الوارد مثل أي قناة، ويقدر الموظف يستلم المحادثة.
اقرأ أيضًا
- التكاملاتمصادر المعرفة والأدوات والقنوات اللي يرتبط بها وكيلك اليوم، واللي جاية.
- رقم واتساب المربوطاربط رقم واتساب العادي برمز QR، ورد على المحادثات والتقط الطلبات من المجموعات.
- التحويل لموظف وصندوق الواردالوكيل يسلّم المحادثة لفريقك، وفريقك يرد من صندوق وارد مشترك في نفس القناة.
- الخصوصية وحماية البياناتوين تنحفظ بياناتك، ووش يوصل لمزوّد النموذج، وكيف نحمي معرفتك ومحادثات عملائك.
- موظف ذكاء اصطناعيموظف ذكاء اصطناعي يرد على عملائك وفريقك من معرفتك، ويسلّم لموظف حقيقي عند الحاجة.
