الإجراءات: إجابات من نظامك الخاص

يتيح الإجراء للبوت الخاص بك البحث عن شيء ما في نظامك الخاص في منتصف الدردشة — أين الطلب، ومتى سيُسلَّم، وهل الحجز مؤكد. يسأل العميل، ويجمع البوت ما يحتاجه، ويستدعي واجهة API الخاصة بك، ويجيب مما يعود إليه، بلغة العميل.

يعمل في كل مكان يعمل فيه البوت الخاص بك: ودجة الموقع الإلكتروني، ورابط البوت ورمز QR الخاصين بك، وتطبيقات Android وiOS وReact Native وFlutter وIonic. لا يُثبَّت أو يُحدَّث أي شيء — يتم الاستدعاء من خوادمنا، لذا لا تصل بيانات اعتماد API الخاصة بك أبداً إلى متصفح أو هاتف.

قبل أن تبدأ: يمكن لأي شخص الدردشة مع البوت الخاص بك

البوت الخاص بك دردشة عامة. إذا كان رقم الطلب وحده كافياً لرؤية الطلب، فيمكن لأي شخص كتابة أرقام حتى يصيب أحدها.

يساعد البوت بثلاث طرق، لكن لا تغني أي منها عن ذلك التحقق: فهو يرسل فقط القيم التي كتبها العميل فعلاً، ويحدّ من عدد عمليات البحث التي يمكن لدردشة واحدة أو عنوان واحد إجراؤها، ويمكنك اختيار حقول الاستجابة المسموح له برؤيتها.

إعداد إجراء

افتح الإجراءات في لوحة التحكم واختر إجراء جديد. يمكن للمالكين والمشرفين رؤية هذه الشاشة.

• الاسم — لك أنت، مثل «حالة الطلب».
• متى ينبغي للبوت استخدامه؟ — جملة واحدة، كما تشرحها لزميل جديد: «يسأل العميل أين طلبه أو متى سيصل.»
• عنوان API الخاص بك — GET أو POST، وعنوان https://. اكتب {{order_id}} حيث توضع القيمة.
• ما يطلبه البوت من العميل — حتى ست قيم. لكل منها تسمية بكلماتك («رقم الطلب»)، والاسم الذي تستخدمه واجهة API الخاصة بك (order_id)، ونوع: أي نص، أو رقم، أو عنوان بريد إلكتروني، أو رقم هاتف.
• الترويسات — مفتاح API أو الرمز المميز الخاص بك. يُخزَّن مشفّراً ولا يُعرض مرة أخرى.
• مشاركة هذه الحقول فقط مع البوت — اختياري. أدرج أجزاء الاستجابة التي يمكن للبوت استخدامها، مثل status, eta, items[].name. يُحذف كل ما عدا ذلك قبل أن يراه الذكاء الاصطناعي.

اضغط اختبار، واكتب قيماً تجريبية، وسترى الطلب الذي أُرسل وبالضبط ما سيحصل عليه البوت. ثم جرّبه فعلياً في شاشة الاختبار: «أين طلبي رقم 48213؟ بريدي الإلكتروني هو asha@example.com».

ما تستقبله واجهة API الخاصة بك

مع GET، تُملأ القيم التي وضعتها في العنوان وتُضاف البقية إلى سلسلة الاستعلام:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

مع POST، تكون القيم هي محتوى JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

يحمل كل طلب أيضاً ترويساتك الخاصة وهذه الترويسات:

ما الذي تعيده

أجب خلال 8 ثوانٍ بصيغة JSON، أو بسطر قصير من النص العادي.

• 200 مع البيانات — يجيب البوت منها. أبقِها صغيرة واستخدم أسماء حقول واضحة: {"status":"shipped","eta":"2 October"} يعمل أفضل من الرموز الداخلية.
• 404 عندما لا يوجد تطابق — يخبر البوت العميل ويطلب منه التحقق مما كتبه.
• أي شيء آخر، أو عدم الرد في الوقت المحدد — يعتذر البوت، ويقدّم بيانات الاتصال الخاصة بك، وتُعلَّم الدردشة لك. يُعرض السبب في شاشة الإجراءات.

لا تُتبع عمليات إعادة التوجيه، ولا تُقرأ الاستجابة التي تتجاوز 256 KB.

التحقق من التوقيع

تُوقَّع الطلبات بطريقة Standard Webhooks، لذا يمكنك استخدام مكتبة موجودة. سر التوقيع الخاص بك موجود في شاشة الإجراءات.

يدوياً: اجمع المعرّف والطابع الزمني والمحتوى (body) بالضبط مفصولةً بنقاط، ووقّع الناتج باستخدام HMAC-SHA256 مع السر (الجزء الذي يلي whsec_، بعد فك ترميز base64)، ثم قارن.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

في طلب GET يكون المحتوى فارغاً، لذا ينتهي النص الموقَّع بنقطة. استخدم POST إذا أردت أن يشمل التوقيع القيم نفسها.

كيف يستخدمه البوت

• يسأل عن أي شيء ناقص، بسؤال قصير واحد في كل مرة، ويتذكر ما قاله العميل سابقاً في الدردشة.
• لا يخمّن قيمة أبداً. إذا لم يكتبها العميل، يسأله البوت.
• عملية بحث واحدة لكل رسالة. إجاباتك المحفوظة لها الأولوية دائماً، لذا فإن السؤال الذي أجبت عنه يدوياً لا يستدعي واجهة API الخاصة بك أبداً.
• لا يُعاد استخدام الإجابات الناتجة عن عملية بحث لعميل آخر أبداً.
• تُحتسب عملية البحث كإجابة واحدة، مثل أي رد آخر يكتبه الذكاء الاصطناعي.

في الدردشات، تشير الإجابة الناتجة عن عملية بحث إلى ذلك أسفلها: أي إجراء تم تشغيله وكيف انتهى. تبقى القيم التي كتبها العميل في نص المحادثة ولا في أي مكان آخر.

الحدود

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