DOCS / api

مرجع الواجهة

الحقول أدناه مقروءة من العقد الذي يتحقّق منه المحرّك، لا مكتوبة بجانبه. فإعادة تسمية حقل تعيد تسميته هنا، وإضافة حقل مطلوب تُضيف صفّاً — ولا توجد نسخة من هذه الصفحة تصف سلوكاً غير موجود.

المصادقة

مفتاح التاجر في ترويسة Authorization. المفتاح يُعرَض مرّة واحدة عند إنشائه؛ نحن نخزّن بصمته فقط، فلا سبيل لاستعادته.

Authorization: Bearer dl_live_…

وPOST /v1/messages يشترط أيضاً ترويسة Idempotency-Key. بدونها يُرفض الطلب — رسالة تُرسَل مرّتين بسبب إعادة محاولة شبكة هي ردّان لعميل واحد.

المسارات

القاعدة https://api.dlal.ai.

POST`/v1/sources`

يضيف مصدراً ويستوعبه فوراً، ويعيد عدد المقاطع.

الحقل	النوع	مطلوب
`type`	`"url" \| "sitemap" \| "file"`	نعم
`uri`	`string`	نعم
`body` محتوى مضمَّن لمصادر `file` فقط، ويُتجاهَل لغيرها.	`string`	لا

curl -X POST https://api.dlal.ai/v1/sources \
  -H "Authorization: Bearer $DLAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","uri":"https://help.example.com/shipping"}'

GET`/v1/sources`

يسرد المصادر المضافة وحالة مزامنة كلٍّ منها.

curl -X GET https://api.dlal.ai/v1/sources \
  -H "Authorization: Bearer $DLAL_KEY"

POST`/v1/messages`

يمرّر رسالة عميل خلال الحلقة ويعيد الرد وحالته.

الحقل	النوع	مطلوب
`conversation_id`	`string`	نعم
`user_id`	`string`	نعم
`channel`	`"api" \| "widget" \| "whatsapp" \| "email"`	نعم
`text`	`string`	نعم
`locale` الافتراضي `ar-SA`.	`string`	لا
`attributes` ما تعرفه أنت عن العميل. وهي القيم الوحيدة التي تُملأ بها معاملات الأدوات.	`object`	لا

curl -X POST https://api.dlal.ai/v1/messages \
  -H "Authorization: Bearer $DLAL_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"c_1","user_id":"u_1","channel":"api","text":"وين طلبي؟"}'

الأخطاء

كل خطأ يعيد error ورمزاً ثابتاً، وmessage يشرح، وrequest_id. الرمز هو ما تتفرّع عليه بالكود؛ النصّ قد يتغيّر.

{
  "error": "invalid_request",
  "message": "host 169.254.169.254 is in a private range",
  "request_id": "req_1c5a44cc-…"
}

واذكر request_id في أي بلاغ — هو المفتاح الذي نصل به إلى سطر هذا الطلب، ولا نحتفظ بنصّ الرسائل في السجلّات لنبحث به.