متغيرات إجراءات AI

في أي موضع يمكنك كتابة قيمة فيه داخل إجراء API (عنوان URL أو الترويسات أو الجسم أو معاملات الاستعلام)، يمكنك إدراج قيم ديناميكية باستخدام صيغة {{...}}. يستبدل Quickchat هذه القيم النائبة وقت الطلب، مباشرة قبل استدعاء نقطة النهاية.

اضغط زر + إضافة بيانات AI بجانب أي حقل قيمة لاستعراض جميع المتغيرات المتاحة في السيناريو الحالي.

يتوفر زر + إضافة بيانات AI بجانب كل حقل قيمة: عنوان نقطة النهاية وقيمة كل ترويسة وحقول الجسم ومعاملات الاستعلام.

أدوات إعداد اختيارية

• عاين طلب إجراء API. اعرض قالب طلب تقدمه بقيم تجريبية اصطناعية دون إرساله. احذف ترويسات بيانات الاعتماد.

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

ثلاث فئات من المتغيرات

الفئة	الصيغة	متى تُملأ
معاملات AI. قيم يستخرجها وكيل AI من المحادثة. تعرّفها في قسم المعاملات لكل إجراء.	{{order_number}}، {{customer_email}}	يملؤها وكيل AI عند الاستدعاء وفق القواعد التي تكتبها في وصف كل معامل.
المتغيرات المدمجة. سياق المحادثة الذي يدرجه Quickchat تلقائيًا.	{{scenario_id}}، {{conversation_id}}، {{language}}، {{country}}، …	متاحة دائمًا. يستبدلها Quickchat في كل طلب.
البيانات الوصفية للمحادثة. أزواج مفاتيح وقيم مخصصة ملحقة بالمحادثة.	{{metadata_<key>}}	كلما وُجد المفتاح المقابل في المحادثة (بواسطة الأداة أو تكامل قناة أو جمع البيانات الذكي أو API).

نصيحة

يظهر كل متغير داخل المحرر كـ شريحة ملونة. الأزرق يعني معامل AI أو متغيرًا مدمجًا. البرتقالي يعني متغير بيانات وصفية أو رمز نظام. الأحمر يعني أن الاسم لا يطابق شيئًا يعرفه Quickchat، وغالبًا سببه خطأ إملائي.

قائمة ”+ إضافة بيانات AI”

تعرض القائمة كل متغير متاح للسيناريو الحالي ضمن خمسة أقسام:

1. المعاملات: معاملات AI التي عرّفتها لهذا الإجراء.
2. الزائر: أربعة مفاتيح بيانات وصفية تُلتقط تلقائيًا لكل زائر عندما توفرها قناته.
3. البيانات الوصفية (المستخدمة في المحادثات الأخيرة): مفاتيح مخصصة ظهرت في آخر 20 محادثة لهذا السيناريو، مع قيمة نموذجية لكل منها.
4. مدمج: متغيرات المحادثة السبعة المتاحة دائمًا، مع عرض قيمتها الحالية أو مثال بجانبها.
5. Tokens النظام: بيانات اعتماد يوفرها تكامل متصل، مثل HubSpot أو Telegram. يظهر فقط عند اتصال التكامل. راجع Tokens النظام أدناه.

تجمع القائمة المتغيرات في أقسام. تعرض صفوف مدمج القيمة الحالية عندما تكون معروفة (scenario_id) وأمثلة e.g. … للباقي. يعاد بناء مجموعة البيانات الوصفية (المستخدمة في المحادثات الأخيرة) لكل سيناريو من محادثات حديثة فعلية. يظهر قسم Tokens النظام (غير ظاهر هنا) فقط عند وجود تكامل متصل.

ملاحظة

يعاد بناء قائمة البيانات الوصفية (المستخدمة في المحادثات الأخيرة) من أحدث 20 محادثة في السيناريو وتُخزن مؤقتًا لمدة 5 دقائق لكل وكيل AI. قد يستغرق ظهور مفتاح أُضيف في محادثة جديدة تمامًا حتى 5 دقائق. يمكنك دائمًا كتابة {{metadata_<your_key>}} مباشرة؛ لا يشترط Quickchat ظهور المفتاح في القائمة لإجراء الاستبدال.

المتغيرات المدمجة

هذه المتغيرات السبعة متاحة دائمًا. تعرض قائمة + إضافة بيانات AI القيمة الحالية عندما تكون معروفة أو قيمة نموذجية بجانب كل صف.

المتغير	مثال	معناه
{{scenario_id}}	abc123xyz	معرّف وكيل AI الذي تنتمي إليه المحادثة.
{{conversation_id}}	conv-d8a8…	المعرّف الفريد للمحادثة.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	رابط مباشر لهذه المحادثة في صندوق الوارد.
{{conversation_channel}}	widget، telegram، slack، whatsapp، …	القناة التي تجري عليها المحادثة.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	التاريخ والوقت الحاليان بتوقيت UTC بصيغة ISO 8601.
{{language}}	en، nl، de، fr، …	رمز لغة المحادثة بأحرف صغيرة وفق ISO 639-1.
{{country}}	US، GB، NL، DE، …	رمز البلد بأحرف كبيرة وفق ISO 3166-1 alpha-2.

ملاحظات مفيدة:

• يظهر {{scenario_id}} أيضًا في عنوان المتصفح أثناء تحرير الإجراء. تعرض قائمة + إضافة بيانات AI المعرّف الفعلي للسيناريو الذي تعدله، لا مثالًا.
• يفيد {{conversation_url}} لنشر روابط قابلة للنقر في Slack أو Jira أو أي أداة تستفيد من العودة المباشرة إلى صندوق الوارد.
• يُشتق {{language}} بهذا الترتيب: بادئة عنوان الصفحة (في Shopify Markets)، ثم بيانات المحادثة الوصفية، ثم اللغة المضبوطة لوكيل AI.
• يُشتق {{country}} بهذا الترتيب: بادئة عنوان الصفحة، ثم نطاق المستوى الأعلى لمضيف URL، ثم خيار احتياطي يربط اللغة ببلد.

البيانات الوصفية للمحادثة

البادئة metadata_ مطلوبة. يبحث Quickchat عن <key> في البيانات الوصفية للمحادثة ويستبدله بقيمته في الطلب.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

مفاتيح بيانات الزائر الوصفية

تصف هذه المفاتيح الأربعة جلسة الزائر ولها قسم الزائر الخاص بها في القائمة. يمكن أن تلتقطها القناة أو التكامل أو الأداة/التضمين أو API أو جمع البيانات الذكي أو روابط مدخلات الإجراءات المضبوطة.

المتغير	ما يلتقطه تلقائيًا
{{metadata_fullPathURL}}	أداة الموقع أو تضمين الموقع أو تكاملات قنوات الدردشة التي تتضمن أداتها، مثل HubSpot وIntercom.
{{metadata_visitor_name}}	ملف قناة الدردشة (Telegram وSlack وغيرها) أو تكاملات القنوات أو جمع البيانات الذكي أو روابط مدخلات الإجراءات المضبوطة أو أداتك/تضمينك أو Quickchat API.
{{metadata_visitor_email}}	ملف قناة الدردشة أو تكاملات القنوات أو روابط مدخلات الإجراءات المضبوطة أو أداتك/تضمينك أو Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp والقنوات التي تعرف رقم الهاتف أو تكاملات القنوات أو روابط مدخلات الإجراءات المضبوطة أو أداتك/تضمينك أو Quickchat API.

مفاتيح بيانات وصفية مخصصة

يمكنك إرفاق أزواج مفاتيح وقيم بالمحادثة والإشارة إليها بصيغة {{metadata_<key>}}.

من أداة الموقع أو التضمين

مرر custom_params عند تهيئة الأداة. راجع قسم قناة الموقع: الميزات المتقدمة: المعاملات المخصصة للمقطع الكامل.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

أشر إليها في أي إجراء بصيغة {{metadata_order_id}} و{{metadata_customer_tier}}.

تنبيه

يجب أن تطابق مفاتيح البيانات الوصفية ^[a-zA-Z0-9_]+$ (أحرف وأرقام وشرطات سفلية). المفاتيح ذات المسافات أو علامات الترقيم الأخرى لا يمكن الإشارة إليها بصيغة {{metadata_<key>}}. تظل ظاهرة في عرض البيانات الوصفية للمحادثة بصندوق الوارد، لكن استبدال الإجراء يتخطاها. التزم بأسماء snake_case عندما تنوي استخدامها في الإجراءات.

من جمع البيانات الذكي

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

نقطة البيانات	المتغير
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

بيانات الاتصال استثناء. نقطة باسم Email أو Name أو Phone number (أو اسم إنجليزي قريب مثل Email address أو Full name أو Mobile) تملأ {{metadata_visitor_email}} أو {{metadata_visitor_name}} أو {{metadata_visitor_phone_number}} بدلًا من ذلك. لا تُعرف إلا الأسماء الإنجليزية: نقطة باسم Correo electrónico تصبح مفتاحًا مستقلًا هو correo_electronico. عندما يلتقط وكيل AI بيانات اتصال لم تكن موجودة في المحادثة، يضبط أيضًا lead_captured إلى true.

• فارغ حتى الالتقاط. يُضاف المفتاح بقيمة فارغة في أول رد لوكيل AI مع تفعيل جمع البيانات الذكي، ويُملأ عندما يقدم الزائر المعلومة. يحدثه التصحيح اللاحق، ولا يُفرغ مرة أخرى.
• استخدم is true لانتظار قيمة. في التشغيل عندما، ينجح budget is true بعد التقاط قيمة، بينما ينجح budget exists فور تشغيل جمع البيانات الذكي. تُعد إجابات مثل no وfalse و0 خاطئة منطقيًا.
• قيمك لها الأولوية. إذا احتوى المفتاح بالفعل على قيمة من موقعك أو API أو إجراء آخر، يتركها جمع البيانات الذكي دون تغيير. ويتوقف أيضًا عن تحديث المفتاح بمجرد أن يغيره شيء آخر.
• بعض الأسماء محجوزة، مثل language وlocale وlead_captured. لا تصبح نقطة البيانات بأحد هذه الأسماء متغيرًا؛ أعد تسميتها إذا احتجت إلى ذلك.
• إعادة تسمية نقطة البيانات تعيد تسمية متغيرها. حدّث الإجراءات التي تستخدمه؛ لا يستطيع الإجراء العمل إذا غاب متغير يحتاجه عن المحادثة.

بمجرد أن تحتوي المحادثة على المفتاح، يظهر أيضًا في قائمة + إضافة بيانات AI.

تحقق من شروط تشغيل الإجراءات باستخدام بيانات وصفية تجريبية لمعرفة الشروط الناجحة. يقيّم الفحص القيم المقدمة دون تشغيل إجراء.

من مدخلات إجراء أو استجابته

يمكن لإجراء API حفظ مدخل معرّف أو قيمة من استجابة API في مفتاح بيانات وصفية ليعيد إجراء لاحق استخدامها. في حفظ في الذاكرة، اختر مدخلات الإجراء أو استجابة API في المصدر. ضمن القيمة المراد حفظها، اختر معامل الإجراء من القائمة للمدخلات أو أدخل تعبير JSONPath للاستجابات، ثم اختر مفتاح الذاكرة. أشر إلى القيمة بصيغة {{metadata_<memory key>}}.

تملأ روابط المدخلات إلى visitor_name وvisitor_phone_number وvisitor_email أيضًا حقول الاتصال غير المعينة في صندوق الوارد. تُحفظ القيم الموجودة والحقول التي مسحها موظف صراحة. تُحفظ المدخلات قبل طلب HTTP بعد اجتياز الإجراء فحوصه، فتظل بيانات الاتصال الصالحة متاحة إذا فشل API. راجع حفظ في الذاكرة للأمثلة والشرح الكامل.

من تكاملات القنوات

تدفع تكاملات HubSpot وIntercom وTelegram وSlack وWhatsApp وما شابه بياناتها الوصفية إلى المحادثة (اسم الزائر وبريده وعنوان الصفحة وخصائص الحساب وغيرها). يمكن الإشارة إلى أي شيء يظهر في عرض البيانات الوصفية للمحادثة بصندوق الوارد باستخدام {{metadata_<key>}}.

من Quickchat API

استخدم POST /v1/api_core/conversations/{conv_id}/metadata لإرفاق البيانات الوصفية برمجيًا. راجع البيانات الوصفية للمحادثة في مرجع API.

Tokens النظام

تعرض بعض التكاملات المتصلة رمز نظام: بيانات اعتماد يدرجها Quickchat في الطلب على الخادم وقت الاستدعاء عند تشغيل الإجراء. لا يُضاف الرمز إلى سياق AI أو بيانات المحادثة الوصفية، ويُحجب من سجل الطلب والتتبع وسجل الاستدعاءات بصندوق الوارد. لا تملك البيانات الوصفية العادية ضمانات السرية نفسها. لا يظهر الرمز في قسم Tokens النظام ضمن قائمة + إضافة بيانات AI إلا عند اتصال التكامل المطابق، ويظهر كشريحة برتقالية.

رمز النظام	متى يتوفر	ما يدرجه
{{hubspot_access_token}}	عندما يكون HubSpot متصلًا	رمز وصول HubSpot OAuth صالح يتجدد تلقائيًا.
{{telegram_bot_token}}	عندما يكون للسيناريو نشاط Telegram	رمز بوت Telegram المتصل، لاستدعاء Telegram Bot API.

استدعاء Telegram Bot API

يأخذ Telegram Bot API رمز البوت في مسار URL، لذا أشر إليه مباشرة في عنوان نقطة النهاية:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

يحل Quickchat الرمز وقت الاستدعاء ويحجبه في كل مكان يظهر فيه الطلب، فلا يتسرب السر. لتوجيه استدعاء Bot API إلى الدردشة أو الرسالة أو المرسل الحالي، اجمعه مع مفاتيح بيانات Telegram الوصفية التي يضبطها Quickchat في كل رسالة واردة:

مفتاح البيانات الوصفية	القيمة
{{metadata_telegram_chat_id}}	الدردشة التي جاءت منها الرسالة.
{{metadata_telegram_chat_type}}	private أو group أو supergroup أو channel.
{{metadata_telegram_user_id}}	معرّف مستخدم Telegram للمرسل.
{{metadata_telegram_username}}	اسم @username للمرسل إن وجد.
{{metadata_telegram_message_id}}	معرّف الرسالة الواردة.
{{metadata_telegram_sender_is_admin}}	true عندما يكون المرسل مسؤولًا في الدردشة. تُحسب على الخادم فلا يمكن تزويرها من الدردشة. استخدمها في شرط تشغيل لقصر إجراءات الإشراف على المسؤولين.
{{metadata_telegram_reply_to_message_id}}، {{metadata_telegram_reply_to_user_id}}، {{metadata_telegram_reply_to_text}}	تُضبط عندما تكون الرسالة الواردة ردًا، ليتمكن AI من التصرف على الرسالة الأصلية، مثل الإشراف على كاتبها.

ألوان الشرائح في المحرر

تظهر كل إشارة {{...}} كشريحة ملونة لتعرف سريعًا هل يتعرف Quickchat على المتغير.

تعمل الشرائح في كل حقل قيمة. أعلاه: شريحة {{metadata_user_type}} برتقالية في عنوان نقطة النهاية وشريحة {{language}} زرقاء في قيمة ترويسة.

تسري قواعد الألوان نفسها داخل جسم طلب JSON. تظهر المتغيرات المدمجة مثل {{country}} بالأزرق، ومتغيرات البيانات الوصفية مثل {{metadata_fullPathURL}} بالبرتقالي.

• 🔵 أزرق: متغير مدمج أو معامل AI عرّفته.
• 🟠 برتقالي: متغير بيانات وصفية ({{metadata_*}}) أو رمز نظام من تكامل متصل.
• 🔴 أحمر: لا يتعرف Quickchat على الاسم. غالبًا خطأ إملائي. صحح الكتابة أو عرّفه كمعامل AI، أو تأكد أنه يبدأ بـ metadata_ إن كان فعلًا مفتاح بيانات وصفية.

نصيحة

كتابة {{metadata_anything}} مباشرة صالحة دائمًا، حتى لو لم يظهر المفتاح في محادثة بعد. تكون الشريحة برتقالية لا حمراء. هذه الطريقة الصحيحة لربط مفاتيح تضبطها بنفسك من برنامج الأداة أو جمع البيانات الذكي قبل حدوث أول محادثة.

اختبار الإجراء

تتيح لوحة اختبار الاستجابة (بجوار تم في محرر الإجراء) إرسال طلب HTTP فعلي دون المرور بدردشة. سترى صف إدخال لكل متغير مستخدم في الإجراء لتعبئة القيمة التي سيستبدلها Quickchat.

تملأ اللوحة مسبقًا كل متغير مدمج بسياق حالي أو قيمة اختبار تمثيلية. تشمل قيم اللغة والوقت الافتراضية:

• القيمة الافتراضية لـ {{language}} هي en
• القيمة الافتراضية لـ {{country}} هي US
• القيمة الافتراضية لـ {{current_timestamp}} هي وقت UTC الحالي

غيّر أي حقل لاختبار قيمة مختلفة. تبدأ معاملات AI ومفاتيح {{metadata_*}} فارغة. اكتب أي قيمة لمحاكاة ما يحدث في محادثة فعلية.

الأسئلة الشائعة

لماذا يظهر المتغير بالأحمر؟ لا يتعرف المحرر على الاسم. قد يكون خطأ إملائيًا، أو لا يطابق معامل AI عرّفته، أو ليس متغيرًا مدمجًا، أو مفتاح بيانات وصفية تنقصه البادئة metadata_.

هل يمكن إدراج {{language}} أو {{country}} حتى إن لم أضبطهما؟ نعم. يشتق Quickchat كليهما دائمًا من سياق المحادثة (عنوان الصفحة أو لغة المتصفح أو لغة وكيل AI المضبوطة). تحصل دائمًا على قيمة، حتى إذا رجع إلى en / US.

ما الفرق بين {{language}} و{{metadata_locale}}؟

• {{language}} هو المتغير المدمج. متاح دائمًا وبصيغة en / nl / de … استخدمه في 99% من الحالات.
• لا يوجد {{metadata_locale}} إلا إذا ضبط تكامل قناة أو أداتك مفتاح locale صراحة في بيانات المحادثة الوصفية، غالبًا بصيغة xx_YY مثل en_GB. استخدمه فقط عندما تحتاج إلى نص الإعداد المحلي نفسه حرفيًا.

هل يوجد حد لعدد معاملات AI لكل إجراء؟ نعم، 30 لكل إجراء. إذا احتجت فعلًا أكثر، تواصل مع الدعم.

هل تُرسل القيم المدمجة والبيانات الوصفية إلى AI؟ يستبدل Quickchat هذه القيم عند تكوين طلب HTTP؛ لا يحتاج AI إلى توليدها أو تعريفها كمعاملات AI. في إجراء AI يقرر، يحدث الاستبدال بعد اختيار AI للإجراء. الإجراءات التلقائية لا تطلب من AI اختيارها.

الاستبدال وسياق النموذج أمران منفصلان. قد تتوفر أيضًا البيانات الوصفية المؤهلة والسياق المدمج لـ AI، وقد تحتوي استجابة الإجراء على القيم نفسها. تُستبعد بيانات وصفية أخرى من التعليمات. لا تفترض أن البيانات الوصفية العادية مرئية دائمًا للنموذج أو مخفية دائمًا عنه. راجع سياق النموذج والتفويض.

كم مرة تتحدث قائمة “البيانات الوصفية (المستخدمة في المحادثات الأخيرة)”؟ تُخزن مؤقتًا لمدة 5 دقائق لكل وكيل AI. قد يستغرق ظهور مفتاح جديد في محادثة حديثة حتى 5 دقائق في القائمة، لكن يمكنك دائمًا كتابة {{metadata_<your_key>}} مباشرة دون انتظار.

هل تراعي أسماء مفاتيح البيانات الوصفية حالة الأحرف؟ نعم. {{metadata_orderId}} و{{metadata_orderid}} مفتاحان مختلفان. استخدم حالة الأحرف نفسها التي ضبطتها في الأداة أو التكامل أو API.

هل تعرف لوحة اختبار الاستجابة هذه المتغيرات؟ نعم. تملأ لوحة اختبار الاستجابة المتغيرات المدمجة السبعة مسبقًا، ومنها {{language}} بقيمة en و{{country}} بقيمة US و{{current_timestamp}} بوقت UTC الحالي. تبدأ معاملات AI ومتغيرات البيانات الوصفية فارغة. اكتب أي قيمة لمحاكاة استدعاء فعلي.

ذات صلة

• إجراءات مخصصة: كيفية إنشاء إجراء API وضبطه.
• قناة الموقع: المعاملات المخصصة: كيفية دفع البيانات الوصفية من موقعك.
• API: البيانات الوصفية للمحادثة: كيفية دفع البيانات الوصفية برمجيًا.