لوحتك أنت بدل لوحتنا
اسحب المحادثات والعملاء والعروض إلى نظامك الداخلي واعرضها كما تشاء. لوحة ناطق ليست إلزامية.
GET /api/v1/conversations- الرئيسية
- للمطوّرين
واجهة برمجية وأحداث لحظية
متاحة في الباقة الاحترافية فأعلى، وتعمل فوق نسختك على خادمك. مفتاح واحد، أحداث JSON، وتوقيع تحقّق على كل طلب صادر.
المصادقة
مفتاح في الترويسة
كل طلب يحمل مفتاحك في ترويسة Authorization. المفاتيح تُنشأ وتُلغى من لوحة التحكم، ولا تُعرض مرة أخرى بعد الإنشاء.
القاعدة: مفتاح لكل تكامل. إلغاء مفتاح لا يوقف البقية.
والعنوان الأساسي هو نطاقك أنت: ناطق يعمل على خادمك لا على سحابة مشتركة.
# طلب بيانات عميل — استبدل النطاق بنطاق خادمك curl https://bot.example.sa/api/v1/customers/966501234567 \ -H "Authorization: Bearer $NAATEQ_KEY" \ -H "Accept: application/json"
Webhooks
الأحداث التي تصلك لحظياً
تسجّل رابطاً واحداً، فتصلك كل الأحداث عليه بصيغة JSON مع توقيع X-Naateq-Signature.
message.receivedوصلت رسالة من عميل. تحمل النص، ورقم المرسل، والنية المصنَّفة.reply.sentردّ النظام. تحمل الرد، والمصدر (آلي / أداة / بشري)، وزمن المعالجة.stage.changedانتقل العميل بين المراحل الأربع. تحمل المرحلة السابقة والجديدة.quote.issuedصدر عرض سعر. تحمل رقم المستند والإجمالي ورابط PDF.contract.approvedوافق المالك على إرسال عقد. تحمل رقم العقد والقيمة.handoff.requestedطلب تصعيد لموظف بشري. تحمل سبب التصعيد ونص المحادثة كاملاً.guard.blockedحجب حارس المدخلات رسالة. تحمل نوع المحاولة والنص المحجوب.POST /your-endpoint
X-Naateq-Signature: t=1780000000,v1=5f2b…
{
"event": "quote.issued",
"created_at": "2026-08-04T09:31:02.771Z",
"data": {
"doc_number": "HT-Q-260804-058",
"customer": { "number": "966501234567", "name": "محمد الحربي" },
"total": 4200,
"currency": "SAR",
"pdf_url": "https://bot.example.sa/api/v1/documents/HT-Q-260804-058/pdf"
}
}
التحقق من التوقيع
لا تثق بأي طلب غير موقّع
احسب HMAC-SHA256 على t + "." + body بمفتاح الويبهوك، وقارنه بالقيمة v1. ارفض أي طلب أقدم من خمس دقائق.
import crypto from "node:crypto";
export function verify(raw, header, secret) {
const [t, v1] = header.split(",").map(p => p.split("=")[1]);
if (Math.abs(Date.now()/1000 - +t) > 300) return false;
const expect = crypto
.createHmac("sha256", secret)
.update(`${t}.${raw}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expect), Buffer.from(v1)
);
}
حالات الاستعمال
ما الذي يُبنى فوق هذه الواجهة
مزامنة مع الـCRM
كل عميل جديد يصل ويبهوك فوري بمرحلته ومصدره، فيدخل مسارك في ثوانٍ بلا إدخال يدوي.
stage.changedتنبيه فريقك حيث يعمل
صعّد المحادثة إلى سلاك أو تيليجرام أو نظام تذاكرك لحظة تجاوز الحد الذي وضعته أنت.
handoff.requestedالحدود وسياسة البيانات
| البند | القيمة |
|---|---|
| حد الطلبات | 120 / دقيقة لكل مفتاح |
| تجاوز الحد | 429 مع ترويسة Retry-After |
| إعادة محاولة الويبهوك | 5 محاولات بتباعد أُسّي خلال 24 ساعة |
| مهلة استجابة نقطتك | 5 ثوانٍ |
| أين تُخزَّن البيانات | على خادمك — لا نسخة عندنا |
| الاحتفاظ والحذف | تضبطهما أنت. النظام لا يحذف من تلقائه |
تحتاج نقطة نهاية غير موجودة؟
الواجهة تتوسّع بطلبات العملاء. أخبرنا بما تبنيه.