# Make Agent Fast documentation (ar)

---

# سجل التغييرات

Source: /ar/docs/account/changelog.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;المنصة&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;API&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;الوثائق&#x22;, icon: &#x22;book&#x22; }]" />

## 2026-08-27 [#2026-08-27]

* توثيق إطلاق الوكيل انطلاقًا من عنوان URL: انتظار مرحلة الإنشاء، ثم **المراجعة والنشر**، ثم **الموافقة والنشر**، وتفعيل الوكيل عند أول محادثة لزائر أو أول عميل محتمل (lead).
* توثيق الفرق بين خيار المظهر **استخدام الموقع** وخياري الفاتح/الداكن، وأن حفظ المظهر يحدّث التضمين المباشر (وأي صفحات مستضافة متبقية) دون إعادة النشر.
* مواءمة مقتطفات التضمين مع سمات `embed.js` المعتمدة في النسخة المباشرة ومع معامل تجديد الذاكرة المؤقتة `?v=` في لوحة التحكم.
* توثيق المحادثة الصوتية المباشرة في أداة الاختبار على المنصة مقارنةً بالموقع المنشور والتضمين.
* إزالة النطاق المخصص وشراء النطاقات وإعدادات النطاق الفرعي كمنتج. يتم تضمين الوكيل في موقع العميل الحالي. وتبقى أحداث الإضافة الخاصة بنطاقات Polar المتبقية متجاهَلة أو ملغاة.

## 2026-07-28 [#2026-07-28]

* تبسيط سجل الاستخدام ليعرض الرصيد النهائي المستهلك من الاعتمادات بدلًا من صفوف منفصلة للحجز والاسترداد؛ ويظهر الاستخدام الضئيل الآن بصيغة `<0.001`.
* جعل زوايا التحديد في قائمة إجراءات الوثائق تتكيف مع المحتوى متعدد الأسطر، مع الحفاظ على تطابق هندسة زر التشغيل وإطار القائمة.
* توسيع الأدلة بالإنجليزية والكورية والأوزبكية لتشمل فوترة المكالمات المباشرة، وإدخال الوسائط في المنشئ المرئي، وتغييرات النطاق الفرعي المستضاف، وضوابط الخصوصية والأمان للحساب، وسجل أحداث الإشعارات.

## 2026-07-15 [#2026-07-15]

* إطلاق منصة وثائق Make Agent Fast ثنائية اللغة.
* إضافة Markdown لكل صفحة، وخيارات التنزيل، والبحث، وإجراءات ChatGPT وClaude.
* إضافة المسارات `/docs/llms.txt` و`/docs/llms-full.txt` ومسارات `.md` المعتمدة.
* توثيق واجهة API العامة وعقد SDK وwebhooks والتضمين والموصّلات (connectors) والعمليات والتسعير والأمان والخصوصية.
* إضافة أدلة تنفيذ لأبرز أطر العمل ومنشئي المواقع.

## سياسة الإصدارات [#سياسة-الإصدارات]

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

---

# الخطط والأسعار

Source: /ar/docs/account/pricing.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;الإطلاق&#x22;, icon: &#x22;layers&#x22; },
{ label: &#x22;التشغيل&#x22;, icon: &#x22;spark&#x22; },
{ label: &#x22;التوسع&#x22;, icon: &#x22;bolt&#x22; },
{ label: &#x22;باقات الرصيد&#x22;, icon: &#x22;layers&#x22; }
]"
/>

<TutorialVideo episode="ep08" start="132" />

## مقارنة الخطط [#مقارنة-الخطط]

| الخطة   | الفوترة الشهرية | الإجمالي السنوي | الرصيد الشهري |                         الوكلاء |   الصوت المباشر | شارة العلامة التجارية |
| ------- | --------------: | --------------: | ------------: | ------------------------------: | --------------: | --------------------- |
| Launch  |      $15/شهريًا |     $144/سنويًا |          1000 |                               1 |        غير متاح | إلزامية               |
| Operate |      $35/شهريًا |     $336/سنويًا |          3000 |                               3 | 30 دقيقة/شهريًا | يمكن إزالتها          |
| Scale   |      $79/شهريًا |     $758/سنويًا |          8000 | غير محدود، وفق الاستخدام العادل | 90 دقيقة/شهريًا | يمكن إزالتها          |

الفوترة السنوية أقل بنسبة 20% من دفع السعر الشهري اثنتي عشرة مرة. تبدأ خطتا Launch وOperate بفترة تجريبية مجانية لمدة سبعة أيام دون الحاجة إلى بطاقة ائتمان؛ أضف بطاقة بعد اليوم السابع لإبقاء الوكيل يعمل. أما خطة Scale فتبدأ فوترتها فورًا وليس لها فترة تجريبية. عند الحاجة إلى بطاقة، تعرض صفحة الدفع السعر الدقيق وفترة التجديد والضريبة والشروط قبل إتمام الشراء.

خطة Launch هي وكيل مضمَّن يعمل بالفعل خلال هذا الأسبوع. وخطة Operate هي الخطوة التالية حين يبدأ العملاء بالتحدث فعليًا مع الوكيل — صوت مباشر وأداة دردشة أكثر اكتمالًا وقنوات مراسلة. أما Scale فهي الاستوديو الكامل: كل عناصر التحكم في المظهر، وأدوار الفريق، ومفاتيح المزوّدين الخاصة بك.

## سلّم الميزات [#سلّم-الميزات]

| الإمكانية       | Launch                                    | Operate                                       | Scale                                                      |
| --------------- | ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------------- |
| الوكلاء         | 1                                         | 3                                             | غير محدود، وفق الاستخدام العادل                            |
| استوديو الأداة  | اللون المميز والموضع والوضع الفاتح/الداكن | + تسمية زر الفتح وإعدادات جاهزة وألوان إضافية | جميع عناصر التحكم (نصف القطر والظل والحدود والخط والزجاجي) |
| لغات الصوت      | 1                                         | 2                                             | جميع اللغات المدعومة                                       |
| استيعاب المعرفة | لصق وURL وملفات                           | + YouTube وبودكاست وRSS                       | مثل Operate                                                |
| قنوات المراسلة  | تستمر الاتصالات الحالية في العمل          | اتصالات جديدة                                 | اتصالات جديدة                                              |
| مفاتيحك الخاصة  | تستمر المفاتيح الحالية في العمل           | تستمر المفاتيح الحالية في العمل               | حفظ مفاتيح جديدة                                           |
| دعوات الفريق    | يبقى الأعضاء الحاليون                     | يبقى الأعضاء الحاليون                         | دعوات جديدة بأدوار                                         |

نحن لا نبيع نطاقات العملاء ولا نربطها بحساباتهم. ضمّن الوكيل في الموقع الذي تملكه بالفعل.

## متاح في جميع الخطط [#متاح-في-جميع-الخطط]

تتضمن جميع الخطط الحالية ما يلي:

* تضمين في الموقع الذي تملكه بالفعل (`embed.js` + `data-agent`).
* الدردشة النصية والرسائل الصوتية والأصوات الجاهزة واسترجاع المعرفة والأسئلة الشائعة/المنتجات المنظَّمة والتقاط العملاء المحتملين (Leads).
* التضمين في المواقع مع عناصر تحكم دقيقة في المصدر (origin).
* الوصول إلى API العامة بمفاتيح محدودة النطاق، وOAuth للتطبيقات التي تمت مراجعتها، وOpenAPI، وحدود معدل تتناسب مع الخطة.
* التحليلات والمحادثات وتتبع الاستخدام وإمكانية شراء باقات الرصيد.

حد استخدام API العامة هو 120 طلبًا لكل مفتاح API في الدقيقة في Launch، و600 في Operate، و1,800 في Scale. لا تحل حدود الطلبات هذه محل استحقاقات الموارد أو فحوصات الرصيد أو خاصية التكرار الآمن (idempotency) أو الحدود الخاصة بالمزوّدين. راجع [حدود المعدل](/ar/docs/api/rate-limits).

## فهم الرصيد [#فهم-الرصيد]

يُستخدم الرصيد لدفع تكلفة أعمال الذكاء الاصطناعي المقاسة، مثل التوليد وأدوار الوكيل وتضمينات المعرفة (embeddings) والتفريغ النصي وتركيب الكلام. وهو ليس عددًا ثابتًا من الرسائل: فالمزوّد والنموذج وطول المدخلات/المخرجات ومدة الوسائط ونوع العملية كلها تغيّر التكلفة.

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

تؤدي مفاتيح المزوّد الخاصة بك (BYOK) إلى رسوم منفصلة من OpenRouter (للنصوص) أو Speko (للصوت)، وهما المزوّدان اللذان يمكن إضافة مفتاح جديد لهما؛ وتستمر مفاتيح المزوّدين المباشرين الأقدم المحفوظة لديك في العمل حتى يتم إلغاؤها. حفظ المفتاح متاح في Scale فقط. عند استخدام مفتاحك الخاص، يكلّف كل إجراء رسم منصة ثابتًا (رصيد واحد لكل رد دردشة) بدلًا من الرسوم المبنية على الرموز (tokens). لا يحوّل BYOK فواتير المزوّدين إلى رصيد Make Agent Fast ولا يلغي فحوصات الاستحقاق الخاصة بالمنصة. راجع [مفاتيح مزوّدي الذكاء الاصطناعي](/ar/docs/account/provider-keys).

## استحقاقات الصوت [#استحقاقات-الصوت]

الرسائل الصوتية مشمولة في جميع الخطط، لكن أعمال التفريغ النصي والنموذج وتركيب الكلام المرتبطة بها قد تستهلك رصيدًا. أما الصوت المباشر في الوقت الفعلي فيستخدم حصة دقائق شهرية منفصلة: لا شيء في Launch، و30 دقيقة في Operate، و90 دقيقة في Scale.

## الوكلاء والعلامة التجارية [#الوكلاء-والعلامة-التجارية]

تدعم Launch وكيلًا واحدًا موجّهًا للعملاء، وتدعم Operate حتى ثلاثة وكلاء. أما وصف الوكلاء غير المحدودين في Scale فيخضع للاستخدام العادل، وليس دعوة لإنشاء أعداد مسيئة أو آلية من المساحات المستقلة (tenants). يتضمن الوكيل معرفته وإعدادات التضمين والموصلات والتحليلات وبيانات المحادثات. يحصل كل وكيل على رابط الوكيل، وهو صفحة دردشة عامة واحدة على نطاق فرعي خاص به. ما زالت صفحات العرض التجريبي المستضافة المتبقية تعمل على نطاقات فرعية؛ أما الوكلاء الجدد فلا يحصلون على صفحة تسويقية مستضافة.

تبقى شارة الإحالة «Made with Make Agent Fast» في Launch. ويمكن لمالكي حسابات Operate وScale إزالتها من المواقع المنشورة المستحقة.

## باقات الرصيد [#باقات-الرصيد]

| عملية الشراء |         السعر | ما الذي تغيّره                                            |
| ------------ | ------------: | --------------------------------------------------------- |
| باقة صغيرة   |  $8 مرة واحدة | تضيف 1000 رصيد لا تنتهي صلاحيتها ما دام الاشتراك قائمًا   |
| باقة متوسطة  | $35 مرة واحدة | تضيف 5000 رصيد لا تنتهي صلاحيتها ما دام الاشتراك قائمًا   |
| باقة كبيرة   | $90 مرة واحدة | تضيف 15,000 رصيد لا تنتهي صلاحيتها ما دام الاشتراك قائمًا |

تضيف عمليات الشحن سعة استخدام فقط. ولا تزيد عدد المواقع أو حدود طلبات API أو الدقائق المباشرة أو أذونات العلامة التجارية.

## الفترات التجريبية والتجديد والإلغاء [#الفترات-التجريبية-والتجديد-والإلغاء]

لا تتحول الفترة التجريبية المجانية في Launch/Operate تلقائيًا إلى اشتراك مدفوع: ففي اليوم السابع يتوقف الوكيل مؤقتًا إلى أن تضيف بطاقة. بعد حفظ بطاقة، قد يؤدي الإلغاء أو فشل التجديد إلى إزالة الوصول النشط بعد انتهاء فترة المزوّد أو انتقال الحالة المعمول به. وقد تتوقف عمليات التضمين والموصلات وعملاء API والمكالمات الصوتية رغم بقاء بيانات مساحة العمل المخزنة.

## اختيار خطة [#اختيار-خطة]

* اختر **Launch** لوكيل مضمَّن واحد مع الدردشة النصية والرسائل الصوتية وأداة دردشة أساسية.
* اختر **Operate** عندما يبدأ العملاء بالتحدث: مكالمات مباشرة وقنوات مراسلة وأداة دردشة مخصصة وصوت بلغتين أو إزالة الشارة.
* اختر **Scale** عندما يكون عدة وكلاء قيد الإنتاج: كل عناصر التحكم في الأداة، وصوت بكل اللغات المدعومة، وأدوار الفريق، ومفاتيح API الخاصة بك.

قدّر الاستخدام اعتمادًا على اختبارات قبول حقيقية لا على عدد الرسائل وحده. انشر وكيلًا واحدًا نموذجيًا، وقِس استخدام النصوص والصوت والمعرفة، ثم أسقِط ذلك على حجم الزيارات المتوقع وأضف هامشًا للمحاولات المتكررة والموصلات والأتمتة وذروات الإطلاق.

## المرجع الرسمي للفوترة [#المرجع-الرسمي-للفوترة]

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

---

# الخصوصية والبيانات

Source: /ar/docs/account/privacy.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;بيانات الزوار&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;الاحتفاظ بالبيانات&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;الضوابط&#x22;, icon: &#x22;shield&#x22; }]" />

يقرّر مالك الموقع المعرفة ومدخلات الزوار والتكاملات التي تُستخدم في تجربته. تعالج Make Agent Fast بيانات المنصة لتقديم الخدمة، وذلك وفقًا للشروط المعمول بها وإشعار الخصوصية.

## إشعار الزوار [#إشعار-الزوار]

اشرح استخدام الذكاء الاصطناعي والتسجيل وجمع بيانات العملاء المحتملين والتحليلات والمتابعة بلغة تناسب التجربة والمتطلبات المحلية. لا تطلب من الـ agent جمع بيانات لا تحتاج إليها.

## دورة حياة البيانات [#دورة-حياة-البيانات]

يؤثر حذف أحد المصادر (Sources) في عمليات الاسترجاع المستقبلية. ويؤدي حذف بيانات الاعتماد إلى إيقاف الوصول المصرّح به. أما المحادثات السابقة وملفات التصدير وبيانات القنوات الخارجية وسجلات المزوّدين، فقد تخضع لسياسات احتفاظ منفصلة.

## ضوابط المالك [#ضوابط-المالك]

يمكن من صفحة **التحليلات** (Analytics) في الموقع تصدير العملاء المحتملين (Leads) الذين تم جمع بياناتهم بصيغة JSON، وحذف عميل محتمل بعينه. كما يمكن تصدير تقارير التحليلات بصيغة Markdown أو Excel أو عرض الطباعة/PDF. ينشئ التصدير نسخة جديدة تحت سيطرتك؛ ولا يؤدي حذف سجل المنصة إلى محو أي تنزيل سابق، أو محادثة مرتبطة، أو سجل لدى مزوّد خارجي، أو بيانات يُحتفظ بها لمتطلب قانوني.

استخدم **إعدادات الحساب** لتسجيل الخروج من جميع الأجهزة أو لحذف الحساب نهائيًا. عند حذف الحساب، تُجرى أولًا محاولة إيقاف اشتراك المنصة واشتراكات إضافات النطاق المتبقية في Polar وموارد الموصّلات (Connectors)، ثم تُزال المواقع والـ agents والمعرفة والمحادثات والعملاء المحتملون وبيانات اعتماد API/OAuth والجلسات وسجل الفوترة المخزَّن محليًا الخاصة بالحساب. وإذا تعذّر التأكد من إيقاف الفوترة الخارجية، يفشل الحذف بشكل آمن ويُترك الحساب سليمًا لإعادة المحاولة بأمان أو لمراجعة الدعم.

## الطلبات [#الطلبات]

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

---

# مفاتيح مزوّدي الذكاء الاصطناعي

Source: /ar/docs/account/provider-keys.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;spark&#x22;, title: &#x22;توليد النصوص&#x22;, description: &#x22;مفتاح OpenRouter واحد يموّل توليد نصوص الوكيل عبر نماذجه.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;الكلام&#x22;, description: &#x22;مفتاح Speko واحد يموّل التفريغ النصي وتوليد الصوت.&#x22; },
{ icon: &#x22;shield&#x22;, title: &#x22;تخزين مشفّر&#x22;, description: &#x22;تُشفَّر المفاتيح الكاملة ولا تُعاد أبدًا بعد حفظها.&#x22; }
]"
/>

تتيح ميزة استخدام مفتاحك الخاص (BYOK) أن تستخدم طلبات الذكاء الاصطناعي المدعومة حسابك لدى مزوّد الذكاء الاصطناعي. لا تحتاج إلى مفتاح: فالمنصة توفّر النماذج افتراضيًا. يتطلب حفظ مفتاح باقة Scale. أما المفاتيح المحفوظة مسبقًا فتواصل العمل في باقتي Launch وOperate. وتظل تدفع اشتراك باقة Make Agent Fast بالإضافة إلى رسم ثابت للمنصة عن كل إجراء، بينما يحاسبك المزوّد مباشرة على استخدام نماذجه.

## المزوّدون المدعومون [#المزوّدون-المدعومون]

يمكن إضافة مفاتيح جديدة لمزوّدين اثنين فقط: أحدهما للنصوص والآخر للصوت:

| المزوّد    | الاستخدام                                                         | إنشاء مفتاح أو مراجعته                              |
| ---------- | ----------------------------------------------------------------- | --------------------------------------------------- |
| OpenRouter | توليد نصوص الوكيل عبر النماذج التي يوجّه OpenRouter الطلبات إليها | [مفاتيح OpenRouter API](https://openrouter.ai/keys) |
| Speko      | تحويل الكلام إلى نص وتحويل النص إلى كلام                          | [منصة Speko](https://platform.speko.ai)             |

### المفاتيح القديمة [#المفاتيح-القديمة]

تظهر مفاتيح المزوّدين المباشرين المحفوظة قبل الانتقال إلى OpenRouter وSpeko ضمن **المفاتيح القديمة**. تظل تعمل حتى تلغيها، ويمكنك إلغاؤها، لكن لا يمكنك إضافة مفتاح قديم أو استبداله:

| المزوّد القديم                                  | الاستخدام                                                    | مرجع المزوّد                                                                                                                                                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic وOpenAI وGoogle Gemini وxAI وDeepSeek | توليد نصوص الوكيل                                            | [وثائق Anthropic API](https://platform.claude.com/docs/en/api/overview)، [البدء السريع مع OpenAI API](https://developers.openai.com/api/docs/quickstart)، [مفاتيح Gemini API](https://ai.google.dev/gemini-api/docs/api-key) |
| Deepgram                                        | تحويل الكلام إلى نص عندما يكون Deepgram هو مزوّد STT المضبوط | [مفاتيح Deepgram API](https://developers.deepgram.com/docs/create-additional-api-keys)                                                                                                                                       |
| ElevenLabs                                      | تحويل النص إلى كلام عندما يكون ElevenLabs هو المضبوط         | [مصادقة ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)                                                                                                                                                 |

يعتمد توفّر المزوّدين أيضًا على مزوّدي النصوص والكلام والوقت الفعلي المضبوطين في المنصة. ولا يعني حفظ مفتاح صالح أن كل ميزة ستستخدم ذلك المزوّد حتمًا.

<Callout title="BYOK يختلف عن مفتاح Make Agent Fast API">
  يفوّض مفتاح المزوّد الرسوم واستدعاءات النماذج لدى مزوّد الذكاء الاصطناعي الخارجي. أما مفتاح `maf_live_...` فيفوّض برنامجك باستدعاء واجهة Make Agent Fast API العامة. لا تلصق أحدهما في حقل الآخر أبدًا.
</Callout>

## إضافة مفتاح مزوّد [#إضافة-مفتاح-مزوّد]

1. أنشئ مفتاحًا في وحدة تحكم OpenRouter أو Speko، وفعّل الفوترة لدى المزوّد أو حدًّا للإنفاق إذا لزم الأمر.
2. افتح **لوحة التحكم ← الإعدادات ← مفاتيح مزوّدي الذكاء الاصطناعي**. وحده مالك الفوترة في مساحة عمل Scale يستطيع حفظ مفتاح.
3. الصق المفتاح في بطاقة **OpenRouter** أو **Speko**.
4. اختر **اختبار وحفظ**.
5. انتظر نتيجة التحقق، ثم اختبر الميزة التي تستخدم المزوّد.

يُجري Make Agent Fast طلب تحقق مباشرًا قبل حفظ المفتاح، ولا يستهلك ذلك أي رموز نماذج أو أرصدة من المنصة. يجب ألا يحتوي المفتاح على مسافات أو فواصل أسطر، وأن يتراوح طوله بين 16 و512 حرفًا. يجب أن تبدأ مفاتيح OpenRouter بـ `sk-or-`، وأن تبدأ مفاتيح Speko بـ `sk_speko_` أو `sk_live_`. ويبقى التحقق المباشر هو المرجع النهائي.

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

## كيف يتم اختيار مزوّد النصوص [#كيف-يتم-اختيار-مزوّد-النصوص]

لتوليد النصوص، تكون الأولوية لمفتاح OpenRouter النشط. وإن لم يوجد، يبحث Make Agent Fast عن مفتاح قديم نشط يطابق مزوّد النصوص المضبوط في المنصة، ثم عن بقية مفاتيح النصوص القديمة (Anthropic وOpenAI وGemini وxAI وDeepSeek) بهذا الترتيب. وإذا لم يوجد مفتاح BYOK مناسب، يستخدم مزوّد المنصة متى سمحت الباقة والنشر بذلك.

مفاتيح الكلام خاصة بكل مزوّد. يُستخدم مفتاح Speko عندما يجري الكلام عبر Speko. ويُستخدم مفتاح Deepgram القديم فقط عندما يكون مزوّد تحويل الكلام إلى نص النشط هو Deepgram، ويُستخدم مفتاح ElevenLabs القديم فقط عندما يكون تحويل النص إلى كلام مضبوطًا على ElevenLabs.

لا تحلّ مفاتيح BYOK حاليًا محل بيانات اعتماد تضمين المعرفة الخاصة بالمنصة. يستمر استيعاب المعرفة واسترجاعها في استخدام مزوّد التضمين المضبوط في النشر.

## الفوترة والأرصدة [#الفوترة-والأرصدة]

* يحاسب المزوّد الخارجي استخدام رموز الذكاء الاصطناعي على الحساب الذي أصدر المفتاح.
* يواصل Make Agent Fast احتساب الاشتراك بالإضافة إلى رسم ثابت للمنصة عن كل إجراء يعمل بمفتاحك: رصيد واحد لكل رد في المحادثة بدلًا من الرسوم المبنية على الرموز. يغطي هذا الرسم الاسترجاع والتنسيق والاستضافة المحيطة بالاستدعاء، وهو ليس نسبة من فاتورة الرموز لديك.
* يُطبَّق الرسم على كل استدعاء للمزوّد. أما خطوات الكلام التي تموّلها المنصة (مثل التفريغ النصي عندما يكون لديك مفتاح نصوص فقط) فتُحتسب بالسعر المعتاد، وتستخدم المكالمات المباشرة دائمًا سعر المنصة.
* قد يفشل الطلب عند استنفاد حصة المزوّد حتى مع بقاء أرصدة في Make Agent Fast.

راجع كلًا من **الاستخدام والأرصدة** في Make Agent Fast ولوحة الاستخدام الخاصة بالمزوّد.

## حالات المفتاح ومعالجة الأعطال [#حالات-المفتاح-ومعالجة-الأعطال]

| الحالة    | المعنى                             | ما العمل                                                                                               |
| --------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `active`  | نجح التحقق المباشر                 | اختبر الميزة المعنية وراقب استخدام المزوّد                                                             |
| `invalid` | رفض المزوّد المفتاح المخزّن لاحقًا | تحقق من الفوترة لدى المزوّد والقيود والحصة وحالة الإلغاء، ثم احفظ مفتاحًا بديلًا (OpenRouter أو Speko) |
| `revoked` | المفتاح معطّل في Make Agent Fast   | احفظ مفتاح OpenRouter أو Speko جديدًا إذا أردت أن تواصل الميزة استخدام BYOK                            |

إذا فشل طلب لأن المزوّد رفض بيانات الاعتماد أو بسبب الحصة، فقد يضع Make Agent Fast علامة «غير صالح» على المفتاح المخزّن. ولا يؤدي إصلاح المفتاح لدى المزوّد إلى كشف السر المخزّن أو إعادة كتابته؛ ففي حالة مفتاح OpenRouter أو Speko، استخدم **اختبار الاتصال** لإعادة التحقق منه، أو احفظ المفتاح العامل مرة أخرى. أما المفتاح القديم الذي يصبح غير صالح فلا يمكن استبداله بمفتاح قديم آخر؛ انقل ذلك المزوّد إلى OpenRouter أو Speko بدلًا من ذلك.

## تدوير مفتاح المزوّد [#تدوير-مفتاح-المزوّد]

1. أنشئ مفتاحًا جديدًا لدى المزوّد دون حذف المفتاح القديم.
2. احفظ المفتاح الجديد في Make Agent Fast وتأكد من أنه أصبح نشطًا.
3. اختبر محادثة نصية أو رسائل صوتية، بحسب ما يستخدم ذلك المزوّد.
4. ألغِ المفتاح القديم في وحدة تحكم المزوّد.
5. افحص سجلات المزوّد بحثًا عن أي استخدام غير متوقع للمفتاح القديم.

إذا انكشف مفتاح في نظام إدارة الإصدارات أو في شيفرة المتصفح، فألغِه لدى المزوّد فورًا. فحذفه من Make Agent Fast وحده لا يمنع أي طرف آخر يملكه من استخدامه مباشرة لدى المزوّد.

---

# الأمان

Source: /ar/docs/account/security.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;بيانات الاعتماد&#x22;, description: &#x22;تبقى المفاتيح وأسرار OAuth ورموز الموصّلات على جهة الخادم.&#x22; },
{ icon: &#x22;embed&#x22;, title: &#x22;قوائم السماح للتضمين&#x22;, description: &#x22;تحكّم في المصادر المسموح لها بتحميل أداة الوكيل الخاصة بك.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;Webhooks&#x22;, description: &#x22;تحقّق من التوقيعات قبل الوثوق بالأحداث الواردة.&#x22; }
]"
/>

## الوصول إلى الحساب [#الوصول-إلى-الحساب]

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

تحقّق من البريد الإلكتروني للحساب عبر الرابط المرسل بعد التسجيل. يمكن لأصحاب الحسابات المحمية بكلمة مرور استخدام **نسيت كلمة المرور** في صفحة تسجيل الدخول؛ وتؤدي إعادة التعيين الناجحة إلى إلغاء الجلسات الحالية. يمكنك من **إعدادات الحساب** تغيير كلمة المرور المحلية، وربط Google صراحةً عند تفعيله، وتسجيل الخروج من جميع الأجهزة. أما الحسابات التي تعتمد على OAuth فقط فلا تملك كلمة مرور محلية لتغييرها، ولا يؤدي تسجيل الدخول العادي إلى ربط هوية جديدة بصمت.

## الأسرار [#الأسرار]

تُعدّ مفاتيح API ورموز الموصّلات وأسرار التطبيقات وأسرار webhook ومفاتيح مزوّدي الصوت من بيانات الاعتماد. خزّنها في مدير أسرار معتمد، ولا تضعها أبدًا في شيفرة العميل، وبدّلها بعد أي تعرّض لها.

## أقل قدر من الصلاحيات [#أقل-قدر-من-الصلاحيات]

اختر نطاقات API ضيقة، وتطبيقات مخصصة للمنصات الخارجية، ومصادر تضمين دقيقة، ومفاتيح منفصلة للأنظمة المختلفة. أزل بيانات الاعتماد والتكاملات غير المستخدمة.

## المحتوى والخصوصية [#المحتوى-والخصوصية]

ارفع فقط البيانات المسموح للوكيل باستخدامها. اختبر حالات الرفض ومسارات التصعيد، وطبّق قواعد الاحتفاظ على صادرات المحادثات والـ Leads.

## الإبلاغ [#الإبلاغ]

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

---

# استكشاف الأخطاء وإصلاحها

Source: /ar/docs/account/troubleshooting.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;النشر&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;التضمين&#x22;, icon: &#x22;embed&#x22; }, { label: &#x22;الموصّلات&#x22;, icon: &#x22;connectors&#x22; }]" />

## ابدأ بحالة قابلة لإعادة الإنتاج [#ابدأ-بحالة-قابلة-لإعادة-الإنتاج]

قبل تغيير أي إعدادات، سجّل ما يلي:

* مساحة العمل/الموقع، والمسار العام أو نقطة نهاية API، والوقت الدقيق مع المنطقة الزمنية.
* النتيجة المتوقعة والنتيجة الفعلية.
* المتصفح/الجهاز أو قناة المزوّد الخارجي.
* ما إذا كان العطل يؤثر في معاينة المالك، أو صفحة العرض التجريبي المستضافة المتبقية، أو التضمين، أو الموصّل، و/أو API.
* نص الحالة/الخطأ الآمن، أو قيمة `x-request-id` في الاستجابة، أو آخر خطأ للموصّل، أو معرّف حدث التسليم لدى المزوّد.
* آخر وقت كان يعمل فيه كل شيء بشكل سليم، وأصغر تغيير أُجري مؤخرًا.

لا تُدرج بيانات اعتماد API أو المزوّد أو الموصّل بنص صريح، ولا أسرار webhook، ولا بيانات العملاء الخاصة، ولا ترويسات التفويض كاملة، ولا محتوى المحادثات غير الضروري.

## تغييرات الموقع لا تظهر [#تغييرات-الموقع-لا-تظهر]

1. تأكد من أن عنوان URL في لوحة التحكم يخص الموقع ومساحة العمل المقصودين.
2. تأكد من أن إجراء الحفظ أبلغ عن نجاحه.
3. تُطبَّق التعليمات والمعرفة المفهرسة على المحادثات الجديدة دون إعادة نشر. إذا كانت أداة الدردشة نفسها مخفية، فأعد تفعيلها من قائمة **اجعله متاحًا** في صفحة الـ agent ← **أداة الموقع** (أو من بطاقة **على موقعك** في تبويب **نظرة عامة**).
4. بالنسبة لإعدادات **العرض** (وشارة العلامة التجارية)، تُحفظ التغييرات تلقائيًا وتحدّث التضمين المباشر فورًا — لذا تجاوز إعادة النشر وافتح نافذة خاصة.
5. افتح تضمينًا فعليًا (أو slug مستضافًا متبقيًا إن كان لديك واحد) في نافذة خاصة.
6. إذا كانت المعاينة الاجتماعية فقط هي القديمة، فاستخدم أداة ذاكرة التخزين المؤقت/التصحيح الخاصة بتلك المنصة.

إلغاء النشر والتحرير أمران مختلفان. فقد يستمر موصّل المراسلة المتصل في الرد حتى لو كان التضمين متوقفًا.

## إجابة الـ agent ضعيفة أو خاطئة [#إجابة-الـ-agent-ضعيفة-أو-خاطئة]

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

عندما لا يحتوي المصدر على إجابة، حسّن سلوك الإجابة البديلة/التصعيد بدلًا من توجيه الـ agent إلى التخمين. استخدم [مصادر المعرفة](/ar/docs/build/knowledge) لإنشاء مجموعة قبول تشمل الأسئلة المباشرة وإعادة الصياغة والحدود.

## أداة التشغيل الخاصة بالتضمين مفقودة أو محظورة [#أداة-التشغيل-الخاصة-بالتضمين-مفقودة-أو-محظورة]

تأكد من أن الموقع منشور، وأن التضمين مفعّل، وأن السكربت يحمل slug الموقع بدقة، وأن أصل الصفحة الأم النهائي في المتصفح — بما في ذلك المخطط واسم المضيف والمنفذ — مدرج في قائمة السماح. في DevTools، افحص طلب `embed.js`، وأخطاء CSP، وحالة مدير الموافقة، وطلب iframe، ووجود جذر `data-maf-embed` واحد.

إذا كان النص يعمل لكن الميكروفون لا يعمل، فتحقق من HTTPS، وإذن المتصفح، وإذن allow الخاص بـ iframe، وسياسة Permissions Policy للمضيف. اتبع [نظرة عامة على التضمين](/ar/docs/embed/overview) و[الأمان وCSP](/ar/docs/embed/security) كاملتين.

## الصوت لا يعمل [#الصوت-لا-يعمل]

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

افحص مفاتيح التفريغ النصي وتحويل النص إلى كلام (TTS) والمزوّد الفوري كلًّا على حدة؛ ثم افحص أهلية الخطة ورصيد الـ credits وحصة الدقائق المباشرة وإذن المتصفح واللغات المهيأة. اختبر تسجيلًا قصيرًا وواضحًا قبل التحقيق في ملف طويل أو مليء بالضوضاء.

## الموصّل لا يتلقى أي رسائل [#الموصّل-لا-يتلقى-أي-رسائل]

استخدم دليل القناة وقارن بين الطرفين. تأكد من أن الموصّل مفعّل، وأن بيانات الاعتماد ما تزال صالحة، وأن عنوان webhook/التفاعل/المهارة لدى المزوّد هو العنوان الحالي، وأن الحدث/الصفحة/الرقم/الكتلة المطلوبة مشترَك بها، وأن وضع التطبيق يشمل مستخدم الاختبار، وأن التسليم عبر HTTPS العام ينجح.

نجاح التحقق من webhook لا يثبت الاشتراك في أحداث وقت التشغيل ولا أذونات الإرسال. قارن سجلات التسليم لدى المزوّد مع **آخر رسالة** والخطأ المحفوظ للموصّل. اختبر النص قبل الصوت.

## النطاقات المخصصة غير متاحة [#النطاقات-المخصصة-غير-متاحة]

نحن لا نبيع نطاقات العملاء ولا نربطها. ضع الـ agent على الموقع الذي تملكه بالفعل عبر [التضمين](/ar/docs/embed/overview). أحداث الإضافة الخاصة بالنطاقات المتبقية في Polar تُتجاهل أو تُلغى ولا تمنح credits أبدًا.

## فشل طلب API [#فشل-طلب-api]

سجّل الأسلوب (method)، والمسار ذا الإصدار، والحالة، ورمز الخطأ الثابت، وقيمة `x-request-id` في الاستجابة، وترويسات حدّ المعدل ذات الصلة. ثم صنّف الحالة:

| الحالة | الإجراء الأرجح                                                                               |
| ------ | -------------------------------------------------------------------------------------------- |
| `400`  | صحّح بنية JSON/النموذج أو تفاصيل التحقق؛ لا تُعد المحاولة دون تغيير                          |
| `401`  | استخدم بيانات اعتماد MAF صالحة وغير منتهية وغير ملغاة؛ ولا تستخدم مفتاح مزوّد أبدًا          |
| `403`  | أضف النطاق (scope) المطلوب أو استعد صلاحية الوصول إلى الخطة/المورد                           |
| `404`  | تأكد من أن المعرّف ينتمي إلى مساحة العمل المصادَق عليها وأن المسار صحيح                      |
| `409`  | عالج تعارض الحالة أو أعد إرسال المفتاح والحمولة نفسيهما لضمان idempotency                    |
| `415`  | أرسل نوع المحتوى الموثّق                                                                     |
| `429`  | التزم بترويسات `retry-after`/إعادة الضبط مع إضافة jitter؛ ولا تُكرر المحاولة في حلقة متواصلة |
| `500`  | أعد محاولة الطلب الآمن/المتماثل (idempotent) واحتفظ بمعرّف الطلب والوقت                      |

استخدم [بيانات الاعتماد والرموز](/ar/docs/api/credentials) و[النطاقات والأخطاء](/ar/docs/api/scopes-errors) و[حدود المعدل](/ar/docs/api/rate-limits). لا تحلّ خطأ API أبدًا بنقل بيانات اعتماد الخادم إلى كود المتصفح.

## الفوترة أو الاستخدام يبدو غير صحيح [#الفوترة-أو-الاستخدام-يبدو-غير-صحيح]

ميّز بين الوصول إلى المنصة، والـ credits الشهرية، والـ credits المشتراة، وعدد المواقع، والدقائق المباشرة، ومعدل API، وقنوات المراسلة (Operate+)، وBYOK/الفريق (Scale). الشحن الإضافي يغيّر الـ credits فقط. أما رسوم مزوّد BYOK فمنفصلة عن فوترة Make Agent Fast.

في حال الاستخدام غير المتوقع، احتوِ المصدر المرجّح قبل التحقيق: عطّل موصّلًا، أو ألغِ مفتاحًا، أو أزل أصل تضمين غير مقصود، أو أوقف حلقة إعادة محاولة API. احتفظ بالنطاق الزمني ومعرّفات الطلبات/المزوّد دون كشف أي أسرار.

## اجمع تفاصيل دعم آمنة [#اجمع-تفاصيل-دعم-آمنة]

إذا بقيت المشكلة قائمة، فاستخدم عنصر التعليقات في الدليل الأكثر صلة أو تواصل مع الدعم من لوحة التحكم، مع تضمين ما يلي:

* معرّف الموقع/مساحة العمل والميزة المتأثرة.
* الطابع الزمني الدقيق/المنطقة الزمنية وخطوات إعادة الإنتاج.
* النتيجة المتوقعة مقابل الفعلية.
* عنوان URL عام غير سري عند الاقتضاء.
* حالة HTTP، ورمز الخطأ الثابت، وقيمة `x-request-id`، أو معرّف حدث المزوّد.
* لقطة شاشة منقّحة أو حمولة minimal بعد إزالة الأسرار والبيانات الشخصية.

اذكر ما فحصته بالفعل. فهذا يمنع تكرار نصائح الإعداد ويوضّح حدود العطل.

---

# المصادقة

Source: /ar/docs/api/authentication.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;مفاتيح API&#x22;, description: &#x22;بيانات اعتماد من نوع Bearer محدّدة النطاق، لحساب واحد وخادم تتحكم به.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;OAuth&#x22;, description: &#x22;تفويض خاضع للمراجعة للتطبيقات التي تتصل بعدة حسابات عملاء.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;أقل قدر من الصلاحيات&#x22;, description: &#x22;تحدد كل عملية نطاق القراءة أو الكتابة الذي تحتاج إليه بدقة.&#x22; }
]"
/>

استخدم مفتاح API لخادمك الخلفي أو لأتمتة أعمالك. واستخدم OAuth عندما يطلب تطبيقك من مستخدمين آخرين في Make Agent Fast منحه حق الوصول. يستدعي النوعان من بيانات الاعتماد موارد `/api/v1` نفسها، ويخضعان للنطاقات نفسها، وصلاحيات الخطة، وعزل المستأجرين، وحدود المعدّل.

## مفاتيح API [#مفاتيح-api]

يتطلب إنشاء مفتاح API عام واستخدامه وجود خطة مدفوعة نشطة.

1. افتح **لوحة التحكم ← الإعدادات ← المطوّرون**.
2. أدخل اسمًا يحدد الخدمة والبيئة، مثل `Production lead export`.
3. حدّد أقل النطاقات التي تحتاج إليها الخدمة.
4. اختر مدة الصلاحية: 30 يومًا، أو 90 يومًا، أو سنة واحدة، أو بلا انتهاء.
5. أنشئ المفتاح، وانسخ القيمة `maf_live_...` فورًا.

يخزّن Make Agent Fast تجزئة SHA-256 بدلًا من نص عادي يمكن استرجاعه. وتعرض لوحة التحكم لاحقًا بادئة آمنة للمفتاح، والنطاقات، وتاريخ الانتهاء، ووقت آخر استخدام، وحالة الإلغاء.

```http
Authorization: Bearer maf_live_...
```

أرسل الترويسة من شيفرة الخادم:

```bash
curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

يؤدي غياب بيانات الاعتماد إلى الاستجابة `401 authentication_required`. أما المفاتيح غير الصالحة أو المنتهية أو الملغاة فتُرجع `401 invalid_api_key`. وإذا لم تعد الخطة المدفوعة نشطة في حساب المفتاح، فتُرجع الاستجابة `403 subscription_required`.

### تدوير المفتاح أو إلغاؤه [#تدوير-المفتاح-أو-إلغاؤه]

أنشئ مفتاحًا بديلًا قبل إلغاء المفتاح القديم. انشر المفتاح البديل، وأرسل طلبًا فعليًا، وتحقق من `x-request-id` الخاص به، ثم انقر **إلغاء** على المفتاح القديم. الإلغاء فوري ولا يمكن التراجع عنه.

في إعدادات **المطوّرون**، يتيح لك **تعديل** تغيير اسم المفتاح النشط ونطاقاته؛ ويسري التغيير فورًا على المفتاح نفسه. أما مدة الصلاحية والرمز فلا يمكن تغييرهما، لذا أنشئ مفتاحًا بديلًا للحصول على مدة صلاحية جديدة أو رمز مُدوَّر.

## تطبيقات OAuth [#تطبيقات-oauth]

يُستخدم OAuth للبرمجيات التي تتصل بحسابات يملكها مستخدمون آخرون في Make Agent Fast. ويعتمد على Authorization Code مع PKCE (`S256`)، ولا يُصدر سرّ عميل ولا يتطلبه. معرّف العميل (client ID) عام؛ أما أكواد التفويض، ورموز الوصول، ورموز التحديث، وPKCE verifier فهي بيانات حساسة.

### 1. سجّل التطبيق [#1-سجّل-التطبيق]

افتح **لوحة التحكم ← الإعدادات ← المطوّرون ← تطبيقات OAuth**. ثم أضف:

* اسم التطبيق بطول من 2 إلى 100 حرف.
* ما بين 1 و10 عناوين URL دقيقة لإعادة التوجيه.
* الحد الأقصى للنطاقات التي يجوز لتطبيقك طلبها.

يجب أن تستخدم عناوين URL لإعادة التوجيه في الإنتاج HTTPS، ولا يجوز أن تتضمن بيانات اعتماد أو أجزاء (fragments). ويجب أن يطابق URI الكامل إحدى القيم المسجّلة أثناء التفويض وتبادل الرمز. تكون حالة التطبيقات المقدَّمة حديثًا `pending`، ولا يعمل التفويض إلا بعد مراجعة التطبيق ووسمه `approved`.

يراجع مالك المنصة معرّفات العملاء المعلّقة عبر سير العمل المدقَّق `oauth:review`. احتفظ بمعرّف العميل الظاهر بعد الإرسال؛ إذ تظهر حالته في صفحة المطوّرين، وتتضمن التطبيقات المرفوضة قرار المراجعة قبل أن يمكن إعادة إرسالها.

### 2. أنشئ قيم PKCE [#2-أنشئ-قيم-pkce]

أنشئ verifier جديدًا لكل محاولة تفويض، واحتفظ به في الجلسة المحمية قصيرة الأمد نفسها التي تحتفظ فيها بالقيمة `state`.

```ts
import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
```

يجب أن يتكون verifier من 43 إلى 128 حرفًا من أحرف PKCE الآمنة في عناوين URL. ولا يُقبل سوى `code_challenge_method=S256`.

### 3. أعد توجيه المستخدم للموافقة [#3-أعد-توجيه-المستخدم-للموافقة]

```text
https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
```

يسجّل المستخدم الدخول، ويراجع النطاقات المطلوبة، ثم يسمح بالوصول أو يرفضه. عند النجاح، يعيد Make Agent Fast التوجيه إلى URI المسجّل نفسه تمامًا مع `code` وقيمة `state` الأصلية. وعند الرفض، يرسل `error=access_denied` مع قيمة `state` الأصلية إن كانت قد أُرسلت.

ارفض استدعاء الرجوع (callback) إذا لم تطابق قيمة `state` تمامًا القيمة المخزّنة لجلسة المتصفح تلك.

### 4. بادل كود التفويض [#4-بادل-كود-التفويض]

ينتهي كود التفويض بعد 10 دقائق، ولا يمكن استخدامه إلا مرة واحدة.

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"
```

```json
{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}
```

يظل رمز الوصول صالحًا لمدة ساعة واحدة. ويظل رمز التحديث صالحًا حتى 90 يومًا ما لم يُدوَّر أو يُلغَ قبل ذلك.

### 5. دوّر رمز التحديث [#5-دوّر-رمز-التحديث]

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

```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
```

يؤدي إعادة استخدام كود تفويض أو رمز تحديث سبق تدويره إلى الاستجابة `invalid_grant`. وتُرجع نقطة نهاية رمز OAuth استجابات بصيغة OAuth هي `{ "error", "error_description" }` بدلًا من غلاف الأخطاء الخاص بواجهة API العامة، وتسمح بـ 30 طلب رمز لكل عنوان IP للمتصل في الدقيقة.

## لا تصادق أبدًا على طلبات الإدارة في شيفرة المتصفح [#لا-تصادق-أبدًا-على-طلبات-الإدارة-في-شيفرة-المتصفح]

لا تضع مفتاح API سريًا أو رمز وصول أو رمز تحديث في مكوّنات React على جهة العميل، أو في JavaScript ثابت، أو في الويب على الجوال، أو في Webflow أو Framer أو Wix أو Shopify Liquid. استخدم خادمك الخلفي المصادَق عليه. يعتمد تضمين الموقع العام على معرّف موقع (site slug) غير سرّي وعلى قائمة سماح للأصول (origins)، لا على بيانات اعتماد واجهة الإدارة البرمجية.

راجع [بيانات الاعتماد والرموز](/ar/docs/api/credentials) و[النطاقات والأخطاء](/ar/docs/api/scopes-errors) و[البدء السريع مع API](/ar/docs/api/quickstart).

---

# بيانات الاعتماد والرموز المميزة

Source: /ar/docs/api/credentials.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;shield&#x22;, title: &#x22;بيانات اعتماد الخادم&#x22;, description: &#x22;تمنح مفاتيح API ورموز OAuth صلاحية الوصول إلى واجهة API العامة.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;بيانات اعتماد القنوات&#x22;, description: &#x22;تربط رموز البوتات وأسرار التطبيقات مزوّدي المراسلة الخارجيين.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;مفاتيح المزوّدين&#x22;, description: &#x22;تتيح بيانات اعتماد BYOK الدفع لمزوّدي الذكاء الاصطناعي من حسابك الخاص لدى المزوّد.&#x22; }
]"
/>

يستخدم Make Agent Fast عدة أنواع من بيانات الاعتماد، ولا يمكن استبدال بعضها ببعض. قبل نسخ أي قيمة، حدّد الجهة التي أصدرتها، والنظام الذي سيستقبلها، وهل يمكن كشفها بأمان في المتصفح.

## خريطة بيانات الاعتماد [#خريطة-بيانات-الاعتماد]

| بيانات الاعتماد                                         | مكان الإنشاء                                 | الجهة المستخدِمة                  | سرّية؟ | الصيغة أو القيمة المعتادة                 |
| ------------------------------------------------------- | -------------------------------------------- | --------------------------------- | ------ | ----------------------------------------- |
| المعرّف المختصر (slug) للموقع المنشور                   | لوحة تحكم الموقع                             | أداة تحميل التضمين في الموقع      | لا     | `my-agent`                                |
| مفتاح API الخاص بـ Make Agent Fast                      | **الإعدادات ← المطوّرون**                    | الخادم الخلفي أو الأتمتة لديك     | نعم    | `maf_live_...`                            |
| معرّف عميل OAuth                                        | **الإعدادات ← المطوّرون**                    | التطبيق متعدد الحسابات            | لا     | `maf_app_...`                             |
| رمز وصول OAuth                                          | نقطة نهاية رمز OAuth                         | الخادم الخلفي لتطبيقك             | نعم    | رمز Bearer، مدة صلاحيته ساعة واحدة        |
| رمز تحديث OAuth                                         | نقطة نهاية رمز OAuth                         | مخزن الرموز الآمن لديك            | نعم    | `maf_refresh_...`، يُبدَّل عند كل استخدام |
| مفتاح API لمزوّد الذكاء الاصطناعي (اختياري، باقة Scale) | OpenRouter (للنص) أو Speko (للصوت)           | الخادم الخلفي لـ Make Agent Fast  | نعم    | `sk-or-...` أو `sk_speko_...`             |
| رمز الموصّل أو سر التطبيق                               | Telegram أو Meta أو Discord أو Kakao         | خدمة الموصّلات في Make Agent Fast | نعم    | يختلف حسب المزوّد                         |
| سر توقيع الـ webhook                                    | إنشاء نقطة نهاية webhook في واجهة API العامة | مستقبِل الـ webhook لديك          | نعم    | `whsec_...`                               |

<Callout title="التضمين في الموقع لا يستخدم مفتاح API">
  تحتاج أداة تحميل التضمين إلى المعرّف المختصر العام للموقع ونطاق موقع إلكتروني مسموح به فقط. لا تضف أبدًا مفتاح API الخاص بـ Make Agent Fast أو مفتاح مزوّد أو رمز موصّل أو سر webhook إلى وسم script.
</Callout>

## اختيار طريقة التفويض المناسبة [#اختيار-طريقة-التفويض-المناسبة]

استخدم **مفتاح API الخاص بـ Make Agent Fast** لخادم تتحكم فيه وحساب واحد على Make Agent Fast. اختر فقط النطاقات (scopes) التي يحتاجها ذلك الخادم.

استخدم **OAuth Authorization Code مع PKCE** عندما يربط منتجك حسابات تخص مستخدمين آخرين في Make Agent Fast. تخضع تطبيقات OAuth للمراجعة قبل أن ينجح التفويض في بيئة الإنتاج.

استخدم **مفتاح مزوّد الذكاء الاصطناعي** فقط عندما تريد أن يستدعي Make Agent Fast ذلك المزوّد عبر حسابك لديه. لا يمنح مفتاح المزوّد صلاحية الوصول إلى واجهة API العامة لـ Make Agent Fast.

استخدم **بيانات اعتماد الموصّل** فقط في نموذج الموصّل المطابق أو في طلب API الخاص بالموصّل. لا يمكن لرمز بوت Telegram تفويض Discord أو Meta أو طلبات API الخاصة بـ Make Agent Fast.

## تخزين الأسرار بأمان [#تخزين-الأسرار-بأمان]

في بيئة التطوير المحلية، ضع الأسرار في ملف بيئة مستثنى من التتبع أو في بيئة الطرفية لديك:

```bash
export MAF_API_KEY="maf_live_..."
```

عند النشر، استخدم مدير الأسرار المشفّر لدى مزوّد الاستضافة. لا تضع الأسرار في:

* عمليات Git commit، أو وصف المشكلات (issues)، أو لقطات الشاشة، أو خصائص التحليلات، أو رسائل الدعم.
* المتغيرات `NEXT_PUBLIC_*` أو `VITE_*` أو أي متغيرات أخرى تُضمَّن في JavaScript الخاص بالمتصفح.
* Webflow أو Framer أو Wix أو Shopify Liquid أو HTML في WordPress أو حزمة تطبيق ويب للجوال.
* سلاسل الاستعلام (query strings)، إذ يشيع الاحتفاظ بعناوين URL في سجل المتصفح والوسطاء (proxies) والسجلات.

أجرِ استدعاءات API عبر الخادم الخلفي الموثَّق لديك. يجب أن يستدعي المتصفح خادمك الخلفي، وأن يضيف الخادم الخلفي السر.

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites", {
  headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
```

## قواعد الأسرار التي تُعرض مرة واحدة [#قواعد-الأسرار-التي-تُعرض-مرة-واحدة]

يجب نسخ مفاتيح API وأسرار توقيع webhook ورموز تحديث OAuth المُصدَرة حديثًا عند عرضها، إذ لا يمكن استرجاع القيمة الكاملة لاحقًا. إذا فُقدت، أنشئ بديلًا بدلًا من أن تطلب من الدعم كشفها.

تُشفَّر بيانات اعتماد مزوّدي الذكاء الاصطناعي والموصّلات قبل تخزينها ولا تُعاد عبر واجهات API الخاصة بالقوائم. قد تعرض لوحة التحكم تسمية أو بادئة أو آخر أربعة أحرف أو حالة التحقق أو وقت آخر استخدام، حتى تتمكن من تمييز بيانات الاعتماد دون كشفها.

## قائمة التحقق للتبديل [#قائمة-التحقق-للتبديل]

1. أنشئ البديل بالنطاقات أو أذونات المزوّد الدنيا نفسها.
2. حدّث نشرًا واحدًا أو مستقبِلًا واحدًا في كل مرة.
3. تحقق من نجاح طلب حقيقي وسجّل قيمة `x-request-id` الخاصة به.
4. اسحب بيانات الاعتماد القديمة.
5. تأكد من أن الطلبات القديمة تفشل بالخطأ `401 invalid_api_key` أو ما يعادله لدى المزوّد.

في OAuth، احفظ رمز التحديث الجديد الذي تعيده كل استجابة تحديث قبل التخلص من الرمز السابق. وعند تبديل سر webhook، شغّل نقطتي النهاية القديمة والجديدة بالتوازي إلى أن يستخدم كل منتِج ومستقبِل البديلَ.

## إذا انكشف سر [#إذا-انكشف-سر]

اسحبه أو بدّله فورًا. لا يكفي حذفه من أحدث Git commit، فقد يبقى في السجل التاريخي أو الذاكرة المؤقتة أو السجلات أو النسخ المتفرعة (forks). راجع النشاط في Make Agent Fast وعند المزوّد الذي أصدره، ثم استبدل أي بيانات اعتماد تشترك في موقع التخزين أو بيئة النشر نفسها.

تابع مع [المصادقة](/ar/docs/api/authentication) أو [النطاقات والأخطاء](/ar/docs/api/scopes-errors) أو [مفاتيح مزوّدي الذكاء الاصطناعي](/ar/docs/account/provider-keys).

---

# نظرة عامة على API

Source: /ar/docs/api/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/api/authentication&#x22;, label: &#x22;المصادقة&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/ar/docs/api/quickstart&#x22;, label: &#x22;البدء السريع&#x22;, icon: &#x22;bolt&#x22; },
{ href: &#x22;/ar/docs/api/reference&#x22;, label: &#x22;المرجع&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/api/webhooks&#x22;, label: &#x22;Webhooks&#x22;, icon: &#x22;link&#x22; },
{ href: &#x22;/ar/docs/api/sdks&#x22;, label: &#x22;SDKs&#x22;, icon: &#x22;code&#x22; }
]"
/>

تستخدم واجهة API العامة تنسيق JSON موجَّهًا نحو الموارد عبر HTTPS ضمن المسار `/api/v1`. وهي متاحة في الباقات المدفوعة، وتعتمد على نفس صلاحيات الموقع والرصيد والميزات المعتمدة في لوحة التحكم.

## ما الذي يمكنك أتمتته [#ما-الذي-يمكنك-أتمتته]

* المواقع وحالة النشر
* إعدادات الـ agent والأسئلة الشائعة والمنتجات والمعرفة
* المحادثات (بما في ذلك ردود المالك والإيقاف المؤقت والاستئناف) والـ leads والتحليلات والإشعارات والرسائل الجماعية
* إنشاء الـ leads وتسجيل موافقتهم، ومسارات الفرص، ونتائج CRM، واستعادة المزامنة
* الـ connectors والتسييل والتذاكر والفريق والاستخدام ومعلومات الحساب
* اشتراكات Webhooks الموقَّعة للأحداث المدعومة

تستخدم الإجراءات الحساسة نقاط نهاية صريحة مخصصة للإجراءات بدلًا من التعديل غير المقيّد على قاعدة البيانات. تُقبل أسرار الـ connector عند الكتابة، لكنها لا تُعاد أبدًا.

هذه **واجهة API للإدارة والمزامنة**. يمكنها إنشاء الـ leads وتحديثها،
وقبولها في مسار الفرص، واستيراد نتائج CRM (الفوز/الخسارة) مع نسبتها إلى مصدرها،
وإعادة محاولة عمليات استيراد النتائج الفاشلة، والرد على الزائر بصفة النشاط التجاري،
مع إيقاف الـ agent مؤقتًا في تلك المحادثة واستئنافه. أما إرسال الرسائل بصفة الزائر
فيظل عملية خاصة بالأداة (widget)، وتبقى التحليلات والاستخدام للقراءة فقط. تمت
إزالة النطاقات المخصصة، وتعيد مسارات `/domains` الرمز `409`.

## ابدأ بأمان [#ابدأ-بأمان]

أنشئ مفتاحًا محدود النطاق من لوحة التحكم، ثم استدعِ نقطة نهاية الحساب الحالي، وابنِ تطبيقك أولًا على موقع تجريبي قبل أن تتعامل مع محتوى الإنتاج.

```bash
curl https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer maf_live_YOUR_KEY"
```

راجع [المصادقة](/ar/docs/api/authentication) و[البدء السريع مع API](/ar/docs/api/quickstart) و[مرجع API](/ar/docs/api/reference).

---

# البدء السريع مع API

Source: /ar/docs/api/quickstart.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;10 دقائق&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;للخادم فقط&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;REST&#x22;, icon: &#x22;code&#x22; }]" />

يتحقق هذا الدليل السريع من قدرة الواجهة الخلفية على المصادقة وقراءة بيانات حسابك. تحتاج إلى خطة مدفوعة نشطة، وطرفية تدعم `curl`، وصلاحية الوصول إلى **لوحة التحكم ← الإعدادات ← المطوّرون**.

تتيح الإصدار v1 الحالي من API إدارة الموارد ومزامنتها. وهي ليست وسيلة نقل للمحادثات المخصصة: لا يمكنك إرسال رسائل بصفتك زائرًا. يمكن إنشاء العملاء المحتملين (Leads) وتحديثهم وقبولهم (`leads:write`)، ويمكن للمالك الرد على محادثة أو إيقافها مؤقتًا أو استئنافها (`conversations:write`).

## 1. إنشاء مفتاح بأقل الصلاحيات [#1-إنشاء-مفتاح-بأقل-الصلاحيات]

أنشئ مفتاحًا باسم `Local API quickstart`، وحدّد `account:read` و`sites:read`، واختر مدة صلاحية قصيرة. انسخ المفتاح بصيغته الأصلية فورًا؛ فلن يُعرض مرة أخرى.

لا تستخدم مفتاح مزوّد ذكاء اصطناعي مثل مفتاح OpenRouter أو Speko. تتطلب واجهة API العامة مفتاح Make Agent Fast يبدأ بالبادئة `maf_live_`.

## 2. تخزينه لهذه الطرفية [#2-تخزينه-لهذه-الطرفية]

```bash
export MAF_API_KEY="maf_live_..."
```

تأكد من وجود المتغير دون طباعة السر:

```bash
test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"
```

لا تضف المفتاح إلى `.env` أو أمثلة سجل الأوامر في الطرفية أو بيانات الاختبار الثابتة أو حزمة المتصفح. وفي الشيفرة المنشورة، استخدم مدير الأسرار الخاص بالمضيف.

## 3. فحص الحساب [#3-فحص-الحساب]

```bash
curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

الحالة المتوقعة: `200 OK`. يحتوي نص الاستجابة على `data.id` ومعلومات الخطة والاستحقاقات وملخص المحفظة. كما تحتوي الاستجابة على `x-request-id`؛ احتفظ بهذه القيمة عند الإبلاغ عن طلب فاشل.

```json
{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}
```

قد تُضاف حقول جديدة دون تغيير المسار `/v1`. تجاهل الحقول غير المعروفة بدلًا من رفض الاستجابة.

## 4. عرض المواقع [#4-عرض-المواقع]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"
```

تستخدم استجابات المجموعات هذا الغلاف:

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

إذا كانت قيمة `has_more` تساوي true، فأرسل قيمة `next_cursor` كما هي تمامًا كمعامل الاستعلام `cursor` في الطلب التالي. لا تفك ترميز المؤشرات ولا تنشئها بنفسك.

## 5. التعامل مع خطأ منظَّم [#5-التعامل-مع-خطأ-منظَّم]

أزل ترويسة Authorization مؤقتًا وكرر الطلب إلى `/me`. يجب أن تكون الاستجابة `401` مع رمز ثابت:

```json
{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}
```

يجب أن تعتمد الشيفرة الإنتاجية في تفرعاتها على `error.code` لا على مقارنة `message`. سجّل العملية ورمز حالة HTTP ومعرّف الطلب دون تسجيل المفتاح.

## 6. تنفيذ أول عملية كتابة بأمان [#6-تنفيذ-أول-عملية-كتابة-بأمان]

أنشئ مفتاحًا منفصلًا يتضمن أيضًا `sites:write` و`agents:write` و`knowledge:write`؛ ولا توسّع صلاحيات مفتاح القراءة الخاص بالبدء السريع. اتبع [وصفات API](/ar/docs/api/recipes) لإنشاء موقع، وإضافة معرفة موثوقة، ونشره باستخدام مفاتيح idempotency صريحة.

## أخطاء شائعة في الطلب الأول [#أخطاء-شائعة-في-الطلب-الأول]

| النتيجة                       | السبب                                                                  | الحل                                                      |
| ----------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| `401 authentication_required` | الترويسة مفقودة أو ليست بصيغة `Bearer TOKEN`                           | أضف ترويسة Authorization الصحيحة من شيفرة الخادم          |
| `401 invalid_api_key`         | خطأ إملائي، أو مفتاح منتهي الصلاحية أو ملغى، أو نوع بيانات اعتماد خاطئ | أنشئ مفتاح Make Agent Fast API جديدًا وانسخه              |
| `403 subscription_required`   | لا توجد خطة مدفوعة نشطة                                                | جدّد اشتراك الحساب                                        |
| `403 insufficient_scope`      | المفتاح لا يتضمن صلاحية العملية المطلوبة                               | أنشئ مفتاحًا بديلًا يتضمن الحد الأدنى من الصلاحية الناقصة |
| `403 account_paused`          | تم إيقاف الوصول إلى API مؤقتًا لهذا الحساب                             | استأنف الوصول إلى API أو تواصل مع مالك الحساب             |
| `429 rate_limit_exceeded`     | استُنفدت حصة المفتاح لمدة دقيقة واحدة                                  | انتظر حسب `Retry-After` وقلّل عدد الطلبات المتزامنة       |

تابع مع [الصلاحيات والأخطاء](/ar/docs/api/scopes-errors) و[مرجع API](/ar/docs/api/reference) و[حدود المعدّل](/ar/docs/api/rate-limits).

---

# حدود المعدّل

Source: /ar/docs/api/rate-limits.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;لكل مفتاح&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;دقيقة واحدة&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;Retry-After&#x22;, icon: &#x22;code&#x22; }]" />

تطبّق واجهة API العامة حصة طلبات متجدّدة مدتها دقيقة واحدة على كل مفتاح API أو رمز وصول OAuth. إنشاء مفاتيح إضافية للالتفاف على أحد الحدود غير مدعوم، وقد يؤدي إلى فرض قيود على بيانات الاعتماد أو الحساب.

## حدود الخطط [#حدود-الخطط]

| الخطة النشطة | الطلبات لكل مفتاح في الدقيقة |
| ------------ | ---------------------------: |
| Launch       |                          120 |
| Operate      |                          600 |
| Scale        |                        1,800 |

تتلقى بيانات الاعتماد التي لا يملك حسابها خطة مدفوعة نشطة الاستجابة `403 subscription_required` قبل منحها أي سعة ضمن حدود المعدّل. يمكن لـ Make Agent Fast تطبيق حدود أدنى خاصة ببعض نقاط النهاية للعمليات المكلفة بشكل غير معتاد، وعند حدوث ذلك سيوضّح مرجع نقطة النهاية هذه الحدود صراحةً.

## استجابة تجاوز حد المعدّل [#استجابة-تجاوز-حد-المعدّل]

عند استنفاد الحصة، تعيد API الاستجابة `429 rate_limit_exceeded` مع:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json
```

تمثّل `Retry-After` الحد الأدنى لعدد الثواني التي يجب انتظارها. كما تتضمن كل استجابة موثّقة
الترويسات `X-RateLimit-Limit` و`X-RateLimit-Remaining` و
`X-RateLimit-Reset` (طابع زمني بنظام Unix)، بحيث تستطيع التطبيقات تنظيم معدّل طلباتها قبل الوصول إلى
`429`.

## تنفيذ إعادة المحاولة [#تنفيذ-إعادة-المحاولة]

استخدم التراجع الأسّي مع تباين عشوائي (jitter)، والتزم بقيمة `Retry-After` إذا كانت أكبر، وحدّد سقفًا لإجمالي عدد المحاولات.

```ts
async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}
```

في طلبات `POST` و`PATCH` و`DELETE`، احتفظ بالقيمة الصالحة نفسها للترويسة `Idempotency-Key` عبر كل عمليات إعادة المحاولة الناتجة عن أخطاء الشبكة أو الخادم. قد يؤدي مفتاح idempotency جديد إلى تكرار أثر جانبي اكتمل بالفعل.

## تقليل حجم الطلبات [#تقليل-حجم-الطلبات]

* خزّن مؤقتًا عمليات قراءة الحساب والموقع والإعدادات التي لا تتطلب بيانات محدّثة في الوقت الفعلي.
* اطلب ما يصل إلى `100` سجل في الصفحة بدلًا من طلب صفحات صغيرة جدًا بشكل متكرر.
* عالج أحداث webhook بدلًا من الاستعلام الدوري عن المحادثات أو العملاء المحتملين (Leads) أو رسائل البث.
* حدّد عدد العمليات المتزامنة للعمال (workers) لكل مفتاح API؛ فالدفعات المفاجئة من عدد كبير من استدعاءات serverless تتشارك الحصة نفسها.
* استخدم مفاتيح منفصلة للخدمات المنفصلة لأغراض العزل وسهولة التدقيق، وليس لمضاعفة سعة عبء عمل واحد.

## جدول ما يُعاد وما لا يُعاد [#جدول-ما-يُعاد-وما-لا-يُعاد]

| الاستجابة                         | هل تُعاد المحاولة؟ | الشرط                                                                        |
| --------------------------------- | ------------------ | ---------------------------------------------------------------------------- |
| `429`                             | نعم                | انتظر مدة `Retry-After`، وأضف jitter، وحدّد سقفًا للمحاولات                  |
| `500`                             | أحيانًا            | عمليات القراءة الآمنة أو عمليات التعديل المحمية بمفتاح idempotency نفسه      |
| تعارض معالجة `409`                | نعم                | انتظر وفق الترويسة `Retry-After: 2` واحتفظ بمفتاح idempotency نفسه           |
| أي `409` آخر                      | ليس فورًا          | اقرأ الحالة الحالية للمورد وعالج التعارض                                     |
| `503` مع `outcome_unknown`        | لا                 | ربما اكتملت عملية التعديل؛ تحقق من المورد قبل استخدام مفتاح idempotency جديد |
| `400` و`401` و`403` و`404` و`415` | لا                 | صحّح أولًا المدخلات أو بيانات الاعتماد أو الاستحقاق أو المسار أو نوع المحتوى |

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

---

# وصفات API

Source: /ar/docs/api/recipes.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;إنشاء&#x22;, icon: &#x22;site&#x22; }, { label: &#x22;التأسيس&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;نشر&#x22;, icon: &#x22;globe&#x22; }]" />

تستخدم هذه الوصفات REST الخام، لذا تعمل قبل تثبيت SDK عام. اضبط `MAF_API_KEY` في بيئة الخادم، واستبدل المعرّفات بالقيم التي أعادتها الخطوات السابقة.

## وصفة: إنشاء ونشر وكيل مستند إلى مصادر موثوقة [#وصفة-إنشاء-ونشر-وكيل-مستند-إلى-مصادر-موثوقة]

أنشئ مفتاح API واحدًا بالصلاحيات `sites:write` و`agents:write` و`knowledge:write`. أضف `sites:read` إذا كانت الأتمتة تعرض المواقع أو تتحقق منها أيضًا.

### 1. إنشاء الموقع [#1-إنشاء-الموقع]

```bash
curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'
```

الاستجابة الناجحة هي `201 Created`، وتتضمن الموقع ضمن `data`، وتعيد مسار المورد القياسي في ترويسة `Location`. احفظ `data.id` باسم `SITE_ID`.

### 2. إعداد الوكيل وسياسة التضمين [#2-إعداد-الوكيل-وسياسة-التضمين]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'
```

المصادر المسموح بها (origins) هي مصادر مطابقة تمامًا: المخطط (scheme) واسم المضيف ومنفذ اختياري. لا تُضمّن مسارًا ولا حرفًا بديلًا (wildcard) في النهاية.

### 3. إضافة مصدر معرفة نصي [#3-إضافة-مصدر-معرفة-نصي]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'
```

يجب أن يتراوح طول النص الملصوق بين 5 و200,000 حرف. يمكن لنقطة النهاية نفسها أيضًا الزحف إلى موقع ويب باستخدام `{ "url", "max_pages", "refresh_hours" }` (بحد أقصى 40 لـ `max_pages`)، أو استيراد `{ "kind": "youtube" | "podcast" | "feed", "url" }`؛ وتتطلب مصادر الوسائط هذه باقة Operate أو Scale، وتعيد `409` على باقة Launch. أما رفع الملفات فيبقى متاحًا في لوحة التحكم.

### 4. إضافة سؤال شائع منظَّم [#4-إضافة-سؤال-شائع-منظَّم]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'
```

### 5. النشر [#5-النشر]

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'
```

يجب أن تحتوي الاستجابة على `{"data":{"id":"...","status":"published"}}`. افتح تضمينًا حقيقيًا واطرح سؤالًا تظهر إجابته في المصدر. يثبت النشر أن حالة الوكيل قد تغيّرت، لكنه لا يثبت أن جودة المصدر أو مصدر التضمين (origin) صحيحان.

## وصفة: تصفّح العملاء المحتملين (Leads) صفحةً بعد صفحة بأمان [#وصفة-تصفّح-العملاء-المحتملين-leads-صفحةً-بعد-صفحة-بأمان]

استخدم مفتاحًا يملك الصلاحية `leads:read`. تعامل مع `next_cursor` على أنه قيمة معتمة (opaque) وقم بترميزه بصيغة URL.

```ts
const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);
```

لا تفكّ ترميز المؤشر (cursor) ولا تعدّله ولا تفرزه ولا تعِد استخدامه مع مجموعة بيانات مختلفة.

## وصفة: تعطيل التضمين أثناء حادث [#وصفة-تعطيل-التضمين-أثناء-حادث]

استخدم الصلاحية `agents:write` وأبقِ مفتاح idempotency نفسه عبر إعادات المحاولة الناتجة عن مشكلات الشبكة:

```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'
```

بعد نجاح الاستجابة، تحقق من أن أيقونة فتح المحادثة (launcher) لم تعد تعمل على مضيف مسموح به. أعد تفعيله بمفتاح جديد لحل الحادث بعد تصحيح مشكلة المصدر (origin) أو المحتوى أو بيانات الاعتماد.

## قائمة التحقق للإنتاج [#قائمة-التحقق-للإنتاج]

* استخدم مفتاحًا منفصلًا لكل خدمة ولكل بيئة.
* احفظ معرّفات الموارد ومفاتيح idempotency قبل إرسال أي عملية تعديل.
* حدّد مهلات للاتصال وللاستجابة.
* التزم بـ `Retry-After` وضع حدًا أقصى لإعادات المحاولة.
* سجّل اسم العملية ورمز حالة HTTP ومعرّف الطلب دون تسجيل الأسرار أو البيانات الشخصية.
* اختبر على موقع غير إنتاجي قبل منح صلاحيات الكتابة للإنتاج.

---

# مرجع API

Source: /ar/docs/api/reference.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;v1&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;123 عملية&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;JSON&#x22;, icon: &#x22;book&#x22; }]" />

المرجع المعتمد القابل للقراءة آليًا هو [OpenAPI JSON](/api/openapi.json). هذه الصفحة هي فهرس العمليات المقروء للبشر، وتشرح القواعد المشتركة بين جميع نقاط النهاية.

## عنوان URL الأساسي والإصدار [#عنوان-url-الأساسي-والإصدار]

```text
https://makeagent.fast/api/v1
```

يُعد الإصدار الرئيسي جزءًا من المسار. قد تظهر حقول إضافية دون تغيير الإصدار الرئيسي، لذا تجاهل أي حقول غير معروفة في الاستجابة. تستخدم جميع طلبات الإدارة HTTPS ومفتاح API من نوع bearer أو رمز وصول OAuth.

## الترويسات الشائعة [#الترويسات-الشائعة]

```http
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key
```

الترويسة `Content-Type` مطلوبة لأجسام JSON في طلبات `POST` و`PATCH`، بما في ذلك `{}`. أما `Idempotency-Key` فهي اختيارية، لكننا نوصي بها بشدة لكل طلب `POST` و`PATCH` و`DELETE`.

## الحساب والمواقع [#الحساب-والمواقع]

| الأسلوب  | المسار                       | النطاق         | الغرض                                                                                                                                         |
| -------- | ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/me`                        | `account:read` | قراءة ملخص الحساب والخطة والاستحقاقات والمحفظة                                                                                                |
| `GET`    | `/sites`                     | `sites:read`   | عرض المواقع المملوكة                                                                                                                          |
| `POST`   | `/sites`                     | `sites:write`  | إنشاء موقع ووكيله الافتراضي                                                                                                                   |
| `GET`    | `/sites/{site_id}`           | `sites:read`   | جلب موقع واحد مملوك                                                                                                                           |
| `PATCH`  | `/sites/{site_id}`           | `sites:write`  | تحديث حقول الموقع الآمنة                                                                                                                      |
| `DELETE` | `/sites/{site_id}`           | `sites:write`  | حذف الموقع والموارد التابعة له                                                                                                                |
| `POST`   | `/sites/{site_id}/publish`   | `sites:write`  | النشر أو إلغاء النشر باستخدام `{ "published": boolean }`                                                                                      |
| `GET`    | `/sites/{site_id}/agent`     | `agents:read`  | قراءة إعدادات الوكيل                                                                                                                          |
| `PATCH`  | `/sites/{site_id}/agent`     | `agents:write` | تحديث وضع الشخصية والغرض والاسم المعروض والتعليمات والصوت واللغات والنموذج والمظهر وإطار التضمين والشارة وحالة التضمين أو المصادر المسموح بها |
| `GET`    | `/sites/{site_id}/billing`   | `account:read` | قراءة الخطة والفترة والمحفظة والإضافات وروابط الفوترة في لوحة التحكم                                                                          |
| `PATCH`  | `/sites/{site_id}/workspace` | `team:write`   | إعادة تسمية الشركة المالكة للوكيل                                                                                                             |
| `PATCH`  | `/sites/{site_id}/retention` | `team:write`   | تحديد مدة الاحتفاظ بالمحادثات                                                                                                                 |

يتطلب إنشاء الموقع الحقلين `title` و`content.headline`. وتشمل الحقول الاختيارية `slug` و`type` و`template` ومحتوى إضافيًا و`persona_mode`، ولغة واحدة إلى أربع لغات من `en` و`ko` و`uz` و`ru`.

يمرّر الطلب `PATCH /agent` الحقول `model` و`appearance` و`embed_chrome` و`badge_hidden` عبر فحوصات الخطة نفسها المطبّقة في لوحة التحكم؛ فالقيمة `badge_hidden: true` تتطلب خطة مؤهلة أو إضافة الشارة.

## التثبيت وأداة الموقع [#التثبيت-وأداة-الموقع]

| الأسلوب | المسار                           | النطاق         | الغرض                                                               |
| ------- | -------------------------------- | -------------- | ------------------------------------------------------------------- |
| `GET`   | `/sites/{site_id}/install`       | `agents:read`  | قراءة وجهة التثبيت وحالة التضمين والمصادر المسموح بها وأدلة التثبيت |
| `PATCH` | `/sites/{site_id}/install`       | `agents:write` | تحديد الصفحة التي يجب تثبيت الأداة عليها                            |
| `POST`  | `/sites/{site_id}/install/check` | `agents:write` | التحقق مما إذا كان مقتطف التضمين يعمل في الصفحة المستهدفة           |

## المعرفة والأسئلة الشائعة [#المعرفة-والأسئلة-الشائعة]

| الأسلوب            | المسار                                                         | النطاق                               | الغرض                                                                                      |
| ------------------ | -------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ |
| `GET`              | `/sites/{site_id}/knowledge`                                   | `knowledge:read`                     | عرض مصادر المعرفة                                                                          |
| `POST`             | `/sites/{site_id}/knowledge`                                   | `knowledge:write`                    | استيعاب نص ملصوق، أو زحف موقع إلكتروني، أو استيراد مصدر YouTube أو بودكاست أو تغذية (feed) |
| `PATCH`            | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | تحديد `refresh_hours` أو `approval_status` الخاص بحزمة المشتري                             |
| `POST`             | `/sites/{site_id}/knowledge/{source_id}/recrawl`               | `knowledge:write`                    | وضع إعادة قراءة مصدر تم جلبه في قائمة الانتظار؛ يعيد `202`                                 |
| `DELETE`           | `/sites/{site_id}/knowledge/{source_id}`                       | `knowledge:write`                    | حذف مصدر واحد من الاسترجاع مستقبلًا                                                        |
| `GET`              | `/sites/{site_id}/faqs`                                        | `knowledge:read`                     | عرض الأسئلة الشائعة المنظَّمة                                                              |
| `POST`             | `/sites/{site_id}/faqs`                                        | `knowledge:write`                    | إنشاء `{ "question", "answer", "approved" }`                                               |
| `POST`             | `/sites/{site_id}/faqs/generate`                               | `knowledge:write`                    | صياغة مسودات أسئلة شائعة من معرفة الوكيل                                                   |
| `POST`             | `/sites/{site_id}/faqs/approve-all`                            | `knowledge:write`                    | اعتماد ونشر كل مسودات الأسئلة الشائعة                                                      |
| `PATCH`            | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | تحديث السؤال أو الإجابة أو حالة الاعتماد                                                   |
| `DELETE`           | `/sites/{site_id}/faqs/{faq_id}`                               | `knowledge:write`                    | حذف سؤال شائع                                                                              |
| `GET` / `PATCH`    | `/sites/{site_id}/fact-sheet`                                  | `knowledge:read` / `knowledge:write` | قراءة صحيفة الحقائق المستخرجة عن النشاط التجاري، أو تعديل الحقائق التي أخطأ الاستخراج فيها |
| `POST`             | `/sites/{site_id}/fact-sheet/reextract`                        | `knowledge:write`                    | إعادة قراءة الموقع الإلكتروني وإعادة بناء صحيفة الحقائق                                    |
| `POST`             | `/sites/{site_id}/qa`                                          | `knowledge:write`                    | نشر أزواج أسئلة وأجوبة منتقاة                                                              |
| `POST`             | `/sites/{site_id}/answers/revise`                              | `knowledge:write`                    | تعليم الوكيل الإجابة التي كان ينبغي أن يقدّمها                                             |
| `GET`              | `/sites/{site_id}/knowledge-connections`                       | `knowledge:read`                     | عرض اتصالات المعرفة مع Notion وDrive وMCP                                                  |
| `GET`              | `/sites/{site_id}/knowledge-connections/connect-links`         | `knowledge:read`                     | الحصول على عناوين URL في لوحة التحكم التي تبدأ اتصال Notion أو Drive                       |
| `PATCH` / `DELETE` | `/sites/{site_id}/knowledge-connections/{connection_id}`       | `knowledge:write`                    | تحديد وتيرة المزامنة أو العناصر المحددة أو أداة الاستيراد؛ أو فصل الاتصال وحذف بياناته     |
| `GET`              | `/sites/{site_id}/knowledge-connections/{connection_id}/items` | `knowledge:read`                     | عرض الصفحات أو قواعد البيانات أو الملفات التي يمكن للاتصال استيرادها                       |
| `POST`             | `/sites/{site_id}/knowledge-connections/{connection_id}/sync`  | `knowledge:write`                    | وضع مزامنة اتصال المعرفة في قائمة الانتظار                                                 |

يقبل `POST /knowledge` ثلاثة أنواع من الأجسام: `{ "name", "text" }` بطول من 5 إلى 200,000 حرف؛ و`{ "url", "max_pages", "refresh_hours" }` لزحف موقع إلكتروني (`max_pages` من 1 إلى 40، و`refresh_hours` من 1 إلى 8,760 أو `null`)؛ و`{ "kind": "youtube" | "podcast" | "feed", "url", "refresh_hours" }`. تتطلب مصادر YouTube والبودكاست والتغذية خطة Operate أو Scale؛ وفي خطة Launch تعيد `409 conflict`. أما رفع الملفات فيبقى عملية تتم من لوحة التحكم.

## المحادثات والعملاء المحتملون والتحليلات والاستخدام [#المحادثات-والعملاء-المحتملون-والتحليلات-والاستخدام]

| الأسلوب | المسار                                                    | النطاق                | الغرض                                                 |
| ------- | --------------------------------------------------------- | --------------------- | ----------------------------------------------------- |
| `GET`   | `/sites/{site_id}/conversations`                          | `conversations:read`  | عرض سلاسل المحادثات                                   |
| `GET`   | `/sites/{site_id}/conversations/{conversation_id}`        | `conversations:read`  | جلب سلسلة محادثة ورسائلها مقسّمة إلى صفحات            |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/reply`  | `conversations:write` | الرد على الزائر بصفة النشاط التجاري                   |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/pause`  | `conversations:write` | إيقاف الوكيل مؤقتًا في هذه المحادثة وتولّيها          |
| `POST`  | `/sites/{site_id}/conversations/{conversation_id}/resume` | `conversations:write` | إعادة المحادثة إلى الوكيل                             |
| `GET`   | `/sites/{site_id}/leads`                                  | `leads:read`          | عرض العملاء المحتملين الذين تم التقاطهم               |
| `POST`  | `/sites/{site_id}/leads`                                  | `leads:write`         | إنشاء عميل محتمل معتمد بموافقة صريحة وتفضيلات تواصل   |
| `GET`   | `/sites/{site_id}/leads/{lead_id}`                        | `leads:read`          | جلب عميل محتمل واحد                                   |
| `PATCH` | `/sites/{site_id}/leads/{lead_id}`                        | `leads:write`         | تحديث عميل محتمل أو تأهيله أو تغيير سياسة التواصل معه |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/accept`                 | `leads:write`         | قبول عميل محتمل ضمن مسار الفرص                        |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup`               | `leads:write`         | إرسال رسالة المتابعة إلى عميل محتمل                   |
| `POST`  | `/sites/{site_id}/leads/{lead_id}/followup/draft`         | `leads:write`         | إعادة صياغة رسالة المتابعة دون إرسالها                |
| `GET`   | `/sites/{site_id}/analytics`                              | `analytics:read`      | عرض أحداث التحليلات                                   |
| `GET`   | `/sites/{site_id}/report`                                 | `analytics:read`      | قراءة تقرير التحليلات المجمَّع                        |
| `POST`  | `/sites/{site_id}/report/unanswered-faq`                  | `knowledge:write`     | الإجابة عن سؤال بلا إجابة وإضافته كسؤال شائع جديد     |
| `GET`   | `/sites/{site_id}/usage`                                  | `usage:read`          | عرض أحداث الاستخدام المقاس                            |

تقبل مجموعات الأحداث والأنشطة هذه المعامِلين `limit` و`cursor`. قد تحتوي السجلات المعادة على بيانات شخصية؛ خزّنها وصدّرها وفق التزاماتك في الخصوصية.

ردود المالك مدعومة: تتولى `reply` و`pause` و`resume` سلسلة محادثة على الويب أو محادثة على Telegram أو WhatsApp أو Messenger أو Instagram بالطريقة نفسها التي تعمل بها لوحة التحكم. أما إرسال الرسائل بصفة الزائر فليس عملية عامة في API.
تعديل العملاء المحتملين مدعوم؛ لا تضبط `consent_status: granted` ما لم يكن لدى نظامك
سجل موافقة يمكن الدفاع عنه. تُستبعد الموافقة غير المعروفة من الرسائل الجماعية.

## مسار الفرص ونتائج CRM [#مسار-الفرص-ونتائج-crm]

| الأسلوب         | المسار                                                                                                        | النطاق                             | الغرض                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/stages`                                                                            | `pipeline:read` / `pipeline:write` | عرض المراحل أو إعدادها                                                                            |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/accounts`                                                                          | `pipeline:read` / `pipeline:write` | عرض حسابات الأعمال أو إنشاؤها                                                                     |
| `GET`           | `/sites/{site_id}/pipeline/accounts/{account_id}`                                                             | `pipeline:read`                    | جلب حساب أعمال                                                                                    |
| `GET` / `POST`  | `/sites/{site_id}/pipeline/opportunities`                                                                     | `pipeline:read` / `pipeline:write` | عرض الفرص أو إنشاؤها                                                                              |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline/opportunities/{opportunity_id}`                                                    | `pipeline:read` / `pipeline:write` | قراءة النشاط أو تحديث الإسناد والقيمة والمرحلة والإجراء التالي والرد البشري                       |
| `POST`          | `/sites/{site_id}/pipeline/outcomes`                                                                          | `pipeline:write`                   | استيراد نتيجة ربح أو خسارة مصدرها CRM بطريقة idempotent                                           |
| `GET`           | `/sites/{site_id}/pipeline/sync-records`                                                                      | `pipeline:read`                    | عرض حالة المزامنة والمحاولات والأخطاء                                                             |
| `POST`          | `/sites/{site_id}/pipeline/sync-records/{sync_record_id}/retry`                                               | `pipeline:write`                   | إعادة محاولة نتيجة فاشلة من حمولتها المخزَّنة                                                     |
| `GET` / `PATCH` | `/sites/{site_id}/pipeline-workflow`                                                                          | `pipeline:read` / `pipeline:write` | قراءة سياسة الرد في المبيعات أو تحديثها                                                           |
| `GET` / `POST`  | `/sites/{site_id}/pilots`                                                                                     | `pipeline:read` / `pipeline:write` | عرض التجارب التجريبية الموجَّهة أو بدؤها                                                          |
| `GET`           | `/sites/{site_id}/pilots/{pilot_id}`                                                                          | `pipeline:read`                    | قراءة تجربة تجريبية ومرحلتها وأعدادها وقائمة مهامها                                               |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/setup`, `/start`, `/stop`, `/review`, `/decision`, `/complete`, `/delete` | `pipeline:write`                   | نقل تجربة تجريبية عبر الإعداد والقياس والمراجعة والقرار والإغلاق، أو حذفها مع أدلتها (سبع عمليات) |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/outcomes`, `/bookings`                                                    | `pipeline:write`                   | تسجيل نتيجة عميل محتمل أو نتيجة حجز (عمليتان)                                                     |
| `POST`          | `/sites/{site_id}/pilots/{pilot_id}/report/approve`, `/report/revoke`                                         | `pipeline:write`                   | اعتماد تقرير التجربة القابل للمشاركة أو إلغاء اعتماده (عمليتان)                                   |
| `GET` / `POST`  | `/sites/{site_id}/buyer-packs`                                                                                | `pipeline:read` / `pipeline:write` | عرض حزم المشتري، أو إنشاء حزمة من مصادر معتمدة                                                    |
| `PATCH`         | `/sites/{site_id}/buyer-packs/{pack_id}`                                                                      | `pipeline:write`                   | استبدال عنوان الحزمة وجمهورها وملخصها ومصادرها وأقسامها                                           |
| `POST`          | `/sites/{site_id}/buyer-packs/{pack_id}/approve`, `/revoke`                                                   | `pipeline:write`                   | تفعيل رابط مشاركة الحزمة أو تعطيله (عمليتان)                                                      |

يبقى `provider` الخاص بـ CRM الذي تم تقديمه، والمعرّف الخارجي، ومفتاح idempotency
في سجل التدقيق. تتولى إعادة المحاولة سجلًا فاشلًا فقط، ولا تحوّل أبدًا
عملية كتابة خارجية قيد التنفيذ إلى نجاح كاذب.

## الموصّلات [#الموصّلات]

| الأسلوب  | المسار                                        | النطاق             | الغرض                                                                                              |
| -------- | --------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/connectors`                 | `connectors:read`  | عرض حالة الموصّلات دون الأسرار                                                                     |
| `POST`   | `/sites/{site_id}/connectors`                 | `connectors:write` | ربط قناة: التحقق من بيانات الاعتماد مباشرةً، وتهيئة webhook الخاص بها، وإرجاع قائمة مراجعة الإعداد |
| `PATCH`  | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | تحديد `status` أو `reply_with_voice`                                                               |
| `DELETE` | `/sites/{site_id}/connectors/{connector_id}`  | `connectors:write` | إلغاء تهيئة موصّل وإزالته                                                                          |
| `POST`   | `/sites/{site_id}/concierge`                  | `connectors:write` | طلب أن تتولى المنصة ربط قناة مراسلة نيابةً عنك                                                     |
| `GET`    | `/sites/{site_id}/domains`                    | `domains:read`     | أُزيل — يعيد `409`. النطاقات المخصصة غير متاحة                                                     |
| `POST`   | `/sites/{site_id}/domains`                    | `domains:write`    | أُزيل — يعيد `409`                                                                                 |
| `PATCH`  | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | أُزيل — يعيد `409`                                                                                 |
| `POST`   | `/sites/{site_id}/domains/{domain_id}/verify` | `domains:write`    | أُزيل — يعيد `409`                                                                                 |
| `DELETE` | `/sites/{site_id}/domains/{domain_id}`        | `domains:write`    | أُزيل — يعيد `409`                                                                                 |

يستخدم إنشاء الموصّل جسمًا يتحدد بحسب القناة. تختلف حقول بيانات الاعتماد بين `telegram` و`whatsapp` و`messenger` و`instagram` و`discord` و`kakao`؛ استخدم دليل الموصّل المطابق قبل إرسال الأسرار.

## الرسائل الجماعية والإشعارات وتحقيق الدخل [#الرسائل-الجماعية-والإشعارات-وتحقيق-الدخل]

| الأسلوب  | المسار                                                | النطاق                | الغرض                                                         |
| -------- | ----------------------------------------------------- | --------------------- | ------------------------------------------------------------- |
| `GET`    | `/sites/{site_id}/broadcasts`                         | `broadcasts:read`     | عرض الرسائل الجماعية                                          |
| `POST`   | `/sites/{site_id}/broadcasts`                         | `broadcasts:write`    | إنشاء مسودة رسالة جماعية عبر Kakao                            |
| `POST`   | `/sites/{site_id}/broadcasts/{broadcast_id}/send`     | `broadcasts:write`    | وضع مسودة موجودة في قائمة الانتظار؛ يعيد `202`                |
| `GET`    | `/sites/{site_id}/notifications`                      | `notifications:read`  | عرض إشعارات المالك                                            |
| `POST`   | `/sites/{site_id}/notifications/read-all`             | `notifications:write` | تعليم جميع إشعارات المالك لهذا الوكيل كمقروءة                 |
| `PATCH`  | `/sites/{site_id}/notifications/{notification_id}`    | `notifications:write` | التعليم كمقروء أو غير مقروء باستخدام `{ "read": boolean }`    |
| `GET`    | `/sites/{site_id}/alerts`                             | `notifications:read`  | قراءة حالة قناة تنبيهات المالك ورابطها في لوحة التحكم         |
| `GET`    | `/sites/{site_id}/monetization/products`              | `monetization:read`   | عرض منتجات الموقع                                             |
| `POST`   | `/sites/{site_id}/monetization/products`              | `monetization:write`  | إنشاء منتج من نوع `access` أو `consult` أو `tip` أو `digital` |
| `PATCH`  | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | تحديث حقول المنتج وحالة تفعيله                                |
| `DELETE` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write`  | حذف منتج                                                      |

يقبل إنشاء الرسائل الجماعية حاليًا القناة `kakao` فقط. يفشل وضعها في قائمة الانتظار مع `409 conflict` عندما لا يوجد مستلمون يمكن الوصول إليهم أو عندما لا تعود الرسالة مسودة.

## الإجراءات والتذاكر والفريق [#الإجراءات-والتذاكر-والفريق]

| الأسلوب            | المسار                                              | النطاق                         | الغرض                                                                               |
| ------------------ | --------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `GET` / `PATCH`    | `/sites/{site_id}/actions`                          | `agents:read` / `agents:write` | قراءة أو إعداد الإجراءات وwebhook العام ورابط الحجز وتذاكر الدعم                    |
| `GET`              | `/sites/{site_id}/tickets`                          | `tickets:read`                 | عرض تذاكر الدعم                                                                     |
| `GET`              | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:read`                 | قراءة تذكرة ورسائلها                                                                |
| `PATCH`            | `/sites/{site_id}/tickets/{ticket_id}`              | `tickets:write`                | تحديد الحالة والأولوية والمسؤول المعيَّن (اختياري)                                  |
| `POST`             | `/sites/{site_id}/tickets/{ticket_id}/messages`     | `tickets:write`                | إضافة ملاحظة داخلية، أو ضبط `internal: false` للرد على العميل عبر البريد الإلكتروني |
| `GET`              | `/sites/{site_id}/team`                             | `team:read`                    | قراءة الأعضاء والدعوات وأحداث التدقيق المسموح بها                                   |
| `POST`             | `/sites/{site_id}/team/invitations`                 | `team:write`                   | إنشاء رابط دعوة دون إرسال بريد إلكتروني                                             |
| `DELETE`           | `/sites/{site_id}/team/invitations/{invitation_id}` | `team:write`                   | إلغاء دعوة معلّقة                                                                   |
| `PATCH` / `DELETE` | `/sites/{site_id}/team/members/{membership_id}`     | `team:write`                   | تغيير دور عضو غير مالك، أو إزالة العضو                                              |

## Webhooks للمطورين وأدوات الإعداد [#webhooks-للمطورين-وأدوات-الإعداد]

| الأسلوب  | المسار                             | النطاق                 | الغرض                                                                                                                                                            |
| -------- | ---------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/webhook-endpoints`               | `webhooks:read`        | عرض حالة نقاط النهاية دون أسرار التوقيع                                                                                                                          |
| `POST`   | `/webhook-endpoints`               | `webhooks:write`       | تسجيل عنوان URL عام عبر HTTPS وإظهار سر التوقيع مرة واحدة                                                                                                        |
| `DELETE` | `/webhook-endpoints/{endpoint_id}` | `webhooks:write`       | حذف نقطة نهاية وإيقاف التسليم مستقبلًا                                                                                                                           |
| `GET`    | `/setup/tools`                     | أي بيانات اعتماد صالحة | اكتشاف أدوات الإعداد لتكاملات API وMCP وGitHub                                                                                                                   |
| `POST`   | `/setup/tools/{tool_name}`         | بحسب الأداة            | تشغيل أداة إعداد؛ تتطلب طلبات المنصة نطاقات نقاط النهاية الخاصة بها، ويستخدم فحص GitHub النطاق `integrations:read`، ويستخدم إعداد PR النطاق `integrations:write` |

يجب أن تستخدم عناوين URL الخاصة بـ webhook بروتوكول HTTPS، ولا يجوز أن تتضمن بيانات اعتماد أو منفذًا مخصصًا، ويجب أن تُحلَّ إلى عناوين IP عامة فقط.

## ترقيم الصفحات [#ترقيم-الصفحات]

تقبل المجموعات المقسّمة إلى صفحات المعامِل `limit` من `1` إلى `100`؛ والقيمة الافتراضية `50`. استخدم `next_cursor` المعتم المُعاد مع المجموعة والمرشِّحات نفسها فقط.

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

تعيد بعض مجموعات الإعدادات الصغيرة الغلاف نفسه مع `has_more: false` ولا تحتاج إلى مؤشر (cursor).

## Idempotency [#idempotency]

يجب أن يتكوّن مفتاح idempotency من 8 إلى 200 حرف من الأحرف والأرقام و`.` و`_` و`:` و`-`. تُحفَظ النتائج لمدة 24 ساعة وتُحصر في نطاق مالك بيانات الاعتماد.

* المفتاح نفسه مع الأسلوب والمسار والاستعلام والجسم نفسها: يعيد الاستجابة المخزَّنة مع `x-idempotent-replayed: true`.
* المفتاح نفسه مع مدخلات مختلفة: يعيد `409 conflict`.
* المفتاح نفسه أثناء معالجة الطلب الأول: يعيد `409 conflict` و`Retry-After: 2`.

احفظ المفتاح قبل إرسال عملية التعديل، ولا تعد استخدامه إلا لإعادة محاولات العملية المنطقية نفسها.

## الاستجابات والأخطاء [#الاستجابات-والأخطاء]

تغلّف استجابات النجاح مواردها داخل `data`. تعيد عمليات الإنشاء عادةً `201`؛ وتعيد عمليات إرسال الرسائل الجماعية الموضوعة في قائمة الانتظار `202`؛ وتعيد العمليات الناجحة الأخرى `200`. تتضمن كل استجابة `x-request-id` وتستخدم `Cache-Control: no-store` لبيانات API.

راجع [النطاقات والأخطاء](/ar/docs/api/scopes-errors) للاطلاع على جدول رموز الأخطاء الكامل، و[وصفات API](/ar/docs/api/recipes) لسير عمل جاهزة للنسخ.

## عملاء MCP [#عملاء-mcp]

اربط عميل MCP يدعم Streamable HTTP بالعنوان `https://makeagent.fast/api/mcp`. تفتح العملاء التي تدعم اكتشاف OAuth المتصفح لتسجيل الدخول والموافقة. تحقّق من هوية العميل والشركة والنطاقات المطلوبة قبل الموافقة. تطلب الموافقة الأولى النطاقات التي تستخدمها الأدوات (`sites:read` و`sites:write` و`agents:write` و`analytics:read` و`conversations:read` و`conversations:write` و`leads:read` و`leads:write` و`knowledge:write`)؛ وتُطالَب بيانات الاعتماد التي ينقصها أحدها بالتفويض مرة أخرى. يلزم وجود خطة نشطة.

بالنسبة إلى العملاء الذين يستخدمون بيانات اعتماد مهيأة يدويًا، أنشئ مفتاح API محدد النطاق في [إعدادات المطورين](/dashboard/settings/developer) وأرسله في الترويسة `Authorization: Bearer ...`. أبقِ بيانات الاعتماد بعيدة عن التحكم بالمصدر وعن شيفرة المتصفح. يمكنك إلغاء مفاتيح API أو منح OAuth من إعدادات المطورين.

أدوات القراءة: `list_agents` و`get_agent` و`get_report` و`list_unanswered_questions` و`list_conversations` و`get_conversation` و`list_leads`. أدوات الكتابة: `create_agent_from_website` و`create_agent_from_notes` و`test_agent` و`add_knowledge` و`save_answer` و`reply_to_customer` و`update_lead` و`set_website_widget`. تأخذ كل أداة خاصة بالوكيل `agent_id` من `list_agents`. تستهلك `test_agent` الرصيد (Credits) مثل أي إجابة عادية؛ وترسل `reply_to_customer` رسالة إلى العميل وتوقف الوكيل مؤقتًا في تلك المحادثة؛ وتشغّل `set_website_widget` أداة دردشة الموقع أو تُطفئها؛ أما قنوات المراسلة فتُدار من لوحة التحكم. تحصل العملاء التي فُعّلت لديها MCP Apps (افتراضيًا اتصال Claude المصادَق عليه) أيضًا على `list_pending_approvals` و`list_action_runs` و`decide_approval`، التي توافق على تغيير أكّده العميل أو ترفضه؛ أما العملاء الآخرون فلا يرون سوى الأدوات الخمس عشرة المذكورة أعلاه. بالنسبة إلى أدوات الإعداد وتكامل GitHub، استخدم مساعد الإعداد داخل التطبيق أو `/api/v1/setup/tools`.

مراجعات البروتوكول المدعومة هي `2026-07-28` و`2025-11-25` و`2025-06-18`. يعيد النقل بيانات JSON؛ ولا يوفّر SSE القديم ولا جلسات الخادم. تفوّض رموز MCP OAuth الوصول إلى `/api/mcp` فقط، وليس إلى طلبات REST المباشرة. تدوم رموز وصول OAuth ساعة واحدة؛ وتتجدد بيانات اعتماد التحديث وتنتهي صلاحيتها بعد 90 يومًا. تستخدم مفاتيح API المُنشأة يدويًا مدة الصلاحية التي ضُبطت لها.

---

# النطاقات والأخطاء

Source: /ar/docs/api/scopes-errors.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;33 نطاقًا&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;رموز ثابتة&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;معرّفات الطلبات&#x22;, icon: &#x22;link&#x22; }]" />

تتطلب كل عملية في واجهة API العامة نطاقًا صريحًا واحدًا. وإذا كانت بيانات الاعتماد صالحة لكنها لا تملك هذا النطاق، فستتلقى الخطأ `403 insufficient_scope`؛ ولا تتم ترقيتها أبدًا بصمت إلى صلاحيات أوسع.

## مرجع النطاقات [#مرجع-النطاقات]

| النطاق                | ما يتيحه                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `account:read`        | قراءة الحساب المصادَق عليه والخطة والاستحقاقات وملخص المحفظة                                                 |
| `tickets:read`        | قراءة تذاكر الدعم ورسائلها                                                                                   |
| `tickets:write`       | تحديث التذاكر وتعيين أعضاء الفريق وإضافة ملاحظات داخلية أو ردود للعملاء                                      |
| `team:read`           | قراءة أعضاء الفريق والدعوات المعلّقة وأحداث التدقيق المسموح بها                                              |
| `team:write`          | إنشاء الدعوات أو إلغاؤها وإدارة أدوار أعضاء الفريق من غير المالكين                                           |
| `integrations:read`   | فحص عمليات تثبيت GitHub App والمستودعات المصرّح بها                                                          |
| `integrations:write`  | إعداد تغييرات التكامل وإنشاء طلبات سحب مسودة                                                                 |
| `sites:read`          | عرض المواقع واسترجاعها                                                                                       |
| `sites:write`         | إنشاء المواقع وتحديثها ونشرها وإلغاء نشرها وحذفها                                                            |
| `agents:read`         | قراءة إعدادات الـ agent                                                                                      |
| `agents:write`        | تحديث سلوك الـ agent ولغته وصوته وإعدادات التضمين                                                            |
| `knowledge:read`      | عرض مصادر المعرفة والأسئلة الشائعة                                                                           |
| `knowledge:write`     | إنشاء مصادر المعرفة والأسئلة الشائعة وتحديثها وحذفها                                                         |
| `conversations:read`  | عرض المحادثات واسترجاع رسائلها                                                                               |
| `conversations:write` | تولّي محادثة: الرد على الزائر باسم النشاط التجاري، وإيقاف الـ agent مؤقتًا فيها، وإعادتها إليه               |
| `leads:read`          | عرض الـ leads الذين تم جمعهم                                                                                 |
| `leads:write`         | إنشاء الـ leads وتحديثهم وتأهيلهم وقبولهم في مسار الفرص                                                      |
| `pipeline:read`       | قراءة المراحل والحسابات والفرص والأنشطة والإسناد وحالة مزامنة CRM                                            |
| `pipeline:write`      | ضبط المراحل؛ وإنشاء الفرص والحسابات أو تحديثها؛ واستيراد نتائج CRM أو إعادة محاولتها                         |
| `analytics:read`      | قراءة أحداث تحليلات الموقع                                                                                   |
| `connectors:read`     | عرض حالة الـ connectors دون إرجاع الأسرار                                                                    |
| `connectors:write`    | إنشاء الـ connectors وتحديثها وتفعيلها وتعطيلها وإزالتها                                                     |
| `domains:read`        | أُزيل. يُحتفظ به لأغراض التوافق فقط؛ إذ تعيد كل مسارات `/domains` الخطأ `409` لأن النطاقات المخصصة غير متاحة |
| `domains:write`       | أُزيل. يُحتفظ به لأغراض التوافق فقط؛ إذ تعيد كل مسارات `/domains` الخطأ `409`                                |
| `broadcasts:read`     | عرض الرسائل الجماعية وحالة التسليم                                                                           |
| `broadcasts:write`    | إنشاء المسودات ووضع إرسال رسالة جماعية في قائمة الانتظار                                                     |
| `notifications:read`  | عرض إشعارات المالك                                                                                           |
| `notifications:write` | تعليم الإشعارات كمقروءة أو غير مقروءة                                                                        |
| `monetization:read`   | عرض منتجات تحقيق الدخل                                                                                       |
| `monetization:write`  | إنشاء المنتجات وتحديثها وتفعيلها وإلغاء تفعيلها وحذفها                                                       |
| `usage:read`          | قراءة أحداث الاستخدام المقاس                                                                                 |
| `webhooks:read`       | عرض نقاط نهاية webhook وحالة التسليم                                                                         |
| `webhooks:write`      | إنشاء نقاط نهاية webhook وحذفها                                                                              |

استخدم نطاقات القراءة لمهام إعداد التقارير. وأضف نطاق الكتابة فقط عندما ينفّذ التكامل هذا التعديل فعلًا. فعلى سبيل المثال، يحتاج تصدير الـ leads عادةً إلى `sites:read` و`leads:read`، لا إلى `sites:write` أو `agents:write`.

## أخطاء النطاقات [#أخطاء-النطاقات]

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}
```

أضف النطاق الناقص إلى المفتاح من **الإعدادات ← المطوّر ← تعديل**، أو أنشئ مفتاحًا بديلًا وحدّث السر المخزَّن على الخادم. يغيّر التعديل اسم المفتاح ونطاقاته في مكانه؛ أما تاريخ انتهاء صلاحيته والرمز المميّز فيبقيان كما هما. لا يمكن تعديل المفاتيح الصادرة عبر OAuth؛ أعد ربط التطبيق لتغيير ما مُنح من صلاحيات.

## غلاف الخطأ [#غلاف-الخطأ]

تستخدم جميع أخطاء API البنية العليا نفسها:

```ts
type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};
```

اعتمد في المعالجة على `error.code` لا على `message` الإنجليزية، فقد تتحسن الرسائل دون تغيير الإصدار. سجّل `error.request_id` وترويسة الاستجابة `x-request-id` مع اسم العملية والحالة ورقم محاولة إعادة الطلب، لكن لا تسجّل أبدًا ترويسة التفويض أو أسرار الطلب.

## مرجع الحالات والرموز [#مرجع-الحالات-والرموز]

| HTTP  | الرمز الثابت              | المعنى                                                                           | الاستجابة المعتادة                                                                                                 |
| ----- | ------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `400` | `invalid_request`         | فشل التحقق من الصحة أو أن أحد الحقول غير مدعوم                                   | صحّح الحقول الواردة في `details`؛ ولا تعِد المحاولة بالمدخلات نفسها                                                |
| `400` | `invalid_json`            | الجسم ليس كائن JSON أو يحتوي على JSON غير صالح                                   | أرسل كائن JSON صالحًا واحدًا                                                                                       |
| `401` | `authentication_required` | ترويسة Bearer مفقودة                                                             | أرفق بيانات اعتماد من جهة الخادم                                                                                   |
| `401` | `invalid_api_key`         | المفتاح غير صالح أو منتهي الصلاحية أو ملغى، أو لم يعد مالكه موجودًا              | استبدل المفتاح أو دوّره                                                                                            |
| `403` | `subscription_required`   | لا يملك المالك خطة مدفوعة نشطة                                                   | استعد الاشتراك قبل إعادة المحاولة                                                                                  |
| `403` | `insufficient_scope`      | تفتقر بيانات الاعتماد إلى نطاق العملية                                           | أنشئ بيانات اعتماد بديلة بأقل قدر من الصلاحيات                                                                     |
| `403` | `account_paused`          | وصول API متوقف مؤقتًا للحساب                                                     | استأنف وصول API أو تواصل مع مالك الحساب                                                                            |
| `404` | `not_found`               | لم يُعثر على نقطة النهاية أو المورد المملوك                                      | تحقق من المسار ومن المعرّف التابع للمستأجر                                                                         |
| `409` | `conflict`                | حالة المورد الحالية تمنع تنفيذ الإجراء                                           | اقرأ الحالة الحالية قبل إعادة المحاولة                                                                             |
| `413` | `payload_too_large`       | جسم JSON يتجاوز حد الطلب البالغ 256 KB                                           | أرسل جسمًا أصغر؛ وقسّم المحتوى الكبير على عدة طلبات                                                                |
| `415` | `invalid_request`         | جسم التعديل ليس `application/json`                                               | أرسل `Content-Type: application/json`                                                                              |
| `429` | `rate_limit_exceeded`     | استُنفدت حصة الدقيقة الواحدة في خطة المفتاح                                      | انتظر حسب `Retry-After` وأضف تأخيرًا عشوائيًا (jitter)                                                             |
| `500` | `internal_error`          | تعذّر إكمال الطلب                                                                | أعد محاولة العملية الآمنة أو القابلة للتكرار دون أثر جانبي، وأبلغ عن معرّف الطلب                                   |
| `503` | `outcome_unknown`         | ربما اكتمل التعديل، لكن تعذّر تسجيل نتيجته؛ وقيمة `details.retryable` هي `false` | لا تعِد المحاولة. اقرأ المورد لمعرفة ما إذا كان التغيير قد حدث؛ ويستمر مفتاح idempotency نفسه في إرجاع هذه النتيجة |

قد تعيد الموارد الواقعة خارج حساب مالك بيانات الاعتماد الخطأ `404` بدلًا من الكشف عمّا إذا كان معرّف يخص مستأجرًا آخر موجودًا.

## تفاصيل التحقق من الصحة [#تفاصيل-التحقق-من-الصحة]

يعيد التحقق من الحقول مسارات يمكن عرضها بجانب عناصر النموذج لديك:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}
```

يجب أن تكون أجسام التعديل كائنات JSON. وتُرفض المصفوفات والأجسام الفارغة وبيانات النماذج وJSON المرسل بنوع محتوى نصي.

## قرارات إعادة المحاولة [#قرارات-إعادة-المحاولة]

* أعد محاولة `429` بعد عدد الثواني المحدد في `Retry-After`.
* أعد محاولة `500` فقط في عمليات القراءة الآمنة أو عمليات الكتابة المحمية بالمفتاح `Idempotency-Key` نفسه.
* أعد محاولة `409` الخاص بـ idempotency قيد التنفيذ بعد المدة الواردة في الترويسة `Retry-After: 2`.
* لا تعِد محاولة `503 outcome_unknown` بشكل أعمى. تحقق من المورد أولًا؛ ولا تستخدم مفتاح idempotency جديدًا إلا بعد التأكد من أن التغيير لم يحدث.
* لا تعِد محاولة `400` أو `401` أو `403` أو `404` أو `413` أو تعارض الحالة إلا بعد تغيّر السبب.

راجع [حدود المعدل](/ar/docs/api/rate-limits) لمعرفة سلوك التراجع، و[مرجع API](/ar/docs/api/reference) لمعرفة النطاق المطلوب لكل عملية.

---

# حالة SDK

Source: /ar/docs/api/sdks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;REST متاحة&#x22;, icon: &#x22;globe&#x22; }, { label: &#x22;OpenAPI&#x22;, icon: &#x22;code&#x22; }, { label: &#x22;معاينة SDK&#x22;, icon: &#x22;bolt&#x22; }]" />

تُعدّ واجهة REST API ذات الإصدارات هي واجهة التكامل العامة المدعومة حاليًا. تتوفر الشيفرة المصدرية لعملاء JavaScript وPython وأطر العمل في مستودع المنتج، لكن الحزم غير منشورة حاليًا على npm أو PyPI.

## التوفر [#التوفر]

| العميل                       | الحالة                                  | طريقة الاستخدام                                                                                 |
| ---------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| REST عبر HTTPS               | **متاح**                                | استدعِ `https://makeagent.fast/api/v1` من أي عميل HTTP على الخادم                               |
| مستند OpenAPI                | **متاح**                                | نزّل [/api/openapi.json](/api/openapi.json) وافحصه قبل توليد أي عميل                            |
| `@make-agent-fast/sdk`       | **معاينة مصدرية — غير متوفر على npm**   | لا تضف هذا الاستيراد إلى مشروع إنتاجي إلى أن يُضاف هنا رابط إصدار منشور في سجل الحزم            |
| حزمة Python ‏`makeagentfast` | **معاينة مصدرية — غير متوفرة على PyPI** | استخدم `requests` أو `httpx` أو المكتبة القياسية في Python إلى أن يُضاف هنا رابط إصدار على PyPI |
| محولات React وVue وSvelte    | **معاينة مصدرية — غير متوفرة على npm**  | يُفضّل اتباع نمط تحميل السكربت الموثّق لإطار العمل                                              |
| Web component                | **معاينة مصدرية — غير متوفر على npm**   | يُفضّل استخدام المحمّل القياسي `embed.js`                                                       |

<Callout title="المجلد المصدري ليس إصدارًا منشورًا للحزمة" tone="warning">
  لا تشغّل `npm install @make-agent-fast/sdk` أو `pip install makeagentfast` بالاعتماد على مثال استيراد فقط. ستتضمن هذه الصفحة رابط السجل والإصدار وإرشادات التحقق من السلامة وأمر التثبيت عند نشر حزمة عامة.
</Callout>

## JavaScript بدون SDK [#javascript-بدون-sdk]

```ts
const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);
```

احتفظ بمفتاح API على الخادم. يجب أن تستدعي حزمة المتصفح في React أو Vue أو Svelte الواجهة الخلفية الخاصة بك أو أن تثبّت محمّل التضمين العام؛ ولا يجوز أن تستدعي واجهة الإدارة البرمجية بمفتاح سري.

## Python بدون SDK [#python-بدون-sdk]

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])
```

التقط الاستثناء `urllib.error.HTTPError` في بيئة الإنتاج وحلّل محتوى JSON في الاستجابة وفق [غلاف الأخطاء المستقر](/ar/docs/api/scopes-errors).

## العملاء المولَّدون [#العملاء-المولَّدون]

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

```bash
curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json
```

لا تعِد توليد العميل ونشره تلقائيًا من الرابط المباشر. فإضافة حقل جديد لا ينبغي أن تعطّل العميل، لكن سلوك المولِّد وأسماء الدوال المولَّدة قد يتغيران مع ذلك.

## ما يجب أن يتضمنه إصدار SDK عام [#ما-يجب-أن-يتضمنه-إصدار-sdk-عام]

قبل اعتبار أي عميل معاينة متاحًا، يجب أن يتوفر فيه ما يلي:

* صفحة عامة في سجل الحزم وإصدار دلالي (semantic version) غير قابل للتغيير.
* إرشادات التثبيت والترقية وبيئات التشغيل المدعومة.
* نماذج مكتوبة الأنواع للطلبات والاستجابات مولَّدة من عقد API الكامل.
* أخطاء منظَّمة تحتفظ برمز حالة HTTP ومعرّف الطلب.
* أدوات مساعدة للترقيم الصفحي تتعامل مع المؤشرات (cursors) على أنها مبهمة.
* دعم صريح لمفتاح عدم التكرار (idempotency key) في عمليات التعديل.
* اختبارات CI على عقد `/api/v1` الحالي وسجل تغييرات منشور.

إلى أن تتحقق هذه الشروط، استخدم أمثلة REST في [البدء السريع لـ API](/ar/docs/api/quickstart) و[وصفات API](/ar/docs/api/recipes).

---

# Webhooks

Source: /ar/docs/api/webhooks.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;HMAC-SHA256&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;مرة واحدة على الأقل&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;8 محاولات&#x22;, icon: &#x22;layers&#x22; }]" />

ترسل Webhooks الخاصة بالمطورين أحداث الحساب إلى الخادم لديك، فلا تحتاج إلى الاستعلام الدوري. التسليم يتم مرة واحدة على الأقل: قد تتكرر الأحداث أو تتأخر أو تصل بترتيب مختلف.

## تسجيل نقطة نهاية [#تسجيل-نقطة-نهاية]

أنشئ مفتاحًا بالصلاحية `webhooks:write`، ثم سجّل مستقبِلًا عامًا عبر HTTPS مع أصغر مجموعة أحداث تحتاج إليها.

```bash
curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-production-v1" \
  -d '{
    "url": "https://api.example.com/webhooks/make-agent-fast",
    "events": ["lead.created", "conversation.started"]
  }'
```

يجب أن يستخدم عنوان URL بروتوكول HTTPS، ولا يجوز أن يحتوي على اسم مستخدم أو كلمة مرور أو جزء (fragment) أو منفذ مخصص، ويجب أن يُحلَّ إلى عناوين IP عامة فقط. لا تُتبع عمليات إعادة التوجيه أثناء التسليم.

تكشف الاستجابة `201` عن سر التوقيع `whsec_...` مرة واحدة فقط. خزّنه في مدير الأسرار الخاص بالمستقبِل قبل إغلاق الاستجابة. عند عرض نقاط النهاية لاحقًا ستحصل على عنوان URL والأحداث والحالة وآخر عملية تسليم وآخر خطأ، لكن دون السر.

## أنواع الأحداث [#أنواع-الأحداث]

| الحدث                          | يُرسَل عندما                                                             |
| ------------------------------ | ------------------------------------------------------------------------ |
| `site.published`               | يصبح الموقع منشورًا                                                      |
| `site.unpublished`             | يعود الموقع إلى حالة المسودة                                             |
| `lead.created`                 | يلتقط الـ agent عميلًا محتملًا (Lead) جديدًا                             |
| `lead.qualified`               | يؤهّل الـ agent عميلًا محتملًا، أو يُقبل العميل المحتمل في مسار المبيعات |
| `booking.requested`            | يطلب زائر موعدًا أو يحجزه                                                |
| `handoff.requested`            | يحوّل الـ agent محادثة إلى شخص (Handoff)                                 |
| `opportunity.created`          | يتحول عميل محتمل إلى فرصة في مسار المبيعات                               |
| `opportunity.updated`          | يتغير إسناد الفرصة أو قيمتها أو إجراؤها التالي أو حقول أخرى فيها         |
| `opportunity.stage_changed`    | تنتقل الفرصة إلى مرحلة أخرى                                              |
| `opportunity.won`              | تُغلق الفرصة كصفقة رابحة                                                 |
| `opportunity.lost`             | تُغلق الفرصة كصفقة خاسرة                                                 |
| `conversation.started`         | تبدأ سلسلة محادثة جديدة                                                  |
| `conversation.message.created` | تُضاف رسالة إلى محادثة                                                   |
| `knowledge.ready`              | يكتمل تجهيز مصدر معرفة (Source)                                          |
| `broadcast.sent`               | تنتهي رسالة جماعية من سير عمل الإرسال                                    |
| `domain.activated`             | حدث متقاعد: النطاقات المخصصة غير متاحة، ولا يُرسَل هذا الحدث أبدًا       |

## تنسيق الطلب [#تنسيق-الطلب]

يرسل Make Agent Fast طلب `POST` مع `Content-Type: application/json` و`User-Agent: MakeAgentFast-Webhooks/1.0` والترويسات التالية:

```http
maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256
```

يتخذ نص JSON غلافًا ثابتًا. تعتمد الحقول داخل `data` على الحدث، ويمكن أن تُضاف إليها حقول جديدة.

```json
{
  "id": "evt_2c34...",
  "type": "lead.created",
  "created_at": "2026-07-16T10:02:46.000Z",
  "data": {
    "site_id": "SITE_ID",
    "lead_id": "LEAD_ID"
  }
}
```

استخدم `id` من النص أو `maf-event-id` مفتاحًا لإزالة التكرار. لا تستخدم وقت التسليم ولا معرّف قاعدة بيانات مولَّدًا.

## التحقق من التوقيع في Node.js [#التحقق-من-التوقيع-في-nodejs]

اقرأ البايتات الخام كما وصلت قبل تحليل JSON. القيمة الموقّعة هي `TIMESTAMP + "." + RAW_BODY`.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  const supplied = values.v1;
  if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;

  const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}
```

ارفض التوقيعات المشوّهة والطوابع الزمنية الأقدم من نافذة إعادة التشغيل (replay) المقبولة لديك؛ وخمس دقائق قيمة افتراضية معقولة. قارن البايتات ذات الطول الثابت بزمن ثابت.

## التحقق من التوقيع في Python [#التحقق-من-التوقيع-في-python]

```python
import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = values.get("t", "")
    supplied = values.get("v1", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, supplied)
```

لا تحلّل JSON ولا تعالجه إلا بعد نجاح التحقق من التوقيع.

## الإقرار والمعالجة [#الإقرار-والمعالجة]

1. تحقق من التوقيع والطابع الزمني.
2. أدرج معرّف الحدث في جدول بقيد تفرّد (unique constraint).
3. إذا كان موجودًا مسبقًا، فأعد `204` دون تكرار الأثر الجانبي.
4. ثبّت الحدث (commit) أو أضف مهمتك الداخلية إلى قائمة الانتظار.
5. أعد استجابة `2xx` بسرعة.

ينتهي مهلة المرسِل في Make Agent Fast بعد 10 ثوانٍ. ويعدّ استجابات `2xx` فقط ناجحة، ولا يتبع عمليات إعادة التوجيه.

## سلوك إعادة المحاولة [#سلوك-إعادة-المحاولة]

توضع عمليات التسليم الفاشلة في قائمة انتظار بحد أقصى ثماني محاولات. يبدأ التأخير التراجعي (backoff) عند نحو ثانيتين، ويتضاعف مع تشويش عشوائي (jitter)، ويبلغ حده الأقصى ساعة واحدة؛ وقد يتأخر وقت التسليم الفعلي عندما تكون العمليات المنفِّذة مشغولة. ولأن إعادة المحاولات قد تتجاوز عمر الطلب الذي أطلقها وقد تصل بترتيب مختلف، فلا تعتمد أبدًا على وصول حدث ما مباشرة قبل حدث آخر.

أعد استجابة غير `2xx` فقط عندما تريد أن يعيد Make Agent Fast المحاولة. وفي حالة إصدار حدث غير مدعوم نهائيًا أو وجهة محذوفة، اقبل الحدث وسجّله أو احذف نقطة النهاية، بدلًا من إنتاج إخفاقات مؤقتة لا تنتهي.

## تدوير سر التوقيع [#تدوير-سر-التوقيع]

لا يمكن كشف أسرار التوقيع ولا تعديلها. لتدويرها بأمان:

1. أنشئ نقطة نهاية ثانية تشير إلى مسار مستقبِل مؤقت أو مُرقَّم بإصدار.
2. خزّن السر الجديد الذي كُشف لك.
3. اقبل الأحداث من نقطتي النهاية معًا مع إزالة التكرار.
4. تأكد أن نقطة النهاية الجديدة تتلقى عمليات تسليم صالحة.
5. احذف نقطة النهاية القديمة عبر `DELETE /webhook-endpoints/{endpoint_id}`.

إذا بقي عنوان URL الخاص بالمستقبِل كما هو، فاجعل التطبيق المستقبِل يقبل السرّين خلال فترة التداخل، واستخدم معرّفات الأحداث لمنع تكرار الآثار الجانبية.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض              | ما يجب فحصه                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| لا توجد عمليات تسليم | حالة نقطة النهاية، والأحداث المحددة، وDNS العام، وشهادة HTTPS، وهل وقع الحدث فعلًا                                           |
| عدم تطابق التوقيع    | الوصول إلى النص الخام، والتسلسل الدقيق `timestamp.body`، وسر نقطة النهاية الصحيح، وأي تحويلات يجريها الوكيل (proxy) على النص |
| عمليات تسليم متكررة  | رمز الاستجابة، ومهلة 10 ثوانٍ، والاستثناءات الداخلية، وتفرّد معرّف الحدث                                                     |
| خطأ عنوان خاص        | يجب أن تُحلّ سجلات DNS إلى عناوين عامة فقط؛ يُرفض localhost والنطاقات الداخلية                                               |
| فشل إعادة التوجيه    | سجّل عنوان HTTPS النهائي مباشرة؛ لا تُتبع عمليات إعادة التوجيه                                                               |

لا تضمّن سر التوقيع أو مفتاح bearer أو الحمولة الكاملة للزائر في أي رسالة إلى الدعم. أرفق معرّف نقطة النهاية ومعرّف الحدث ووقت الفشل وسجلات المستقبِل بعد تنقيتها.

---

# العرض

Source: /ar/docs/build/appearance.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;السمة&#x22;, icon: &#x22;spark&#x22; }, { label: &#x22;الدردشة&#x22;, icon: &#x22;chat&#x22; }, { label: &#x22;المكالمة المباشرة&#x22;, icon: &#x22;voice&#x22; }]" />

يتحكم مظهر الأداة في شكل **الدردشة** و**المكالمة المباشرة** للزائر معًا، ويشمل الألوان والسمة والزوايا والظل والتأثير الزجاجي والخطوط. ولا يُنشئ هذا المظهر صفحة تسويقية مستضافة. تُطلَق الوكلاء الجدد كعنصر تضمين داخل موقعك الحالي.

افتح صفحة **الوكيل** الخاصة بالوكيل ثم اختر تبويب **العرض**. تنطبق جميع عناصر التحكم على الواجهتين معًا، وتعرض اللوحة الحية بجانب التبويب الأداة الفعلية.

<TutorialVideo episode="ep02" start="108" />

## تُنشر التغييرات تلقائيًا [#تُنشر-التغييرات-تلقائيًا]

لا يوجد زر حفظ. تُحفظ النصوص والمنزلقات بعد توقف قصير، أما المفاتيح والإعدادات المسبقة والخيارات فتُحفظ فورًا، ويظهر تلميح **تم الحفظ** بجانب عنصر التحكم. يكتب كل حفظ بيانات صف الوكيل ويحدّث عنصر التضمين (وأي صفحة مستضافة قديمة)، فيرى الزوار التغيير دون انتظار إعادة النشر. تحقق من ذلك في نافذة خاصة على عنصر تضمين فعلي.

يعتمد إخفاء الشارة أو إظهارها في باقتَي Operate وScale على آلية التحديث المباشر نفسها.

## استخدام الموقع مقابل الفاتح أو الداكن [#استخدام-الموقع-مقابل-الفاتح-أو-الداكن]

لدى **سمة الوكيل** ثلاثة خيارات:

| الخيار             | التأثير                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| **استخدام الموقع** | يتبع الوضع الفاتح أو الداكن لدى كل زائر (الصفحة المضيفة أولًا ثم نظام التشغيل). وهو الخيار الافتراضي. |
| **فاتح**           | يثبّت الدردشة والمكالمة المباشرة على لوحة الألوان الفاتحة.                                            |
| **داكن**           | يثبّت الدردشة والمكالمة المباشرة على لوحة الألوان الداكنة.                                            |

**استخدام الموقع** يقابل القيمة `auto`. يؤدي اختيار فاتح أو داكن إلى تثبيت الدردشة والمكالمة المباشرة معًا لجميع الزوار. عدّل لوحتي الألوان الفاتحة والداكنة كلًّا على حدة؛ فمفتاح المعاينة يغيّر فقط اللوحة التي تحرّرها.

في عنصر التضمين، يمكن للمُحمِّل (loader) أن يمرّر `data-theme="light"` أو `data-theme="dark"` لتجاوز الإعداد من جهة الصفحة المضيفة. راجع [نظرة عامة على التضمين](/ar/docs/embed/overview).

## الألوان والإعدادات المسبقة والخطوط [#الألوان-والإعدادات-المسبقة-والخطوط]

* **الإعدادات المسبقة** — Sharp وSoft وGlass وMinimal — تضبط الزوايا والظل والحدود والتأثير الزجاجي معًا.
* **اللون الأساسي** — فقاعات الزائر ولمسات المكالمة والإجراءات الرئيسية. يرث خيار **تلقائي (لون الموقع المميّز)** اللون المميّز للعلامة التجارية الذي جرى استخلاصه من الموقع واستُخدم للأداة.
* اضبط بدقة اللون الثانوي والخلفية وسطح اللوحة والزوايا والظل والحدود والتأثير الزجاجي والخط.
* يُطبَّق خيار **مطابقة الموقع** للخط عند تضمين الوكيل في موقع خارجي، بينما يُبقي **الافتراضي للأداة** على خط الأداة.

احرص على تباين كافٍ وعلى أن تبقى حالات التفاعل متمايزة. عاين المظهر على سطح المكتب وبعرض ضيق، بما في ذلك التسميات الكورية والإنجليزية.

## المكالمة المباشرة في معاينة العرض [#المكالمة-المباشرة-في-معاينة-العرض]

تعرض اللوحة بجانب تبويب **العرض** الأداة الفعلية، فتظهر الدردشة والمكالمة المباشرة بلوحة الألوان الفاتحة أو الداكنة المحددة وبالإطار نفسه الذي يراه الزائر في عنصر التضمين. ويظل التحدث إلى الوكيل هناك اختبارًا من المالك — راجع [الصوت والمكالمات المباشرة](/ar/docs/build/voice).

## شارة العلامة التجارية [#شارة-العلامة-التجارية]

إزالة الشارة متاحة في باقتَي Operate وScale. تحتفظ مواقع باقة Launch بشارة الإحالة الخاصة بـ Make Agent Fast. وتغيير إعداد الشارة (**إظهار شارة «Made with»**) يحدّث أيضًا عنصر التضمين المباشر دون إعادة نشر.

---

# الحجز عبر Cal.com

Source: /ar/docs/build/cal-com.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/change-actions&#x22;, label: &#x22;التأكيدات والإيصالات&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;المحادثات&#x22;, icon: &#x22;book&#x22; }
]"
/>

## ربط التقويم [#ربط-التقويم]

افتح **الوكيل ← الإجراءات ← Cal.com**. أدخل مفتاح Cal.com API يبدأ بـ `cal_`، ومعرّف نوع الحدث الرقمي الموجب، ومنطقة زمنية بصيغة IANA مثل `Asia/Seoul`. ثم اختر **حفظ الاتصال**. لكل وكيل اتصاله الخاص. يُشفَّر المفتاح على الخادم، ولا تعرض لوحة التحكم سوى آخر أربعة أحرف منه. اترك حقل المفتاح فارغًا عند تحديث اتصال قائم للإبقاء على المفتاح الحالي.

اختر **اختبار الاتصال** لقراءة ما يصل إلى ثلاثة أوقات متاحة قادمة خلال الأيام السبعة التالية باستخدام الإعدادات المُدخلة. لا يحفظ هذا الاختبار الاتصال ولا ينشئ حجزًا. قد يعني غياب الأوقات ببساطة أن نوع الحدث لا يتوفر له أي وقت متاح في هذه الفترة. إذا فشل الاختبار، فتحقق من المفتاح ونوع الحدث والجدول الزمني في Cal.com. يؤدي حذف الاتصال إلى إيقاف حجوزات Cal.com الجديدة، لكنه لا يلغي الحجوزات الموجودة.

المدفوعات خارج النطاق. يمثّل [Google Calendar](/ar/docs/build/google-calendar) خيارًا منفصلًا غير متاح للجميع بعد.

## من الأوقات المتاحة إلى الحجز [#من-الأوقات-المتاحة-إلى-الحجز]

1. يستدعي الوكيل `find_slots` للحصول على الأوقات المستقبلية المتاحة فعلًا. يعرض ما يصل إلى ثمانية أوقات بالمنطقة الزمنية المضبوطة. النطاق الافتراضي من اليوم حتى بعد سبعة أيام، والحد الأقصى لمدى التواريخ هو 14 يومًا. إذا كان هناك وقت متاح واحد فقط، يُعرض وحده.
2. يختار العميل وقتًا ويزوّد الوكيل باسمه وبريده الإلكتروني وملاحظة اختيارية. يتحقق الوكيل مجددًا من أن الوقت ما زال متاحًا وأنه عُرض في هذه المحادثة. تنتهي صلاحية عروض الأوقات بعد 15 دقيقة.
3. تعرض بطاقة التأكيد التاريخ والوقت والمنطقة الزمنية وبيانات الحاضر. يجب على العميل الضغط على **تأكيد**. لا يؤدي إرسال رسالة في المحادثة أو اختيار وقت وحده إلى إجراء أي حجز. تنتهي صلاحية الاقتراح بعد 15 دقيقة، ولا يحجز الوقت.
4. بعد التأكيد فقط يرسل المحوّل طلب الحجز إلى Cal.com. تتحول النتيجة `accepted` من Cal.com إلى `done`، مع معرّف UID للحجز كمرجع. أما `pending` أو `awaiting_host` فتبقى قيد الانتظار، ويتحول الرفض أو الإلغاء إلى حالة فشل.

لا تُتاح اقتراحات الحجز على قنوات المراسلة إلا في المحادثات الخاصة. لا تستدعي المحاكاة Cal.com ولا تنشئ حجزًا. وبدون اتصال Cal.com يظل مسار طلب الحجز الحالي متاحًا، لكنه لا يثبت وجود حجز فعلي في التقويم. يؤدي تغيير المفتاح أو نوع الحدث أو المنطقة الزمنية إلى إبطال هدف تنفيذ الاقتراح، لذا ابدأ من جديد بعد أي تغيير في الاتصال.

## إذا أُخذ الوقت أو كانت النتيجة غير مؤكدة [#إذا-أُخذ-الوقت-أو-كانت-النتيجة-غير-مؤكدة]

قد يحجز عميل آخر الوقت قبل اكتمال التأكيد. إذا لم يعد الوقت متاحًا، يُبلغ الوكيل بعدم توفره، وإذا رفضه Cal.com أثناء الإنشاء، يعرض الإيصال حالة الفشل. اطلب أوقاتًا جديدة وأكّد اقتراحًا جديدًا. لا يرفق إيصال الفشل خيارات جديدة تلقائيًا.

انتهاء مهلة الشبكة ليس دليلًا على الفشل ولا على النجاح. يعرض الإيصال نتيجة غير معروفة بينما تعيد الخدمة الفحص. لا تحتوي نقطة إنشاء الحجز في Cal.com على عقد موثّق لمفتاح عدم التكرار (idempotency key)، لذا يخزّن المحوّل معرّف التشغيل في `metadata.maf_run` ويبحث عن ذلك الحجز في جميع الحالات والصفحات قبل إعادة محاولة الإنشاء. ولا يسمح بحث غير مكتمل أبدًا بإرسال طلب إنشاء آخر. يقلل هذا خطر التكرار، لكنه ليس ضمانًا بالتنفيذ مرة واحدة بالضبط مدعومًا من المزوّد. وقبل إجراء حجز آخر بعد استنفاد المحاولات، تحقق من Cal.com.

تختلف موافقة المضيف في Cal.com عن موافقة المالك على إجراءات التغيير المخصصة. لا يحدّث هذا التكامل حجز Cal.com المعلّق تلقائيًا، فتحقق من حالته النهائية في Cal.com. يمكن لأداة الويب استطلاع إيصال التشغيل المخزّن، وتتلقى القنوات الخاصة المدعومة إيصالات متأخرة وفق نوافذ الخدمة الخاصة بها. راجع [تسليم الإيصالات](/ar/docs/build/change-actions#customer-confirmation-and-receipts).

## إصدارات API وفحوصات الإطلاق [#إصدارات-api-وفحوصات-الإطلاق]

يرسل المحوّل مصادقة Bearer وقيم `cal-api-version` التالية الخاصة بكل نقطة نهاية، وقد جرى التحقق منها مقابل الوثائق الرسمية بتاريخ **2026-10-13**:

| العملية               | الإصدار      | المرجع                                                                                                  |
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| قراءة الأوقات المتاحة | `2024-09-04` | [GET /v2/slots](https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type) |
| إنشاء حجز             | `2026-02-25` | [POST /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/create-a-booking)                    |
| مطابقة الحجز          | `2026-05-01` | [GET /v2/bookings](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings)                     |

قبل استخدامه مع العملاء، اختبر حجزًا مُتحكَّمًا به، وتحقق من UID في Cal.com، وجرّب وقتًا محجوزًا، وافحص الإيصالات على كل قناة تنوي استخدامها. لا يثبت نجاح اختبار الاتصال سوى قراءة الأوقات المتاحة، وليس حجزًا فعليًا ولا جاهزية للإنتاج.

---

# إجراءات التغيير

Source: /ar/docs/build/change-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/lookups&#x22;, label: &#x22;عمليات بحث للقراءة فقط&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/build/cal-com&#x22;, label: &#x22;الحجز عبر Cal.com&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: &#x22;العملاء المسجّلون للدخول&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep06" start="134" />

## تعريف إجراء تغيير [#تعريف-إجراء-تغيير]

استخدم إجراء التغيير لتحديث سجل في نظامك الخاص، مثل إلغاء طلب. افتح **الوكيل ← الإجراءات**، واضبط السر الخاص بالوكيل في **العملاء المسجّلون للدخول**، ثم أضف **إجراء تغيير**: اسمًا فريدًا، ووصفًا لوقت استخدامه، ونقطة نهاية HTTPS عامة، ومدخلات نصية معرَّفة. الاسم مثل `cancel_order` يصبح أداة النموذج `change_cancel_order`. تُحفظ التعديلات على الإجراءات الحالية تلقائيًا؛ انتظر ظهور مؤشر الحفظ.

أبقِ خيار **يتطلب عميلًا مسجّلًا للدخول** مفعّلًا للسجلات الخاصة. يجب أن تتحقق نقطة النهاية لديك مع ذلك من أن السجل المطلوب يعود إلى معرّف العميل الذي جرى التحقق منه. الاسم أو البريد الإلكتروني أو رقم الطلب المكتوب في المحادثة ليس دليلًا على الهوية. إذا عطّلت هذا الإعداد فقد تكون قيمة `customer` فارغة (null): اسمح فقط بالتغييرات المناسبة للزوار المجهولين. المدفوعات خارج نطاق هذه الميزة.

## اختيار موافقة المالك [#اختيار-موافقة-المالك]

تأكيد العميل مطلوب في كل الأوضاع:

| الوضع                       | بعد أن يؤكد العميل                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| بلا موافقة (`none`)         | التنفيذ دون قرار منفصل من المالك.                                                                                   |
| الموافقة دائمًا (`always`)  | انتظار المالك.                                                                                                      |
| عند تجاوز حد (`over_limit`) | الانتظار عندما يكون مدخل رقمي معرَّف أكبر تمامًا من الحد؛ المساواة لا تتطلب موافقة. يُرفض المدخل الرقمي غير الصالح. |

راجع الطلبات المنتظرة في **الوكيل ← الإجراءات ← الموافقات**. يمكن لمالك الموقع الموافقة أو الرفض. إذا كانت تنبيهات المالك الخاصة عبر Telegram مرتبطة، فسيتضمن التنبيه أيضًا زرَّي **موافقة / رفض**. لا يمكن استخدامهما إلا من المحادثة الخاصة للمالك المرتبط؛ ولا يمكن للنقرات المنتهية أو المكررة أن تنفّذ الإجراء مرة أخرى. تنتهي صلاحية الموافقة بعد 24 ساعة من تأكيد العميل. يتلقى العميل النتيجة، بما في ذلك الرفض أو انتهاء الصلاحية. تعرض عمليات التشغيل الأخيرة الحالة والطوابع الزمنية والمرجع ومعرّف العميل.

## ما تستقبله نقطة النهاية لديك [#ما-تستقبله-نقطة-النهاية-لديك]

لا يُرسل أي طلب عندما يقترح النموذج التغيير. بعد تأكيد العميل وأي موافقة مطلوبة من المالك، يرسل Make Agent Fast ما يلي:

```http
POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b
```

```json
{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

لا تتضمن قيمة `action` البادئة `change_`. يبقى المعرّفان ورأس مفتاح منع التكرار (idempotency) كما هي عند إعادة المحاولة. يحتوي `input` على سلاسل نصية معرَّفة ومقتطعة المسافات فقط؛ و`customer` إما null أو الكائن الذي جرى التحقق منه ويتضمن `id` و`email`/`name` الاختياريين.

استخدم [أداة التحقق من توقيع عمليات البحث](/ar/docs/build/lookups#verify-the-signature): HMAC-SHA256 باستخدام سر الوكيل على `"maf-webhook-v1:" + timestamp + "." + rawBody`، بحروف سداسية عشرية صغيرة تسبقها `v1=`. تحقق من البايتات الأصلية، وحداثة الطابع الزمني، والموقع/الإجراء المتوقعين، وملكية العميل قبل أي كتابة. **أزل التكرار لقيمة `x-maf-idempotency-key` بشكل ذري مع تغييرك واحتفظ بالنتيجة.** يجب أن يعيد الطلب المكرر النتيجة المحفوظة دون تغيير السجل مرة أخرى. لا يمكن للقفل على مستوى المنصة أن يحل محل إزالة التكرار في نظامك.

## إرجاع النتيجة [#إرجاع-النتيجة]

أرجع JSON بحالة 2xx يتضمن الحقل المطلوب `status` (`done` أو `pending` أو `failed`) والحقول الاختيارية `message` و`reference` و`card`:

```json
{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}
```

تتطلب بطاقة الحالة الاختيارية الحقلين `title` و`fields`؛ أما `kind: "status"` فاختياري. وتدعم `status: { label, tone }` و`reference` و`asOf` و`link: { label, url }`، كما في [عمليات البحث](/ar/docs/build/lookups#return-a-response). النبرات هي `neutral` أو `success` أو `warning` أو `danger`؛ ويجب أن تكون الروابط عناوين HTTPS آمنة. تُرفض حقول المخطط غير المعروفة. اجعل النص قصيرًا وبسيطًا. الحقل الخارجي `status` هو الذي يحدد النتيجة؛ ولا يمكن لصياغة البطاقة أن تحوّل نتيجة معلّقة إلى نجاح.

استخدم `done` فقط بعد اكتمال التغيير، و`pending` عندما لا تزال المعالجة جارية، و`failed` عند حدوث فشل معروف. تُعامل مهلات الانتظار وأخطاء الشبكة واستجابات 5xx والاستجابات غير الصالحة على أنها نتيجة غير مؤكدة (`unknown`). تعيد المطابقة المحاولة بعد دقيقة واحدة ثم بعد خمس دقائق، بحد أقصى ثلاث محاولات تنفيذ وبالمفتاح نفسه؛ وقد تؤخر جدولة قوائم الانتظار هذه الأوقات. تفشل استجابة HTTP 4xx دون إعادة محاولة. عند استنفاد حالات عدم اليقين يفشل التشغيل ويُبلَّغ المالك، لكن هذا لا يثبت أن نظامك لم يُجرِ أي تغيير. حقّق في الأمر قبل بدء تشغيل آخر. لا يؤدي `pending` إلى تنفيذ آخر.

## إرسال استدعاء نهائي موقَّع [#إرسال-استدعاء-نهائي-موقَّع]

عند حسم تشغيل في حالة `pending` أو `unknown`، أرسل بطلب POST استجابة نهائية إلى `https://makeagent.fast/api/agent/actions/RUN_ID/callback`. أرسل عقد الاستجابة نفسه مع `status: "done"` أو `"failed"`؛ ولا تُقبل `pending` هنا.

تحديث عقد الاستدعاء بتاريخ 2026-10-14: وقّع `maf-callback-v1:` + runId + `:` + timestamp + `.` + rawBody. إذا كان الجسم يتضمن `runId` فيجب أن يطابق معرّف التشغيل في المسار؛ وعدم التطابق يعيد 400. التوقيعات الخاصة بتشغيل آخر أو بالصيغة السابقة غير المرتبطة تعيد 403.

```js
import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);
```

استخدم سر الوكيل المحفوظ على خادمك ومعرّف التشغيل الذي استلمته في الطلب الأصلي. يستخدم الاستدعاء **`maf-callback-v1:`** وليس نطاق تسمية الطلب الصادر. يجب أن يكون فارق الطابع الزمني ضمن خمس دقائق. تعيد التوقيعات غير الصالحة 403؛ وتعيد الأجسام غير الصالحة 400؛ ويعيد التشغيل المنتهي أصلًا أو غير المتوافق 409. لا يؤدي الاستدعاء المكرر إلى استبدال النتيجة النهائية. بدّل هذا السر مع إعدادات الهوية وتوقيع نقطة النهاية لديك.

## تأكيد العميل والإيصالات [#تأكيد-العميل-والإيصالات]

يراجع العميل المدخلات بدقة ثم يضغط **تأكيد** أو **إلغاء** على الاقتراح. تنتهي صلاحية الاقتراح بعد 15 دقيقة؛ والاقتراح الجديد للإجراء/المحادثة نفسيهما يحل محل القديم. يستخدم التأكيد رمزًا مرتبطًا بذلك التشغيل والموقع والزائر. كتابة «نعم» أو النقر على بطاقة تأكيد عامة لا يفوّض بتنفيذ التغيير. أزرار وضع التجربة غير فعّالة ولا تستدعي نقطة النهاية لديك.

على الويب، تستعلم أداة الدردشة المفتوحة بشكل دوري عن الإيصالات غير النهائية، في البداية كل خمس ثوانٍ ثم كل 30 ثانية، لمدة تصل إلى 24 ساعة. قد يظهر الإيصال بحالة: تم الطلب، في انتظار المالك، قيد التشغيل، معلّق، جارٍ التحقق من نتيجة غير معروفة، تم، فشل، مرفوض، ملغى، أو منتهي الصلاحية. فقط `done` يؤكد الاكتمال.

تعمل اقتراحات القنوات **في المحادثات الخاصة فقط**، وليس في المجموعات أو القنوات العامة. تستخدم الإيصالات المتأخرة صندوق الإرسال الدائم (outbox): تُدعم رسائل Telegram الخاصة العادية مع البوت؛ أما WhatsApp وMessenger وInstagram وTelegram Business فتتطلب رسالة واردة مسجّلة خلال 24 ساعة، ويُعاد التحقق منها وقت الإرسال. التسليم المتأخر غير متاح لاستعلامات الضيوف في Telegram ولـ Discord وKakaoTalk. قد تمنع النوافذ المغلقة والاتصالات المعطّلة التسليم؛ ومع ذلك يسجل سجل التشغيل النتيجة.

## الحدود والاختبار [#الحدود-والاختبار]

| العنصر                                             | الحد                                                                                                    |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| إجراءات التغيير                                    | 5 لكل وكيل؛ الأسماء فريدة عبر إجراءات التغيير وعمليات البحث                                             |
| الأسماء                                            | الإجراء: `^[a-z][a-z0-9_]{2,39}$`؛ المدخل: `^[a-z][a-z0-9_]{1,31}$`؛ أسماء الإجراءات المحجوزة غير متاحة |
| الأوصاف                                            | 300 حرف                                                                                                 |
| المدخلات                                           | 3 سلاسل نصية معرَّفة، بحد أقصى 200 حرف لكل منها                                                         |
| نقطة النهاية                                       | HTTPS عامة، حتى 500 حرف، دون بيانات اعتماد في عنوان URL أو عناوين خاصة أو إعادة توجيه                   |
| مهلة التنفيذ / الاستجابة / جسم الاستدعاء           | 8 ثوانٍ / 32 KiB / 32 KiB                                                                               |
| عنوان بطاقة الحالة / تسمية الحقل / القيمة / الحقول | 80 / 40 / 200 حرف / 8 حقول                                                                              |
| انتهاء صلاحية الاقتراح / الموافقة                  | 15 دقيقة / 24 ساعة بعد التأكيد                                                                          |

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

---

# إنشاء وكيل

Source: /ar/docs/build/create-agent.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/persona&#x22;, label: &#x22;الشخصية&#x22;, icon: &#x22;account&#x22; },
{ href: &#x22;/ar/docs/build/knowledge&#x22;, label: &#x22;المعرفة&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/build/voice&#x22;, label: &#x22;الصوت&#x22;, icon: &#x22;voice&#x22; },
{ href: &#x22;/ar/docs/build/appearance&#x22;, label: &#x22;المظهر&#x22;, icon: &#x22;spark&#x22; }
]"
/>

يبدأ الوكيل الأول من **رابط موقع (URL)**. نزحف على الصفحات العامة التي يمكننا الوصول إليها، ونُعدّ مسودة وكيل (بما في ذلك نمط الأداة المضمّنة المستمد من تلك المعلومات)، ونُبقيه بعيدًا عن موقعك حتى الخطوة الأخيرة من الإعداد الأولي. ميزة الإنشاء عبر المحادثة معطّلة. ولا توجد ميزة لإنشاء موقع أو أداة لبناء الأقسام.

<TutorialVideo episode="ep01" start="14" />

## الصق الرابط [#الصق-الرابط]

في الصفحة الرئيسية، الصق الرابط ثم تابع. يحتفظ التسجيل وتسجيل الدخول بالمعامل `next=/onboarding/launch?url=…`، فلا يُطلب منك لصقه مرة أخرى. تتيح الصفحة `/try` للزوار لصق رابط والتحدث مع مسودة تحمل علامة مائية (نصية فقط وبحدود معينة) قبل المطالبة بها عند التسجيل.

إذا كانت لديك مواقع بالفعل، فإن لصق رابط ما ينشئ مسودة **جديدة** غير منشورة. أما إذا كان الرابط نفسه قيد المعالجة، فيُستأنف بدلًا من تكراره. ولا يُعاد استخدام موقع اكتمل في أول تشغيل.

لا تلصق كلمات مرور أو بيانات عملاء خاصة أو رموز موصّلات (connector) في حقل الرابط.

## انتظر في شاشة الإنشاء [#انتظر-في-شاشة-الإنشاء]

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

| الخطوة              | ما تفعله                                                            |
| ------------------- | ------------------------------------------------------------------- |
| **قراءة الموقع**    | تجلب الصفحات العامة من الرابط                                       |
| **بناء الوكيل**     | تركّب الوكيل ونمط الأداة المضمّنة من المعلومات التي جرى الزحف إليها |
| **اختبار الإجابات** | تُجري اختبارًا ذاتيًا مقابل تلك المعرفة                             |

يستغرق الانتظار عادةً بضع ثوانٍ، وقد يصل إلى دقيقة تقريبًا للمواقع الأكبر. وإذا كان الزحف محدودًا، تعتمد المسودة على ما عُثر عليه. ويمكنك إضافة المصادر بعد المراجعة.

لا تُنشر المسودة تلقائيًا أبدًا. ولا تحصل الوكلاء الجدد على صفحة تسويقية مستضافة.

## تعرّف على الوكيل وفعّله [#تعرّف-على-الوكيل-وفعّله]

بعد بناء المسودة، يعرض الإعداد الأولي شاشتين إضافيتين:

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

بعد ذلك يفتح الوكيل على صفحة **الوكيل**، وهي أول عنصر في الشريط الجانبي للوكيل: علامات التبويب **نظرة عامة** و**العرض** و**الصوت** و**الإجراءات** إلى جانب لوحة حيّة تعرض الأداة الحقيقية في الزاوية التي اخترتها. اسأله ما قد يسأله العميل هناك. في **نظرة عامة**، يقيّم **فحص الإجابات** ← **إجراء فحص** الإجابات مقابل معرفتك.

التحدث إلى الوكيل في لوحة التحكم هو اختبار من المالك (Owner). فهو لا يُفعَّل للجمهور ولا يُحتسب ضمن التفعيل.

لإضافة الأداة إلى موقعك لاحقًا، افتح **فعّله** ← **أداة الموقع** في صفحة الوكيل. وإذا لم تكن الأداة مفعّلة بعد، فاختر **تفعيل التضمين**. وبعد تفعيلها، تعرض الورقة نفسها كود التثبيت ومفتاح **اعرضه على موقعي** و**عناوين المواقع المسموح بها**. ويمكنك إخفاء الأداة في أي وقت بهذا المفتاح أو من بطاقة **على موقعك** في تبويب **نظرة عامة**.

## التفعيل [#التفعيل]

بعد التفعيل، أضف كود التضمين أو اربط قناة (Channel). يُعدّ الموقع **مفعّلًا** عند أول محادثة لزائر أو أول عميل محتمل (Lead) يتم التقاطه. ولا تُحتسب أبدًا محادثات الاختبار من لوحة التحكم.

## التعديل بعد المسودة الأولى [#التعديل-بعد-المسودة-الأولى]

لا توجد ميزة إنشاء عبر المحادثة. بعد المراجعة، حدّث ما يلي:

* التعليمات في تبويب **نظرة عامة** بصفحة الوكيل، و**الصوت** و**العرض** في تبويبيهما المجاورين.
* **المعرفة** في صفحتها الخاصة ضمن الشريط الجانبي للوكيل.
* تُحفظ تغييرات **العرض** تلقائيًا وتُحدّث التضمين المباشر دون إعادة نشر.

## البدء دون رابط موقع [#البدء-دون-رابط-موقع]

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

---

# الأسئلة الشائعة والمنتجات

Source: /ar/docs/build/faqs-products.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;الأسئلة الشائعة&#x22;, icon: &#x22;book&#x22; }, { label: &#x22;المنتجات&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;المعرفة&#x22;, icon: &#x22;link&#x22; }]" />

## استخدم الأسئلة الشائعة للإجابات المعتمدة [#استخدم-الأسئلة-الشائعة-للإجابات-المعتمدة]

أنشئ سؤالًا شائعًا واحدًا لكل غرض من أغراض الزائر. اكتب السؤال بالصياغة التي يستخدمها العملاء، واجعل الإجابة مكتملة بحيث لا تعتمد على سؤال شائع آخر.

## استخدم المنتجات لمعلومات الكتالوج [#استخدم-المنتجات-لمعلومات-الكتالوج]

تناسب المنتجات العروض المسمّاة التي تتضمن حقولًا مثل الوصف أو السعر أو التوفر أو الرابط. حافظ على تحديث المعلومات المتعلقة بالمعاملات، وتجنّب التعهد بتوفر المخزون أو بالتوصيل ما لم يكن مصدرك يُحدَّث بشكل موثوق.

## تجنّب التكرار [#تجنّب-التكرار]

لا تحتفظ بالسعر نفسه في ملاحظة وسؤال شائع وقسم صفحة وسجل منتج في آن واحد. اختر مصدرًا معتمدًا واحدًا، ثم اربط به أو أشِر إليه في المواضع الأخرى.

## تحقّق من سلوك الوكيل أمام العملاء [#تحقّق-من-سلوك-الوكيل-أمام-العملاء]

بعد إجراء أي تغيير، اطرح على الوكيل السؤال الشائع بصياغات متعددة، وتأكد من صحة رابط المنتج وسعره.

---

# المتابعات والتذكيرات

Source: /ar/docs/build/follow-ups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/page-actions&#x22;, label: &#x22;إجراءات الصفحة&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/build/lookups&#x22;, label: &#x22;عمليات البحث&#x22;, icon: &#x22;book&#x22; }
]"
/>

## قدّم المساعدة في اللحظة المناسبة [#قدّم-المساعدة-في-اللحظة-المناسبة]

افتح **الوكيل ← الإجراءات ← المتابعات**. أضف ما يصل إلى خمس قواعد لعرض صفحة، أو زائر خامل، أو نيّة المغادرة، أو خطأ في نموذج، أو حدث مخصص. اختر نمط مسار، وتأخيرًا اختياريًا، ورسالة لا تتجاوز 200 حرف، وما يصل إلى ثلاثة ردود سريعة. تُحفظ الإعدادات تلقائيًا. تعرض المعاينة الرسالة دون التواصل مع أي عميل ودون إضافة بيانات إلى التجربة.

استخدم `/pricing` لمسار واحد، و`/products/*` لجزء واحد من المسار، و`/products/**` للمسارات المتداخلة. تُستثنى معاملات الاستعلام والأجزاء بعد علامة التجزئة. التأخير الافتراضي للخمول هو 30 ثانية، وفترة الانتظار الافتراضية بين المحفّزات هي سبعة أيام. لن يقاطع المحفّز استلام إنسان للمحادثة أو محادثة نشطة مفتوحة، ولن يتكرر في الجلسة نفسها، ولن يظهر من جديد بعد إغلاقه في تلك الجلسة.

يبلّغ كود التضمين عن مرات عرض الصفحات والخمول ونيّة المغادرة. يمكن للمطوّر لديك الإبلاغ عن أحداث مخصصة باستخدام `MakeAgentFast.track`؛ راجع [إجراءات الصفحة](/ar/docs/build/page-actions). يكون الإبلاغ التلقائي عن أخطاء النماذج متوقفًا ما لم يستخدم كود التضمين `data-auto-form-error="true"` أو `MakeAgentFastSettings.autoFormError = true`. ويبلّغ عن معرّف النموذج فقط، ولا يبلّغ أبدًا عن قيم الحقول.

## اقرأ نتائج المجموعة الضابطة [#اقرأ-نتائج-المجموعة-الضابطة]

افتراضيًا، يُسنَد 10% من الزوار المؤهلين إلى مجموعة ضابطة ثابتة ولا يرون أي رسالة. يرتبط الإسناد بالزائر والقاعدة؛ ولا تؤدي الزيارات المتكررة إلى تضخيم حجم العيّنة. تقارن لوحة التحكم معدلات التحويل بين الزوار المؤهلين في مجموعة الرسالة والمجموعة الضابطة، وتعرض الارتفاع المطلق بالنقاط المئوية.

التحويل هو عميل محتمل أو حجز أو إجراء مكتمل أو بحث ناجح مسجّل خلال 24 ساعة من تعرّض مؤهل للرسالة. أما فتح الرسالة أو الرد عليها فيُعرضان بشكل منفصل. ولا يمكن للأحداث التي يبلّغ عنها المتصفح أن تعلن عن تحويلات. وإذا كان عدد الزوار أقل من 50 في كل مجموعة، تعرض لوحة التحكم أن البيانات غير كافية؛ وعند هذا الحد أو فوقه تعرض فاصل ثقة بسيطًا بنسبة 95%. ولا تُعدّ الفروق الصغيرة دليلًا على أن الرسالة تسببت في مبيعات أكثر.

## أبلغ العميل عند حدوث تغيير [#أبلغ-العميل-عند-حدوث-تغيير]

يمكن للعملاء أن يطلبوا: «أخبرني عندما يتوفر موعد» أو «دعني أعرف عندما تتغير حالة طلبي». تراقب المراقبة توفر التقويم المتصل، أو حقلًا أو حالة في [عملية بحث](/ar/docs/build/lookups) مهيأة. تتطلب مراقبات البحث عميلًا مسجّلًا الدخول وتم التحقق منه. ولا تراقب صفحات عشوائية ولا تجدول تذكيرات متكررة.

يقترح الوكيل مراقبة مع وجهتها وتاريخ انتهائها. يجب على العميل النقر على زر التأكيد خلال 15 دقيقة. كما يدخل زوار الموقع والمكالمات المباشرة بريدًا إلكترونيًا ويحددون خانة الموافقة على البريد الإلكتروني على الشاشة؛ فكتابة «نعم» أو قولها لا تكفي. يتضمن البريد الإلكتروني إشعارًا عامًا ورابط عودة قصير الصلاحية. لا يسجّل هذا الرابط دخول المستلم ولا يمنحه إمكانية الوصول إلى سجلات العملاء.

يمكن لكل زائر أن يمتلك ثلاث مراقبات نشطة أو معلّقة، بحد أقصى 50 لكل وكيل، ومدة قصوى 14 يومًا. تبدأ الفحوصات بعد 15 دقيقة، ثم تتباعد لتصبح كل ساعة ثم كل ست ساعات. ترسل كل مراقبة محاولة إشعار واحدة ثم تتوقف. يمكن الإلغاء عبر عناصر التحكم في المراقبة أو من قائمة المتابعات لدى المالك. وقد يؤدي تغيير إعدادات البحث أو التقويم الأساسية إلى إيقاف المراقبة. ولا يُعاد إرسال إشعار غير مؤكد التسليم تلقائيًا.

## تابع في المحادثات واسألك عند التعثر [#تابع-في-المحادثات-واسألك-عند-التعثر]

افتح **الوكيل ← الإجراءات ← المتابعات ← متابعات المحادثات**. ينطبق هذان المفتاحان على محادثات Telegram وWhatsApp وMessenger وInstagram.

يكون خيار **المتابعة عندما يتوقف العميل عن الرد** مفعّلًا افتراضيًا لوكلاء المبيعات ومعطّلًا لأنواع الوكلاء الأخرى. عندما يتوقف العميل عن الرد بعد إجابة، يعيد الوكيل قراءة المحادثة ثم يرسل رسالة قصيرة واحدة، أو ينتظر قليلًا أطول، أو يترك العميل وشأنه. يتجه وكيل المبيعات نحو إتمام الشراء، ويتحقق وكيل الخدمة من حل المشكلة، ويقترح وكيل الحجوزات موعدًا. ويعتمد فقط على المعرفة التي اعتمدتها وعلى المحادثة، ويتوقف عندما يرد العميل أو يرفض أو يطلب عدم مراسلته. تقبل قنوات Meta الرسائل الآلية خلال 24 ساعة فقط من آخر رسالة للعميل، لذلك تصل المتابعة هناك خلال ذلك اليوم؛ أما محادثة بوت Telegram فيمكن أن تتلقى ما يصل إلى متابعتين على مدى عدة أيام. تُحتسب كل متابعة كما يُحتسب الرد.

يكون خيار **اسألني عندما لا يستطيع الوكيل الإجابة** مفعّلًا افتراضيًا. فبدلًا من طلب البريد الإلكتروني، يخبر الوكيل العميل بأنه يستفسر من الفريق، وينبّهك برابط إلى المحادثة. ردّ هناك، أو احفظ الإجابة في المعرفة، وسيرسلها الوكيل إلى العميل بلغته. تقبل Instagram وMessenger إجابتك خلال 24 ساعة من آخر رسالة للعميل، أو حتى 7 أيام بمجرد حصول تطبيق Meta الخاص بك على إذن Human Agent.

## التسليم والتوفر [#التسليم-والتوفر]

| الوجهة                                | الحد الحالي                                                                                                            |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| الموقع الإلكتروني / المكالمة المباشرة | بريد إلكتروني بموافقة صريحة؛ لا توجد إشعارات دفع في الخلفية من الودجت                                                  |
| Telegram                              | محادثة بوت خاصة قائمة؛ وتتطلب محادثة Business الخاصة أيضًا نافذة 24 ساعة مفتوحة                                        |
| WhatsApp                              | رسائل حرة خلال 24 ساعة من آخر رسالة واردة من العميل؛ وخارجها يلزم قالب خدمي (utility) معتمد                            |
| Messenger / Instagram                 | فقط خلال 24 ساعة من آخر رسالة واردة من العميل                                                                          |
| Discord / KakaoTalk                   | وسيلة نقل المراقبة غير متاحة؛ كما تشترط سياسة Kakao قالب AlimTalk وتستثني الفترة من 20:50 إلى 08:00 بتوقيت كوريا (KST) |

تُفحص قيود القنوات مرة أخرى عند التسليم. ولا تتجاوزها المراقبة التي تمت الموافقة عليها ولا تضمن وصول الرسالة.

---

# Google Calendar

Source: /ar/docs/build/google-calendar.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/cal-com&#x22;, label: &#x22;Cal.com&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/build/follow-ups&#x22;, label: &#x22;تنبيهات التوفر&#x22;, icon: &#x22;book&#x22; }
]"
/>

## حالة التوفر [#حالة-التوفر]

**Google Calendar غير متاح للجميع بعد.** إلى أن يتم تفعيله، يعرض **الوكيل ← الإجراءات ← Google Calendar** عبارة «قريبًا»، ويظل الربط غير متاح؛ ولا يمكن لإعداد في الوكيل تفعيله. يبقى [Cal.com](/ar/docs/build/cal-com) خيارًا منفصلًا.

## ربط تقويم [#ربط-تقويم]

عند التفعيل، افتح لوحة Google Calendar واختر **ربط**. سجّل الدخول إلى Google وراجع الأذونات المطلوبة لأحداث التقويم ولتوفر الأوقات (مشغول/متاح). هذا الربط منفصل عن تسجيل الدخول إلى Make Agent Fast. يخزّن الخادم رمز التحديث (refresh token) مشفّرًا، ولا تتلقاه لوحة التحكم ولا الوكيل.

النطاقات المطلوبة هي `calendar.events` و`calendar.freebusy` إضافةً إلى النطاقين غير الحساسين `openid` و`email`. تتطلب دالة الاستدعاء (callback) بريدًا إلكترونيًا موثّقًا وتخزّنه مشفّرًا لكي تُطابق `primary` معرّف التقويم نفسه المكتوب بالبريد الإلكتروني الصريح. لا يُطلب أي نطاق للملف الشخصي. يجب على أصحاب الاتصالات الأقدم التي لا تحتوي على بريد إلكتروني موثّق قطع الاتصال ثم إعادة الربط قبل الحجز.

يستخدم الوكيل مزوّد تقويم واحدًا في كل مرة. اقطع اتصال المزوّد الحالي قبل التبديل. اختر معرّف التقويم (`primary` للتقويم الأساسي للحساب المتصل) ومنطقته الزمنية بصيغة IANA، مثل `Asia/Seoul`. يجب أن يكون التقويم المشترك متاحًا بأذونات الحساب المتصل. يؤدي قطع الاتصال إلى إلغاء منح Google وإزالة الربط، ولا يلغي الأحداث الموجودة.

## تحديد ساعات العمل [#تحديد-ساعات-العمل]

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

| الإعداد                     | النطاق المقبول                        |
| --------------------------- | ------------------------------------- |
| مدة الموعد                  | 5–240 دقيقة                           |
| الفاصل حول الأحداث المشغولة | 0–120 دقيقة                           |
| الحد الأدنى للإشعار المسبق  | 0–43,200 دقيقة                        |
| نطاق الحجز المستقبلي        | 1–90 يومًا                            |
| نوافذ العمل                 | حتى 28 نافذة غير متداخلة خلال الأسبوع |

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

## من التوفر إلى الحجز [#من-التوفر-إلى-الحجز]

يستخدم الوكيل مسار `find_slots` و`book_slot` نفسه المستخدم مع Cal.com: يعرض حتى ثمانية أوقات متاحة، ويجمع الاسم والبريد الإلكتروني وملاحظة اختيارية، ثم يعيد التحقق من الموعد المختار، ثم يعرض بطاقة تأكيد. تنتهي صلاحية العروض والمقترحات بعد 15 دقيقة، ولا يحجز أيٌّ منهما الموعد. ولا يخوّل الحجز إلا نقر العميل على الزر. أما قول «نعم» شفهيًا أثناء مكالمة مباشرة فلا يمكنه إتمام الحجز.

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

لتلقي إشعار عند توفر وقت جديد، استخدم [المراقبة](/ar/docs/build/follow-ups) بموافقة العميل. قبل الاستخدام الفعلي مع العملاء، تحقق من حجز حقيقي ودعوة في Google، وجرّب موعدًا محجوزًا، وتحقق من قطع الاتصال وإعادة الربط ومن قناة المراسلة المقصودة.

---

# مصادر المعرفة

Source: /ar/docs/build/knowledge.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;اللصق&#x22;, description: &#x22;حقائق وسياسات يكتبها المالك بحد أقصى 200,000 حرف.&#x22; },
{ icon: &#x22;link&#x22;, title: &#x22;عناوين URL والخلاصات&#x22;, description: &#x22;اجلب صفحات عامة أو محتوى موقع إلكتروني يتجدد بانتظام.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;الملفات&#x22;, description: &#x22;استخراج النص من ملفات PDF وWord وExcel وPowerPoint وHWP وOpenDocument وRTF والملفات النصية.&#x22; },
{ icon: &#x22;voice&#x22;, title: &#x22;الوسائط&#x22;, description: &#x22;استخدم ترجمات YouTube المتاحة أو انسخ نصيًا الصوت المدعوم للبودكاست.&#x22; }
]"
/>

توفّر المعرفة للوكيل مادة مصدرية قابلة للاسترجاع. عند إضافة مصدر، يتم استخراج النص العادي منه وتقسيمه إلى مقاطع وإنشاء التضمينات (embeddings) وربط هذه المقاطع بالموقع الحالي. وعند الإجابة، يسترجع الوكيل المقاطع ذات الصلة بدلًا من تلقي جميع المصادر في كل طلب.

<TutorialVideo episode="ep01" start="168" />

## اختر نوع المصدر المناسب [#اختر-نوع-المصدر-المناسب]

| المصدر          | الأنسب لـ                                                                                                                                                                                                       | السلوك المهم                                                                                                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **لصق نص**      | السياسات وتفاصيل الاتصال والملاحظات الداخلية القصيرة                                                                                                                                                            | من 5 إلى 200,000 حرف؛ دون تحديث تلقائي                                                                                                                                       |
| **من URL**      | الصفحات العامة التي تُدار في مكان آخر                                                                                                                                                                           | صفحة واحدة افتراضيًا؛ ويمكن اختياريًا زحف 5 أو 10 أو 20 أو 40 صفحة من الموقع نفسه                                                                                            |
| **رفع ملف**     | PDF وWord (`.docx` و`.doc`) وExcel (`.xlsx` و`.xls`) وPowerPoint (`.pptx`) وملفات Hancom بصيغتي `.hwp` و`.hwpx` وOpenDocument (`.odt` و`.ods` و`.odp`) و`.rtf` و`.txt` و`.md` و`.csv` و`.tsv` و`.json` و`.html` | الحد الأقصى 20 ميغابايت؛ تُرفض الملفات المحمية بكلمة مرور والملفات التي تحتوي على وحدات ماكرو؛ ملفات PDF الممسوحة ضوئيًا التي تتكوّن من صور فقط لا تحتوي على نص قابل للتحديد |
| **YouTube**     | مقاطع الفيديو العامة ذات المحتوى المنطوق المفيد                                                                                                                                                                 | في خطة Operate أو Scale. يجرّب الترجمات أولًا، ثم النسخ النصي إن كان متاحًا؛ بأفضل جهد ممكن                                                                                  |
| **بودكاست**     | عنوان URL عام لصوت حلقة أو خلاصة مدعومة                                                                                                                                                                         | في خطة Operate أو Scale. يتطلب صوتًا يمكن جلبه ومزوّد نسخ نصي متاحًا                                                                                                         |
| **مدونة / RSS** | تحديثات المدونات أو البودكاست العامة عبر RSS/Atom                                                                                                                                                               | في خطة Operate أو Scale. يستخرج عناصر الخلاصة المتاحة كنص؛ بأفضل جهد ممكن                                                                                                    |

استخدم **الأسئلة الشائعة والمنتجات** للأسئلة والأجوبة المتوقعة أو حقول الكتالوج بدلًا من دفنها داخل مستند طويل. راجع [الأسئلة الشائعة والمنتجات](/ar/docs/build/faqs-products).

## إضافة مصدر [#إضافة-مصدر]

1. افتح صفحة **المعرفة** الخاصة بالوكيل من الشريط الجانبي للوكيل، ثم اختر **إضافة مصدر**.
2. اختر **لصق نص** أو **من URL** أو **رفع ملف**. تجد **YouTube** و**بودكاست** و**مدونة / RSS** ضمن **أنواع مصادر أخرى**، وهي تتطلب خطة Operate أو Scale؛ وفي خطة Launch تظهر عليها أيقونة قفل.
3. أدخل المحتوى أو اختر ملفًا.
4. بالنسبة إلى **من URL**، اختر **عدد الصفحات المراد زحفها** (1 أو 5 أو 10 أو 20 أو 40). وبالنسبة إلى المصادر المجلوبة، يمكنك اختياريًا ضبط **التحديث التلقائي** على **يوميًا** أو **أسبوعيًا** أو **أبدًا**.
5. اختر **إضافة إلى المعرفة** وانتظر ظهور النتيجة التي تعرض عدد المقاطع المفهرسة.
6. اطرح سؤالًا لا توجد إجابته إلا في المصدر الجديد.

يستهلك استيعاب المعرفة رصيدًا من الاعتمادات (Credits) لأن مقاطع المصدر يتم تضمينها. ويُرفض الاستيعاب إذا لم يكن لدى مساحة العمل وصول نشط أو رصيد صالح للاستخدام.

## زحف الصفحات العامة بأمان [#زحف-الصفحات-العامة-بأمان]

يقبل الزاحف المحتوى العام عبر HTTP/HTTPS ويحظر الوجهات غير الآمنة في الشبكات الخاصة. ابدأ بصفحة أساسية واحدة. لا تزد عدد الصفحات إلا عندما تكون الصفحات المرتبطة جزءًا من مجموعة المعلومات المفيدة نفسها؛ فقد يضيف الزحف الأكبر عناصر تنقّل ونصوصًا قانونية نمطية ومحتوى مكررًا أو أرشيفات قديمة تُضعف جودة الاسترجاع.

العدد المحدد هو حد أقصى وليس وعدًا. فقد يقلّل عدد الصفحات المجلوبة كلٌّ من سلوك ملف robots والمصادقة والعرض من جهة العميل فقط وعمليات إعادة التوجيه ونوع المحتوى وحجم الاستجابة وبنية الروابط. ويُحدَّد حجم استجابة الصفحة بحد أقصى 5 ميغابايت ويجب أن تحتوي على نص قابل للاستخراج بقدر كافٍ.

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

## استخدام الملفات والوسائط [#استخدام-الملفات-والوسائط]

يجب أن تحتوي الملفات المرفوعة على نص قابل للاستخراج. لا يتم إجراء OCR على ملف PDF ممسوح ضوئيًا يتكوّن من صور فقط؛ حوِّله إلى نص قابل للبحث قبل الرفع. تُقرأ جداول البيانات ورقةً ورقة، وتحتفظ صفوف الجداول بخلاياها معًا (`Coffee | 3000`)؛ أما التخطيطات الأخرى فتُسطَّح بترتيب القراءة، لذا اجعل الجداول بسيطة. أزل كلمة المرور من المستند قبل رفعه، واحفظ ملفات Office التي تحتوي على وحدات ماكرو (`.docm` و`.xlsm` و`.pptm`) أولًا كملفات `.docx` أو `.xlsx` أو `.pptx` عادية. ويُرفض أي ملف لا يطابق محتواه امتداده.

يفضّل استيعاب YouTube مسار الترجمة المتاح. وإذا لم تتوفر الترجمات، فإن النسخ النصي يعتمد على المزوّد والشبكة. يجب أن يكون صوت البودكاست قابلًا للجلب علنًا. وتعتمد نتائج الخلاصات على مقدار نص المقالات أو الحلقات الذي تعرضه الخلاصة. بعد أي استيراد للوسائط، افحص عنوان المصدر وعدد المقاطع واختبر حقيقة محددة بدلًا من افتراض أنه تم التقاط التسجيل بالكامل.

## تخطيط التحديث والاستبدال [#تخطيط-التحديث-والاستبدال]

تتوفر الجداول اليومية والأسبوعية لمصادر URL وYouTube والبودكاست والخلاصات. يعيد النظام جلب أصل المصدر المحفوظ ويستبدل مقاطعه القابلة للاسترجاع عند نجاح الزحف المجدول. تعرض قائمة المصادر وتيرة التحديث ووقت آخر تحديث.

مصادر اللصق والرفع هي لقطات ثابتة. ولتصحيح أحدها أو استبداله، احذفه وأضف المحتوى المحدَّث. يؤدي حذف المصدر إلى إزالة مقاطعه من الاسترجاع المستقبلي؛ لكنه لا يعدّل الرسائل السابقة التي اقتبست النسخة القديمة أو لخّصتها.

اعتمد جهة مسؤولة واحدة وواضحة عن الأسعار والسياسات والجداول الزمنية. فإذا تعارض مصدران نشطان، فقد يُظهر الاسترجاع أيًّا من العبارتين. أزل النسخ التي حلّ محلها غيرها بدلًا من إضافة نسخ «جديدة» بجانبها.

## اكتب محتوى يمكن للوكيل استرجاعه [#اكتب-محتوى-يمكن-للوكيل-استرجاعه]

* اذكر الموضوع في كل قسم: «سياسة إلغاء خطة Pro» أسهل استرجاعًا من «مزيد من التفاصيل».
* ضع الإجابة بلغة واضحة قرب العنوان ذي الصلة.
* أدرج الوحدات والعملة والمنطقة الزمنية وتاريخ السريان والاستثناءات حيثما كانت مهمة.
* استخدم عناوين URL أساسية ثابتة وأسماء ملفات وصفية.
* افصل المعلومات العامة عن التعليمات الداخلية أو السجلات الخاصة.
* أبقِ سلوك الشخصية في [الشخصية والتعليمات](/ar/docs/build/persona)، وليس داخل المواد المصدرية الواقعية.

## اختبار الإجابات المستندة إلى المصادر [#اختبار-الإجابات-المستندة-إلى-المصادر]

أنشئ مجموعة قبول صغيرة قبل النشر:

1. سؤال مباشر تكون إجابته صريحة في المصدر.
2. صياغة بديلة للسؤال تستخدم كلمات مختلفة.
3. سؤال حدّي لا يجيب عنه المصدر.
4. حقيقة تغيّرت مؤخرًا.
5. صيغة بلغة مختلفة لكل لغة مضبوطة للوكيل.

النتيجة الصحيحة ليست دائمًا إجابة واثقة. فعندما يفتقر المصدر إلى المعلومة، ينبغي أن يتبع الوكيل تعليمات الاحتياط/التصعيد بدلًا من اختلاق إجابة. افحص **المحادثات** بعد الإطلاق بحثًا عن الأسئلة غير المُجاب عنها المتكررة، وحوّل الإجابات المؤكدة إلى مصدر أو إلى أسئلة شائعة منظّمة.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                          | ما يجب فحصه                                                                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| يُبلغ URL بعدم وجود نص قابل للاستخدام            | الوصول العام ونوع المحتوى المدعوم والنص المعروض من الخادم ووجهة إعادة التوجيه وحجم الصفحة                                      |
| يُبلغ PDF بعدم وجود نص قابل للتحديد              | هل هو ممسوح ضوئيًا؛ طبّق عليه OCR أو صدّره إلى PDF قابل للبحث أو ملف نصي                                                       |
| رُفض الملف لأنه محمي بكلمة مرور أو لا يطابق نوعه | أزل كلمة المرور، ثم احفظ الملف مجددًا بصيغته الحقيقية بدلًا من إعادة تسميته؛ واحفظ ملفات Office التي تحتوي على ماكرو دون ماكرو |
| فشل استيراد YouTube/البودكاست                    | عنوان URL العام وتوفر الترجمات/الصوت ومفتاح مزوّد النسخ النصي وقيود الجلب                                                      |
| يتم تجاهل معلومة صحيحة                           | نتيجة المعالجة والصياغة والمصادر المتعارضة وعمر المصدر ونص سؤال الاختبار بدقته                                                 |
| يكشف الوكيل أكثر مما ينبغي                       | أزل المصدر الخاص فورًا وشدّد حدود الشخصية والوصول إلى الحساب                                                                   |
| تستمر إجابة قديمة                                | احذف المصدر القديم أو استبدله، وانتظر إعادة الفهرسة، وابدأ محادثة اختبار جديدة                                                 |

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

---

# عمليات البحث

Source: /ar/docs/build/lookups.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/security&#x22;, label: &#x22;العملاء المسجّلون للدخول&#x22;, icon: &#x22;shield&#x22; },
{ href: &#x22;/ar/docs/build/knowledge&#x22;, label: &#x22;مصادر المعرفة&#x22;, icon: &#x22;book&#x22; }
]"
/>

## متى تستخدم عملية البحث [#متى-تستخدم-عملية-البحث]

استخدم عملية البحث للاطلاع على حالة الطلب الحالية أو حجز قائم أو سجل حساب العميل. أبقِ السياسات الثابتة ومعلومات المنتجات في [المعرفة](/ar/docs/build/knowledge). تقرأ عملية البحث من نظامك ولا يجوز لها أن تخصم مبلغًا أو تُلغي أو تحجز أو تُغيّر أي سجل بأي شكل آخر. أما بطاقات الاختيار والتأكيد العامة فترسل رسالة الزائر فقط. للكتابة المؤكَّدة استخدم [إجراءات التغيير](/ar/docs/build/change-actions)، ولحجوزات التقويم استخدم [الحجز عبر Cal.com](/ar/docs/build/cal-com). وحدها بطاقات التأكيد المرتبطة بتشغيل فعلي تخوّل هذه العمليات.

## إعداد الإجراء [#إعداد-الإجراء]

افتح **الوكيل ← الإجراءات**. أنشئ المفتاح السري في **العملاء المسجّلون للدخول**، وخزّنه على خادمك ونفّذ [تحديد هوية العميل](/ar/docs/embed/security#identify-signed-in-customers). في **عمليات البحث** أضف اسمًا مثل `order_status`، واشرح متى ينبغي للوكيل استخدامها، وأدخل نقطة النهاية العامة عبر HTTPS. صرّح فقط بالمدخلات التي تحتاج إليها، مثل سلسلة نصية `order_id`. يرى الوكيل الأداة باسم `lookup_order_status`.

أبقِ خيار **يتطلب عميلًا مسجّلًا للدخول** مفعّلًا للسجلات الخاصة (وهو الإعداد الافتراضي). إذا عطّلته فقد تحتوي الطلبات على `customer: null`؛ أعِد فقط المعلومات المناسبة لزائر مجهول. المعرّف المذكور في المحادثة أو المستخرج من صورة هو مُدخل وليس هوية موثَّقة.

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

## الطلب الذي تستقبله [#الطلب-الذي-تستقبله]

يرسل Make Agent Fast طلب JSON من نوع POST إلى عنوان URL الذي هيّأته. تستخدم الأمثلة أدناه قيمًا نائبة للتوقيع:

```http
POST /agent/order-status HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
```

```json
{
  "version": 1,
  "action": "order_status",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}
```

`action` هو الاسم المهيَّأ دون البادئة `lookup_`. يحدد `requestId` هذه المحاولة بعينها، ويحدد `siteId` موقعك. يحتوي `input` على المعاملات النصية المصرَّح بها فقط. أما `customer` فهو إما null أو الكائن `{ id, email?, name? }` الذي تحقق منه الخادم؛ ولا يمكن لمدخلات الزائر أو النموذج أن تحل محله. يستخدم **اختبار** في لوحة التحكم عن قصد عميلًا تجريبيًا يُدخله مالك مخوَّل.

## التحقق من التوقيع [#التحقق-من-التوقيع]

التوقيع هو HMAC-SHA256 بصيغة سداسية عشرية بأحرف صغيرة باستخدام **المفتاح السري للوكيل**، ويسبقه `v1=`. وقّع بدقة السلسلة `"maf-webhook-v1:" + timestamp + "." + rawBody`. حافظ على البايتات كما وصلت؛ فتحليل JSON ثم إعادة تسلسله قبل فحص التوقيع قد يغيّرها. تقبل هذه الدالة المساعدة كائن `Request` قياسيًا من جهة الخادم، وتطبّق نافذة صلاحية مدتها خمس دقائق، وتثبّت الموقع:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyLookupRequest(request, expectedSiteId) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const timestamp = request.headers.get("x-maf-timestamp");
  const signature = request.headers.get("x-maf-signature");
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || !/^\d+$/.test(timestamp) ||
      !Number.isSafeInteger(Number(timestamp)) ||
      Math.abs(now - Number(timestamp)) > 300) {
    throw new Error("Invalid timestamp");
  }
  if (!signature || !/^v1=[a-f0-9]{64}$/.test(signature)) {
    throw new Error("Invalid signature");
  }
  const rawBody = Buffer.from(await request.arrayBuffer());
  const expected = createHmac("sha256", secret)
    .update(`maf-webhook-v1:${timestamp}.`)
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), "hex");
  if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
    throw new Error("Invalid signature");
  }
  const body = JSON.parse(rawBody.toString("utf8"));
  if (body?.version !== 1 || body.siteId !== expectedSiteId) {
    throw new Error("Invalid lookup scope");
  }
  return body;
}
```

استدعِها قبل أن يستهلك محلل الجسم (body parser) الطلب. ينبغي أن يرفض معالجك أخطاء التحقق، وأن يتحقق من الإجراء المتوقع وشكل المدخلات، وأن يفحص ملكية السجل مقابل `body.customer.id` قبل إعادة أي بيانات خاصة. على سبيل المثال، اختر الطلب A128 **من بين طلبات ذلك العميل**، لا بمعرّف الطلب وحده. لا تستخدم أبدًا `input.customer_id` أو بريدًا إلكترونيًا مقدَّمًا في المحادثة أو صورة كأساس للتخويل. اشترط عميلًا غير null لنقاط النهاية الخاصة. حدّد حجم الجسم الوارد على خادمك، وتتبّع `requestId` ضمن نافذة الصلاحية إذا كنت تريد رفض إعادة الإرسال؛ فالتحقق من الطابع الزمني وحده لا يرفض إعادة إرسال تقع ضمن تلك النافذة.

استخدم HTTPS وأبقِ نقطة النهاية هذه للقراءة فقط رغم أن وسيلة النقل هي POST. بعد تدوير المفتاح السري للوكيل، حدّث كلًا من خادم توقيع الهوية ومُتحقِّق عمليات البحث لديك.

## إرجاع الاستجابة [#إرجاع-الاستجابة]

أجب بحالة نجاح 2xx وبـ JSON مطابق لهذا العقد. المثال الأول سجل تم العثور عليه، والثاني نتيجة عادية بلا تطابق:

```json
{
  "found": true,
  "card": {
    "title": "Order #A128",
    "status": { "label": "Shipped", "tone": "success" },
    "fields": [{ "label": "Carrier", "value": "DHL" }],
    "reference": "A128",
    "asOf": "2026-10-12T09:00:00Z",
    "link": { "label": "Track", "url": "https://shop.example.com/orders/A128" }
  },
  "facts": { "order_id": "A128", "status": "shipped", "carrier": "DHL" }
}
```

```json
{ "found": false }
```

الحقل `found` مطلوب. عندما تكون القيمة `found: true` أدرج `card` أو `facts` أو كليهما. تتطلب البطاقة `title` و`fields` (يُسمح بمصفوفة فارغة). الحقول الاختيارية هي `status` و`reference` و`asOf` و`link`. لا تضف `kind` إلى بطاقة الاستجابة. درجات الحالة هي `neutral` و`success` و`warning` و`danger`. استخدم طابعًا زمنيًا بصيغة ISO للحقل `asOf`، ورابط HTTPS بلا بيانات اعتماد مضمَّنة. تُحذف الروابط الاختيارية غير الصالحة.

`facts` كائن مسطّح قيمه نصوص أو أعداد منتهية أو قيم منطقية أو null؛ وتُرفض الكائنات والمصفوفات المتداخلة. تُرفض الحقول غير المعروفة في مخطط الاستجابة/البطاقة. أعِد فقط المعلومات اللازمة للإجابة: يتلقى النموذج بيانات مُهرَّبة ومحدودة موسومة بأنها غير موثوقة، لا تعليمات. محتوى البطاقة نص عادي وليس HTML.

## الحدود وسلوك الفشل [#الحدود-وسلوك-الفشل]

| البند                                 | الحد                                                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| عمليات البحث لكل وكيل                 | 5؛ بأسماء ومعرّفات فريدة                                                                            |
| الاسم                                 | `^[a-z][a-z0-9_]{2,39}$`؛ أسماء الإجراءات المحجوزة غير متاحة                                        |
| الوصف                                 | 300 حرف                                                                                             |
| المدخلات المصرَّح بها                 | 3؛ بأسماء فريدة تطابق `^[a-z][a-z0-9_]{1,31}$`                                                      |
| أوصاف المدخلات / قيمها                | 300 / 200 حرف؛ تُقتطع المسافات الزائدة من القيم                                                     |
| نقطة النهاية                          | HTTPS عامة، حتى 500 حرف، بلا بيانات اعتماد؛ تُحجب العناوين الخاصة/الداخلية؛ لا تُتبع إعادات التوجيه |
| المهلة / جسم الاستجابة                | 8 ثوانٍ / 32 KiB (32,768 بايت)                                                                      |
| بيانات النموذج                        | 2,000 حرف، منفصلة عن بطاقة الزائر                                                                   |
| عنوان البطاقة / التسميات / قيم الحقول | 80 / 40 / 200 حرف                                                                                   |
| حقول البطاقة                          | 8؛ وبحد أقصى 3 بطاقات في كل دور للوكيل                                                              |

يؤدي غياب هوية العميل إلى عرض تنبيه بتسجيل الدخول دون استدعاء نقطة النهاية. وتدفع المدخلات المطلوبة المفقودة الوكيل إلى سؤال الزائر عنها. يعرض `found: false` بطاقة محايدة تفيد بعدم وجود تطابق. أما انتهاء المهلة أو حالات غير 2xx أو JSON/مخطط غير صالح أو الاستجابات كبيرة الحجم فتعرض حالة فشل وتطلب من النموذج ألا يخمّن. أعِد `found: false` مع حالة 2xx للسجل المفقود عادةً، بدلًا من HTTP 404. اجعل الحقائق المهمة موجزة: تُقتطع نصوص البطاقة وبيانات النموذج الزائدة.

## الاختبار من لوحة التحكم [#الاختبار-من-لوحة-التحكم]

1. احفظ عملية البحث وافتح **اختبار**. أدخل معرّف عميل تجريبيًا، وبريدًا إلكترونيًا اختياريًا، وجميع المدخلات المطلوبة. استخدم حسابًا تتحكم فيه.
2. شغّل **اختبار**. يرسل هذا طلبًا موقّعًا حقيقيًا حتى لو كانت عملية البحث معطّلة للزوار؛ أما محادثة التجربة العادية فلا تستدعي نقطة النهاية أبدًا. تحدّ لوحة التحكم من محاولات الاختبار لكل مالك.
3. افحص البطاقة/الملخص الذي تم التحقق منه أو الخطأ، ومعرّف الطلب، والمدة، وحالة HTTP عند توفرها. راجع سجلات نقطة النهاية لديك دون تسجيل الأسرار أو رموز العملاء.
4. اختبر حالات: العثور على السجل، وعدم العثور عليه، وحساب خاطئ، ومدخل مفقود، وانتهاء المهلة. ثم اختبر التضمين الفعلي مع عميلين موثَّقين؛ فالعميل التجريبي في لوحة التحكم لا يثبت عزل هوية المتصفح ولا اختيار النموذج الفعلي للأداة.

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

---

# أدواتك الخاصة (MCP)

Source: /ar/docs/build/mcp-tools.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/change-actions&#x22;, label: &#x22;التأكيدات والموافقات&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: &#x22;هوية العميل&#x22;, icon: &#x22;book&#x22; }
]"
/>

## الربط والاكتشاف [#الربط-والاكتشاف]

افتح **Agent ← الإجراءات ← أدواتك (MCP)**. اربط خادمك البعيد باستخدام تدفّق OAuth أو بيانات اعتماد من نوع bearer، أو استخدم اتصال MCP موجودًا. اختر **اكتشاف** لقراءة كتالوج الأدوات. راجع وصف كل أداة ومعاملاتها وتعليقاتها التوضيحية (annotations) قبل تفعيلها. لا ينفّذ الاكتشاف أي أداة؛ وتكون الأدوات المكتشَفة حديثًا معطّلة.

يمكنك إعداد ثلاثة خوادم للأدوات وتفعيل 20 أداة في المجموع. تبقى بيانات الاعتماد على جانب الخادم. إزالة ربط أداة توقف هذا الربط فقط، لكنها لا تلغي اتصال المعرفة المشترك ولا صلاحية OAuth الممنوحة له؛ أدِر هذا الاتصال بشكل منفصل. لا يمكن عرض خادم MCP الخاص بإدارة المالك في Make Agent Fast كخادم أدوات للعملاء. لإدارة الـ agents الخاصة بك من Claude، راجع [استخدام Claude وChatGPT](/ar/docs/operate/ai-assistants).

## اختيار القراءة أو الكتابة [#اختيار-القراءة-أو-الكتابة]

| التأثير | السلوك                                                                                                |
| ------- | ----------------------------------------------------------------------------------------------------- |
| قراءة   | تستدعي الأداة مباشرةً وتتعامل مع النص أو البيانات المنظّمة المُرجَعة على أنها بيانات أعمال غير موثوقة |
| كتابة   | تنشئ مقترحًا؛ ويجب على العميل تأكيد المدخلات بدقة عبر أزرار البطاقة قبل التنفيذ                       |

تتوفر القراءة فقط إذا أعلن الخادم `readOnlyHint: true` ولم يعلن `destructiveHint: true`، وأبقيتَ تصنيف الأداة على أنها قراءة. وإلا فتعامل معها على أنها كتابة. راجع ما يفعله الخادم فعليًا؛ فالتعليقات التوضيحية (annotations) ليست نظام تفويض.

تكون الموافقة من المالك مطلوبة افتراضيًا في كل مرة لعمليات الكتابة. يمكنك اختيار عدم اشتراط موافقة إضافية من المالك، أو اشتراط الموافقة عند تجاوز حدّ معيّن لمعامل رقمي. يظل تأكيد العميل مطلوبًا في جميع الأوضاع. تستخدم موافقة المالك قائمة الموافقات والإيصالات الحالية. تُحفظ الإعدادات تلقائيًا. لا تستدعي تجربة المالك الخادم البعيد أبدًا.

## ربط العميل المسجَّل الدخول [#ربط-العميل-المسجَّل-الدخول]

تتطلب الأدوات عميلًا موثَّقًا افتراضيًا. استخدم [هوية العميل الموقَّعة](/ar/docs/embed/security) على موقعك؛ فالمعرّف الذي يُكتب في المحادثة ليس تحقّقًا. بالنسبة إلى السجلات الخاصة بكل عميل، اختر معامل النص (string) في الأداة الذي يعرّف العميل. يملأ الخادم هذا المعامل من معرّف العميل الموثَّق ويزيله من مدخلات النموذج. لا يمكن استخدام معاملات enum لهذا الربط.

على سبيل المثال، اربط `customer_id` في أداة تقرأ طلبًا. يمكن للنموذج تقديم مرجع الطلب المعلَن، لكنه لا يستطيع استبداله بمعرّف عميل آخر. ومع ذلك يجب على الخادم البعيد أن يتحقق من أن الطلب يخص هذا العميل. اشتراط تسجيل الدخول دون ربط معامل لا يحصر بحد ذاته كل سجل يمكن للأداة البعيدة الوصول إليه.

## الحدود والنتائج غير المؤكدة [#الحدود-والنتائج-غير-المؤكدة]

المخططات المدعومة هي كائنات مسطّحة تضم حتى عشرة معاملات من نوع string أو number أو integer أو boolean أو enum. تبقى الكائنات المتداخلة والمصفوفات وقواعد المخطط غير المدعومة غير متاحة. تُقيَّد النصوص بحد أقصى 200 حرف؛ ولكل استدعاء بعيد مهلة 10 ثوانٍ، وتُقتطع النتائج المرئية للنموذج عند 4 كيلوبايت. محتوى النتيجة بيانات وليس تعليمات للـ agent.

لا يوفّر MCP ضمانًا عامًا لخاصية idempotency. يُستدعى إجراء الكتابة مرة واحدة بعد التأكيد أو الموافقة. وإذا كانت نتيجته غير معروفة، فلا يعيد Make Agent Fast المحاولة تلقائيًا ويُخطر المالك. تحقّق من النظام البعيد قبل إنشاء مقترح آخر. تغيير إعداد الأداة الذي تمت مراجعته يُبطل أي مقترح أقدم.

اختبر كل عملية قراءة وكتابة تنوي استخدامها مع خادمك قبل أن يستخدمها العملاء.

---

# إجراءات الصفحة

Source: /ar/docs/build/page-actions.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/html&#x22;, label: &#x22;تثبيت التضمين&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/build/follow-ups&#x22;, label: &#x22;المتابعات&#x22;, icon: &#x22;book&#x22; }
]"
/>

## تسجيل إجراء من الموقع المضيف [#تسجيل-إجراء-من-الموقع-المضيف]

تتيح إجراءات الصفحة لموقعك فتح واجهته الخاصة أو الانتقال إلى صفحة معتمدة. ثبّت أحدث إصدار من التضمين، ثم نفّذ التسجيل بعد تحميل السكربت. احتفظ بالمعالجات (handlers) داخل تطبيقك؛ فالـ agent يتلقى أسماءها وأوصافها وتعريفات معاملاتها فقط، ولا يتلقى شيفرة المعالج أبدًا.

```js
MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");
```

تُرجع الدالتان قيمة منطقية تشير إلى ما إذا كان التسجيل أو الإزالة قد قُبل. تتكوّن الأسماء من أحرف إنجليزية صغيرة وأرقام وشرطات سفلية، وتبدأ بحرف، ويتراوح طولها بين 2 و40 حرفًا. هناك تسع خانات تسجيل مخصّصة، إضافة إلى الإجراء المدمج `open_page`. يسمح كل تعريف بخمسة معاملات نصية؛ وجميع المعاملات المعلنة مطلوبة، وتصل قيمها إلى 200 حرف. أما الأوصاف فحدّها الأقصى 200 حرف. يمكن للمعالج أن يُرجع نصًا أو قيمة قابلة للتحويل إلى JSON بحجم يصل إلى 2 كيلوبايت خلال 10 ثوانٍ.

## اعتماد الإجراءات في لوحة التحكم [#اعتماد-الإجراءات-في-لوحة-التحكم]

افتح الموقع الذي ثبّتّ عليه التضمين ليُبلغ عن أسماء الإجراءات وأوصافها، ثم افتح **Agent → الإجراءات → إجراءات الصفحة**. فعّل الميزة واسمح بكل إجراء تريده. أوصاف الإجراءات المُبلَّغ عنها هي بيانات وصفية من الموقع وغير موثوقة؛ والاكتشاف لا يعتمد أي إجراء. تُحفظ الإعدادات تلقائيًا.

يمكن للـ agent اقتراح الإجراءات التي تكون مسجّلة حاليًا ومسموحًا بها فقط. يرى العميل بطاقة قبل التنفيذ. التأكيد مطلوب ما لم يحدّد المالك (Owner) الإجراء على أنه آمن؛ أما `confirm: true` في شيفرة الموقع المضيف فيتطلب دائمًا نقرة تأكيد. ولا يتجاوز `confirm: false` وحده سياسة المالك. خصّص الوضع الآمن لتغييرات الواجهة غير الضارة.

لا يحتاج الإجراء المدمج `open_page` إلى معالج. اسمح به من لوحة التحكم؛ فهو يقبل مسارًا نسبيًا أو عنوان URL بصيغة HTTP(S) ضمن أصول الموقع (origins) المسموح بها للـ agent. كما تتطلب المسارات النسبية أن يكون أصل الموقع الحالي مسموحًا به. ولا يمكنه الانتقال إلى وجهة خارجية عشوائية.

## الإبلاغ عن حدث باستخدام track [#الإبلاغ-عن-حدث-باستخدام-track]

```js
MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });
```

استدعِ هذه الدوال بعد تحميل التضمين وعند وقوع الحدث المقابل فعلًا. اضبط اسم حدث مطابقًا في [المتابعات](/ar/docs/build/follow-ups). تتبع الأسماء الصيغة نفسها (من 2 إلى 40 حرفًا)، ويجب أن تكون البيانات الاختيارية كائن JSON لا يزيد حجمه على 1 كيلوبايت. لا ترسل قيم الحقول أو بيانات الاعتماد أو تفاصيل الدفع. تطابق القواعد الحدث والمسار والمهلة؛ ولا تُخزَّن البيانات الوصفية ولا تُرسل إلى النموذج ولا تُستخدم كادعاء بحدوث تحويل. تعني القيمة المُرجعة `true` أن المُحمِّل (loader) قبل الحدث، وليس أن رسالة قد عُرضت.

## الأمان والتحقق [#الأمان-والتحقق]

تعمل إجراءات الصفحة في أداة الموقع الحية فقط، ولا تعمل في قنوات المراسلة أو تجربة المالك أو الصوت المباشر. يتحقق المُحمِّل والإطار من الأصل والمصدر والـ slug ومعرّفات الطلبات المعلّقة. تعود النتائج إلى المحادثة بوصفها بيانات متصفح غير موثوقة، وليست دليلًا على تغيّر سجل في الخادم. أبقِ المصادقة والتفويض داخل معالجاتك أو خادمك الخلفي؛ واستخدم [إجراءات التغيير](/ar/docs/build/change-actions) لعمليات الكتابة المهمة على بيانات النشاط التجاري.

لا يلغي انتهاء المهلة تنفيذ المعالج، ولا يثبت أن شيئًا لم يحدث. لا تُعِد محاولة إجراء غير مؤكَّد النتيجة تلقائيًا. ألغِ تسجيل المعالجات عندما يغادر مكوّن الصفحة الشاشة. تحتاج نسخ التضمين المخزّنة مؤقتًا إلى إصدار المُحمِّل الحالي `20261014-page-actions` لاستخدام هذه الواجهة البرمجية.

لا تتعامل هذه الواجهة البرمجية مع المدفوعات ولا توفّر موصل Shopify.

---

# الشخصية والتعليمات

Source: /ar/docs/build/persona.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;قواعد الشخصية&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;الحدود&#x22;, icon: &#x22;shield&#x22; }, { label: &#x22;اللغات&#x22;, icon: &#x22;globe&#x22; }]" />

## افصل الهوية عن المعرفة [#افصل-الهوية-عن-المعرفة]

لا توجد صفحة منفصلة للشخصية. اكتب تعليمات الوكيل في علامة التبويب **نظرة عامة** ضمن صفحة الوكيل، في حقل **التعليمات**؛ وتُحفظ تلقائيًا.

تحدد الشخصية من هو الوكيل وكيف يتصرف، بينما توفّر المعرفة الحقائق. ضع عبارة «تحدّث بصفتك مساعد دعم Acme» في الشخصية، وضع مدة الضمان الحالية في مصدر معرفة.

## ترتيب التعليمات [#ترتيب-التعليمات]

اكتب التعليمات بهذا الترتيب:

1. الهوية والدور
2. الهدف الأساسي للزائر
3. النبرة وطول الردود
4. الإجراءات والأسئلة المطلوبة
5. الادعاءات المحظورة والمواضيع الحساسة
6. شروط التصعيد والتقاط بيانات العملاء المحتملين (Leads)

## الحدود [#الحدود]

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

## اختبر التغييرات [#اختبر-التغييرات]

قد تؤثر تغييرات الشخصية على جميع القنوات. أعد اختبار الأسئلة الشائعة وحالات الرفض والتقاط بيانات العملاء المحتملين واللغات المدعومة قبل نشر أي تغيير كبير.

---

# الصوت والمكالمات المباشرة

Source: /ar/docs/build/voice.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;أصوات جاهزة&#x22;, icon: &#x22;voice&#x22; },
{ label: &#x22;رسائل صوتية&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;مكالمات مباشرة&#x22;, icon: &#x22;bolt&#x22; }
]"
/>

## فهم أنماط التفاعل الثلاثة [#فهم-أنماط-التفاعل-الثلاثة]

| النمط                             | تجربة الزائر                                                                         | الاستحقاق والاستخدام                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **الدردشة النصية**                | يكتب رسالة ويتلقى ردًا نصيًا                                                         | مفعّلة دائمًا؛ وتستهلك رصيد الذكاء الاصطناعي المعتاد                                                                      |
| **الرسائل الصوتية**               | يسجّل رسالة، وينتظر التفريغ النصي ومعالجة الوكيل وتحويل النص إلى كلام، ثم يتلقى ردًا | مشمولة في جميع الخطط؛ ويستهلك التفريغ النصي والنموذج ومعالجة الكلام رصيدًا                                                |
| **مكالمة مباشرة في الوقت الفعلي** | يجري محادثة صوتية بزمن استجابة منخفض                                                 | Operate: 30 دقيقة/شهريًا؛ Scale: 90 دقيقة/شهريًا؛ Launch: غير متاحة؛ كما تُخصم الأرصدة مسبقًا مقابل الحد المضبوط للمكالمة |

لا يمكن تعطيل النص. أما مفاتيح الرسائل الصوتية والوقت الفعلي فتتحكم في الواجهات الإضافية التي يمكن للزوار استخدامها. ولا يتجاوز مفتاح الوقت الفعلي المحفوظ استحقاق خطة مساحة العمل ولا نقص إعدادات المزوّد.

## ضبط سلوك التفاعل [#ضبط-سلوك-التفاعل]

1. افتح صفحة **الوكيل** الخاصة بالموقع وابحث عن **الصوت**.
2. أبقِ **الدردشة النصية** مفعّلة، واختر **الرسائل الصوتية** و/أو **الصوت المباشر في الوقت الفعلي**.
3. إذا كان الوكيل متعدد اللغات، فيمكنك اختياريًا تفعيل محاكاة اللغة في المكالمات المباشرة.
4. حدّد الحد التلقائي لكل مكالمة.
5. اختر صوتًا جاهزًا.
6. احفظ، ثم اختبر كل نمط مفعّل على حدة.

يقبل حد المكالمة قيمًا من 30 ثانية إلى 20 دقيقة بخطوات مقدارها 30 ثانية؛ والقيمة الافتراضية 3 دقائق. يُنهي هذا الحد مكالمة بعينها ويحمي الحصة الشهرية، لكنه لا يزيد الدقائق المباشرة المتبقية في الخطة.

## اختيار اللغات والصوت [#اختيار-اللغات-والصوت]

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

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

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

## مفاتيح المزوّدين والبدائل الاحتياطية [#مفاتيح-المزوّدين-والبدائل-الاحتياطية]

يتطلب الصوت أكثر من مفتاح نموذج:

* يستخدم تحويل الكلام إلى نص مزوّد التفريغ النصي المضبوط في المنصة.
* تحتاج الرسائل الصوتية وردود الصوت في الموصّلات إلى مزوّد تحويل النص إلى كلام المضبوط.
* تحتاج المكالمات في الوقت الفعلي إلى مزوّد الوقت الفعلي المضبوط وإلى حصة ضمن الخطة.

يستخدم الصوت المُدار من المنصة المزوّدين المضبوطين في المنصة؛ ولا تحتاج إلى مفتاح. يمكن لمالكي خطة Scale إضافة مفتاح Speko اختياريًا للتفريغ النصي وتوليد الصوت ضمن **الإعدادات ← مفاتيح مزوّدي الذكاء الاصطناعي**، ثم اتباع [مفاتيح المزوّدين](/ar/docs/account/provider-keys). تُحتسب المكالمات المباشرة دائمًا بسعر المنصة. نجاح الدردشة النصية يثبت مسار النموذج فقط؛ ولا يثبت التفريغ النصي ولا توليد الكلام ولا رفع الوسائط ولا إنشاء جلسة الوقت الفعلي.

## توجيه الكلام والبدائل الاحتياطية [#توجيه-الكلام-والبدائل-الاحتياطية]

اختر نموذجًا ضمن **نماذج الصوت** للتفريغ النصي وتوليد الصوت والمكالمات المباشرة. يحدد كل خيار النموذج وجهة تطويره؛ ويتيح **تلقائي** أن نختار نحن. تتولى Make Agent Fast الاستضافة والتوجيه، لذا لا يوجد خيار منفصل للمنصة. وقد يختلف الصوت الجاهز تحديدًا بحسب النموذج المختار.

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

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

## اختبار الرسائل الصوتية [#اختبار-الرسائل-الصوتية]

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

* البيئات الهادئة والصاخبة؛
* Safari وChrome على الجوال عند الاقتضاء؛
* سؤالًا طويلًا يقارب الحد الأقصى العام للصوت وهو 25 MB؛
* رفض إذن الميكروفون؛
* صوتًا غير مدعوم أو منخفض الجودة؛
* كل لغة مضبوطة.

بالنسبة إلى المواقع المضمَّنة، يجب أن تسمح CSP وPermissions Policy في الصفحة الأم باستخدام الميكروفون. راجع [الأمان وCSP](/ar/docs/embed/security).

## الحديث المباشر على المنصة مقابل الموقع المنشور [#الحديث-المباشر-على-المنصة-مقابل-الموقع-المنشور]

يستخدم الحديث المباشر عناصر التحكم نفسها في موضعين:

| الواجهة                     | الموضع                                                                          | المظهر                                   | هل يُعد تفعيلًا؟                     |
| --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------ |
| **لوحة استوديو الوكيل**     | عنصر الدردشة المباشر بجانب علامات التبويب في صفحة **الوكيل**                    | مظهر عنصر الزائر، معروضًا في لوحة التحكم | لا — اختبارات المالك لا تُفعّل أبدًا |
| **الموقع المنشور والتضمين** | iframe الخاص بـ `embed.js`، والعنصر في رابط الوكيل، وأي صفحة عرض مستضافة متبقية | مظهر المستأجر / العنصر                   | نعم — مكالمة الزائر محادثة حقيقية    |

تعرض اللوحة بجانب علامة التبويب **العرض** مظهر الزائر نفسه. اختبر تضمينًا حقيقيًا قبل الإطلاق؛ فنجاح اختبار لوحة التحكم لا يثبت إذن الميكروفون في التضمين ولا CSP الصفحة المضيفة ولا التفعيل.

يتبع خيار **استخدام الموقع** ضمن **سمة الوكيل** في علامة التبويب **العرض** الوضع الفاتح أو الداكن لدى الزائر في الصفحة المضيفة والتضمين. أما تثبيت الوضع الفاتح أو الداكن فيثبّت الدردشة والمكالمة المباشرة معًا. راجع [المظهر](/ar/docs/build/appearance).

## اختبار المكالمات المباشرة [#اختبار-المكالمات-المباشرة]

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

الدقائق المباشرة استحقاق شهري منفصل عن الأرصدة العادية. يؤدي إصدار رمز المكالمة المباشرة إلى خصم الأرصدة مقابل أقصى مدة يصرّح بها الخادم، وحجز هذه المدة من الحصة المباشرة الشهرية. ولأن الوسائط تتدفق مباشرة بين المتصفح والمزوّد، لا يمكن التحقق من مكالمة أقصر يبلّغ عنها العميل، ولا تُسترد المدة غير المستخدمة جزئيًا بعد تسليم الرمز. تُحرَّر حالات فشل إنشاء الرمز من جانب الخادم؛ أما الجلسات المهجورة فتُحتسب بحدها المصرّح به. أنهِ الاختبارات بشكل سليم واستخدم حد المكالمة المضبوط عند التنبؤ بالاستهلاك. راجع [الأرصدة والاستخدام](/ar/docs/operate/usage).

## إجراءات الصوت المباشر [#إجراءات-الصوت-المباشر]

يتحكم **الوكيل ← الإجراءات ← إجراءات المكالمة المباشرة** (**السماح للوكيل باتخاذ إجراءات أثناء المكالمات المباشرة**) في استخدام الأدوات أثناء المكالمات المباشرة، التي تعمل على Gemini 3.8 Live بكل اللغات. وهو مفعّل افتراضيًا (`voice.liveActions`)؛ وإيقافه يُبقي ربط الإجابات بالمعرفة متاحًا. وتظل شروط خطة الصوت المباشر والمزوّد والوصول سارية.

يمكن أن تعرض المكالمات نتائج البحث والخيارات ومقترحات التغيير والمواعيد/الحجوزات في التقويم ومراقبات المتابعة وتسليم المحادثة إلى موظف. تتطلب تغييرات النشاط التجاري والحجوزات والمراقبات الضغط على أزرار البطاقة على الشاشة؛ ولا تؤكد كلمة «نعم» المنطوقة أو المكتوبة أي عملية كتابة أبدًا. كما تحتاج المراقبة إلى موافقة بالبريد الإلكتروني على الشاشة. تبقى البطاقات ونتائج الأدوات في سجل المحادثة. أما إجراءات الصفحة وأدوات MCP الخاصة بك فليست ضمن المجموعة الفرعية للمكالمات المباشرة. يظل احتساب المكالمة قائمًا على الحجز المسبق فقط، دون استرداد لوقت المكالمة غير المستخدم بعد تسليم الرمز.

اختبر النتيجة المنطوقة والتأكيد على الشاشة معًا قبل استخدامها مع العملاء. راجع [المتابعات](/ar/docs/build/follow-ups) و[إجراءات التغيير](/ar/docs/build/change-actions).

## الإفصاح والسلامة [#الإفصاح-والسلامة]

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

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                 | ما يجب التحقق منه                                                                                                |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| يعمل النص لكن عناصر التحكم الصوتية تفشل | مفاتيح مزوّدي التفريغ النصي/تحويل النص إلى كلام/الوقت الفعلي، ومفتاح الميزة، والخطة، ورصيد الأرصدة، وإذن المتصفح |
| لا يمكن بدء التسجيل                     | HTTPS، وإذن الميكروفون، ومدخل الجهاز، وPermissions Policy للتضمين، ودعم المتصفح                                  |
| النص المفرّغ غير دقيق                   | جودة الصوت، ومجموعة اللغات المختارة، واللهجة/المصطلحات، وتغطية مزوّد التفريغ النصي                               |
| الرد المنطوق يبدو غير صحيح              | الصوت المختار، والنص المصدر، وعلامات الترقيم، وتسمية اللغة، وتوفر المزوّد                                        |
| تنتهي المكالمة المباشرة فورًا           | الدقائق المتبقية، وحد المكالمة، ومفتاح المزوّد، والشبكة، وحالة الجلسات المتزامنة                                 |

تعامل مع الصوت بوصفه واجهة إطلاق مستقلة: اختبارات القبول النصية ضرورية لكنها غير كافية.

---

# Discord

Source: /ar/docs/connectors/discord.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصّلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="89" />

## إنشاء تطبيق Discord [#إنشاء-تطبيق-discord]

اتبع الدليلين الرسميين من Discord: [البدء السريع للتطبيقات](https://docs.discord.com/developers/quick-start/getting-started) و[نظرة عامة على التفاعلات](https://docs.discord.com/developers/interactions/overview). أنشئ تطبيقًا في بوابة المطورين في Discord (Discord Developer Portal) واجمع القيم التالية:

| حقل Make Agent Fast | موقعه في Discord    | الغرض                                                                             |
| ------------------- | ------------------- | --------------------------------------------------------------------------------- |
| **Application ID**  | General Information | يحدد التطبيق والأمر                                                               |
| **Public Key**      | General Information | يتحقق من تفاعلات موقَّعة بخوارزمية Ed25519؛ يتكوّن من 64 خانة سداسية عشرية بالضبط |
| **Bot token**       | صفحة Bot            | يتحقق من التطبيق ويسجّل الأمر `/ask`؛ احتفظ به سرًا                               |

تؤدي إعادة تعيين رمز البوت إلى إبطال الرمز السابق فورًا. المفتاح العام (Public Key) ليس سريًا، لكن يجب أن يعود إلى التطبيق نفسه الذي ينتمي إليه رمز البوت.

## الربط وتسجيل `/ask` [#الربط-وتسجيل-ask]

افتح صفحة **القنوات** الخاصة بالـ agent، واختر **Discord**، وأدخل القيم الثلاث، ثم اضغط **اتصال**.

يتحقق Make Agent Fast من رمز البوت عبر نقطة نهاية التطبيق في Discord، ويرفض أي Public Key لا يطابق التطبيق. كما يصحّح تلقائيًا أي Application ID أُدخل بشكل خاطئ إلى المعرّف الحقيقي للتطبيق الذي جرت مصادقته، ثم ينشئ الأمر العام `/ask question` أو يحدّثه دون حذف أي أوامر أخرى للتطبيق.

بعد الحفظ، انسخ **Interactions Endpoint URL** المعروض إلى الحقل **General Information → Interactions Endpoint URL** في Discord ثم احفظ. يرسل Discord طلب `PING` موقَّعًا؛ يتحقق Make Agent Fast من التوقيع ويعيد الاستجابة المطلوبة `PONG`.

## التثبيت والاختبار [#التثبيت-والاختبار]

استخدم إعدادات التثبيت في Discord لتفويض التطبيق في خادم تجريبي مع الأذونات اللازمة لأوامر التطبيق. قد يستغرق انتشار الأوامر العامة بعض الوقت.

شغّل `/ask`، واملأ الخيار المطلوب `question`، ثم أرسل. يؤكد Make Agent Fast استلام التفاعل قبل انتهاء المهلة القصيرة في Discord، ثم يشغّل الـ agent، ثم يعدّل الرد الأصلي المؤجَّل. يُحفظ سجل المحادثة لكل مستخدم في Discord على حدة، بحيث تحتفظ طلبات `/ask` اللاحقة بالسياق.

الموصّل الحالي نصي فقط. فهو لا يقرأ القنوات الصوتية أو المرفقات أو رسائل القنوات العادية أو الرسائل المباشرة؛ ولا يصل إلى الـ agent سوى تفاعل `/ask` المسجَّل.

## التدوير أو قطع الاتصال [#التدوير-أو-قطع-الاتصال]

إذا تعرّض رمز البوت للكشف، فأعد تعيينه في Discord، ثم حدّث الموصّل، وتحقق من `/ask` مرة أخرى. وإذا تغيّر التطبيق نفسه، فحدّث القيم الثلاث وInteractions Endpoint URL الخاص بذلك التطبيق.

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

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                          | الحل                                                                                                                 |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| يرفض الموصّل الحقول              | استخدم رمز البوت والـ Public Key المكوَّن من 64 خانة من التطبيق نفسه                                                 |
| يرفض Discord نقطة النهاية        | تأكد من أنها عامة وتعمل عبر HTTPS، والصق نقطة النهاية التي جرى إنشاؤها، وأعد حفظ بيانات الاعتماد قبل المحاولة مجددًا |
| الأمر `/ask` غير ظاهر            | تأكد من تثبيت الأمر وتفويضه، وانتظر انتشار الأوامر العامة، ثم أعد الاتصال لتسجيله من جديد                            |
| يظهر أن التطبيق لم يستجب للتفاعل | تأكد من تفعيل الموصّل، وافحص الأخطاء في Make Agent Fast وDiscord؛ ويجب أن ينجح التحقق من توقيع نقطة النهاية          |
| تُتجاهل رسائل الدردشة الأخرى     | هذا متوقع؛ فالتكامل يتعامل مع `/ask` فقط                                                                             |
| الرد مقتطع                       | رسائل الرد في Discord محدودة بـ 2,000 حرف                                                                            |

لا تكشف رمز البوت أبدًا في كود العميل أو المستودعات أو السجلات أو لقطات الشاشة.

---

# Instagram

Source: /ar/docs/connectors/instagram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; }
]"
/>

<TutorialVideo episode="ep05" />

## ماذا يفعل هذا الموصل [#ماذا-يفعل-هذا-الموصل]

يرسل العملاء **رسالة مباشرة** إلى حساب Instagram الاحترافي الخاص بك. ويجيب Make Agent Fast بالوكيل نفسه المعتمد على المصادر الذي يعمل في تضمين موقعك، عبر واجهة Meta الرسمية [Instagram API with Instagram Login](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login).

ويمكنه أيضًا الرد على **التعليقات** في منشوراتك وريلزك، علنًا أو برسالة مباشرة خاصة (راجع [التعليقات والردود المحفوظة](#comments-and-saved-replies)). كما تتم الإجابة عن الردود على قصصك (راجع [القصص](#stories)). ما يخرج عن النطاق: استخلاص البيانات (scraping)، والإعجاب بالمنشورات أو التعليقات. فواجهة Instagram الرسمية لا توفر أي وسيلة للإعجاب بالمحتوى، لذلك لا يفعل الوكيل ذلك أبدًا.

كل حساب Instagram يمثل قناة مستقلة، لذا تبقى الفوترة ومحادثات صندوق الوارد وتوجيه الرسائل منفصلة. ويمكن للوكيل الواحد أن يرتبط بما يصل إلى خمسة حسابات Instagram.

## قبل أن تبدأ [#قبل-أن-تبدأ]

تحتاج إلى:

1. حساب Instagram **احترافي** (نشاط تجاري أو منشئ محتوى). لا يمكن ربط الحسابات الشخصية؛ يمكنك التحويل من Instagram عبر **الإعدادات ← نوع الحساب والأدوات**.
2. اسم مستخدم Instagram وكلمة المرور للحساب، أو تطبيق Instagram مسجَّل الدخول إليه مسبقًا في هذا المتصفح.
3. خطة Operate أو Scale لإضافة قناة جديدة.

أنت **لا** تحتاج إلى حساب Facebook، ولا صفحة Facebook، ولا محفظة أعمال Meta، ولا تطبيق مطوّرين من Meta.

## اربط حسابك [#اربط-حسابك]

### 1. افتح بطاقة Instagram [#1-افتح-بطاقة-instagram]

في لوحة التحكم، افتح وكيلك وانتقل إلى **القنوات ← Instagram**.

### 2. سجّل الدخول واسمح بالوصول [#2-سجّل-الدخول-واسمح-بالوصول]

اختر **الربط مع Instagram**. ستفتح Instagram صفحة تسجيل الدخول الخاصة بها. سجّل الدخول إلى الحساب الاحترافي الذي تريد أن يجيب عنه الوكيل، وتأكد من أن النافذة تذكر هذا الحساب، ثم اختر **السماح**. أبقِ خيار **الوصول إلى الرسائل وإدارتها** مفعّلًا؛ فلا يستطيع الوكيل قراءة الرسائل المباشرة أو الإجابة عنها بدونه. أما **الوصول إلى التعليقات وإدارتها** فيُستخدم فقط إذا فعّلت الردود على التعليقات لاحقًا.

ستعيدك Instagram إلى بطاقة Instagram، التي ستعرض الآن الحساب على أنه متصل. لربط حساب آخر، اختر **الربط مع Instagram** مرة أخرى وسجّل الدخول إلى ذلك الحساب.

### 3. أرسل رسالة اختبار [#3-أرسل-رسالة-اختبار]

من حساب Instagram **مختلف**، أرسل رسالة مباشرة جديدة إلى الحساب المتصل. تأكد مما يلي:

1. تظهر الرسالة في صندوق الوارد في Instagram.
2. تعرض بطاقة Instagram حدثًا جديدًا، ويظهر في **المحادثات** مسار محادثة جديد.
3. تنجح خطوة التحقق في البطاقة.

### 4. فعّل ردود الذكاء الاصطناعي [#4-فعّل-ردود-الذكاء-الاصطناعي]

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

## التعليقات والردود المحفوظة [#التعليقات-والردود-المحفوظة]

فعّل **الرد على التعليقات** في قسم **التعليقات** ببطاقة Instagram. عندها تتم الإجابة عن التعليقات الجديدة من المستوى الأعلى على منشوراتك وريلزك بالترتيب التالي:

1. **ردودك المحفوظة.** اكتب ردًا لمنشور واحد، أو لـ **جميع المنشورات**، واختر الكلمات المفتاحية التي تُفعّله (مثل `price, how much`). اترك الكلمات المفتاحية فارغة للرد على كل تعليق في ذلك المنشور. يمكن لكل رد محفوظ أن ينشر ردًا علنيًا أسفل التعليق، أو يرسل رسالة مباشرة خاصة، أو يفعل الاثنين معًا. يتحول `{name}` إلى @handle صاحب التعليق. وتتقدم ردود المنشور نفسه على ردود **جميع المنشورات**، وتتقدم ردود الكلمات المفتاحية على الردود الشاملة. لا تستخدم الردود المحفوظة الذكاء الاصطناعي ولا تستهلك أي رصيد.
2. **الذكاء الاصطناعي، إذا سمحت به.** ضمن **عندما لا يناسب أي رد محفوظ**، اختر **التزام الصمت**، أو **ردود الذكاء الاصطناعي** (جملة أو جملتان قصيرتان تُنشران علنًا)، أو **الذكاء الاصطناعي يرسل رسالة مباشرة** (تذهب الإجابة إلى الرسائل المباشرة لصاحب التعليق، مع سطر علني اختياري تكتبه أنت أسفل التعليق). يُمرَّر نص منشور التعليق إلى الوكيل كسياق. وتستهلك ردود الذكاء الاصطناعي رصيدًا كما تفعل الإجابة عن رسالة مباشرة.

لا يجيب الوكيل أبدًا عن تعليقاته هو، ولا يرد داخل سلسلة تعليقات، ولا يرد على التعليقات التي تكتفي بالإشارة إلى الأصدقاء أو تتكون من رموز تعبيرية فقط، ولا على الأسئلة التي ليس لديه إجابة معتمدة عنها. تظهر محادثات التعليقات في **المحادثات** للقراءة فقط؛ أجب عنها من Instagram. تسمح Instagram برسالة مباشرة خاصة واحدة لكل تعليق، خلال 7 أيام منه.

## القصص [#القصص]

تصل القصص إلى الوكيل في صورة رسائل مباشرة:

* **الرد المكتوب على قصتك** يجيب عنه الذكاء الاصطناعي كأي رسالة مباشرة. وعندما تكون القصة صورة، يراها الوكيل، فيحصل سؤال مثل «كم سعر هذا؟» على إجابة عما تعرضه القصة. أما قصص الفيديو فتتم الإجابة عنها من النص وحده.
* **الإشارة إليك في قصة شخص ما** و**التفاعل برمز تعبيري فقط مع قصتك** لا يتضمنان سؤالًا، لذا لا يجيب عنهما الذكاء الاصطناعي أبدًا. في قسم **القصص** ببطاقة Instagram، اكتب ردًا قصيرًا لكل منهما، أو اتركه فارغًا لالتزام الصمت. لا تستخدم هذه الردود الذكاء الاصطناعي ولا تستهلك رصيدًا، ولا يتلقى الشخص أكثر من رد تفاعل واحد في اليوم.

تظهر الثلاثة جميعها في **المحادثات**. لا تُبلغ Instagram التطبيقات عندما يعجب أحدهم بقصة، ولا يستطيع أي تطبيق الإعجاب بالقصص أو التعليق عليها.

## التوفر [#التوفر]

يظهر **الربط مع Instagram** في البطاقة بمجرد أن توافق Meta على وصول Make Agent Fast إلى المراسلة عبر Instagram. وإلى ذلك الحين قد لا تعرضه البطاقة، ولا تسلّم Instagram الرسائل إلا من الحسابات التي تسمح Meta للتطبيق باختبارها. إذا لم يظهر الزر في بطاقتك بعد، فاستخدم الطريقة المتقدمة أدناه أو عاود المحاولة لاحقًا.

## قطع الاتصال أو إعادة الربط [#قطع-الاتصال-أو-إعادة-الربط]

يجدد Make Agent Fast تسجيل الدخول تلقائيًا. إذا توقفت الردود وعرضت البطاقة خطأ في الاتصال، مثلًا بعد تغيير كلمة المرور، فاختر **إعادة الربط مع Instagram** وسجّل الدخول مجددًا. لقطع الاتصال، أزل الربط من البطاقة. ويمكنك أيضًا إزالة Make Agent Fast من Instagram عبر **الإعدادات ← التطبيقات والمواقع الإلكترونية**؛ وعندها يتوقف الوكيل عن الرد على ذلك الحساب فورًا.

## متقدم: تطبيق Meta الخاص بك [#متقدم-تطبيق-meta-الخاص-بك]

يمكن للمطورين الذين يشغّلون تطبيق Meta خاصًا بهم أن يواصلوا الربط باستخدام رمز وصول صفحة Facebook بدلًا من ذلك. يتطلب هذا حساب Instagram احترافيًا مرتبطًا بصفحة Facebook، وتطبيق مطورين من Meta يملك الأذونات `instagram_basic` و`instagram_manage_messages` و`pages_manage_metadata` و`pages_messaging` و`pages_show_list`، و[إعداد webhook](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/webhooks/) من Meta.

الصق **رمز وصول الصفحة** و**App secret** الخاص بالتطبيق في النموذج المتقدم بالبطاقة، ثم استخدم **Webhook URL** و**Verify token** اللذين تعرضهما لإعداد webhook الخاص بـ Instagram (الحقل `messages`). اشترك بالصفحة نفسها باستخدام رمز الصفحة:

```text
POST /me/subscribed_apps?subscribed_fields=messages
```

لن يجيب تطبيقك الخاص عن الجمهور إلا بعد اجتيازه مراجعة تطبيقات Meta مع Advanced Access.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                           | الحل                                                                         |
| ------------------------------------------------- | ---------------------------------------------------------------------------- |
| لا يظهر زر **الربط مع Instagram**                 | لا تزال موافقة Meta قيد الانتظار؛ راجع [التوفر](#availability)               |
| تقول Instagram إن الحساب لا يمكن استخدامه         | حوّله إلى حساب احترافي (نشاط تجاري أو منشئ محتوى) وحاول مرة أخرى             |
| «متصل بالفعل بوكيل آخر»                           | اقطع اتصاله من ذلك الوكيل أولًا، ثم اربطه هنا                                |
| تم الربط، لكن لا يظهر حدث جديد بعد رسالة الاختبار | أرسل رسالة مباشرة جديدة من حساب مختلف؛ فالرسائل المرسلة قبل الربط لا تُعاد   |
| تصل رسالة مباشرة لكن بلا رد                       | فعّل ردود الذكاء الاصطناعي بعد خطوة التحقق، وتحقق من البطاقة بحثًا عن خطأ    |
| لا تتم الإجابة عن التعليقات                       | فعّل **الرد على التعليقات** وأضف ردًا محفوظًا أو اسمح بردود الذكاء الاصطناعي |
| الرسالة الصوتية تحصل على رد نصي                   | هذا متوقع؛ الردود الصوتية في Instagram غير مدعومة                            |
| تعرض البطاقة خطأ في الاتصال                       | اختر **إعادة الربط مع Instagram** وسجّل الدخول مجددًا                        |

لا تشارك كلمة مرور Instagram مع أي شخص، بما في ذلك الدعم؛ فالاتصال يستخدم تسجيل الدخول الخاص بـ Instagram نفسه.

---

# KakaoTalk

Source: /ar/docs/connectors/kakao.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصّلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="145" />

## قائمة الإعداد [#قائمة-الإعداد]

تعرض بطاقة KakaoTalk في Make Agent Fast هذه القائمة وقد مُلئت بقيمك الخاصة، لذا يُنجز معظم المالكين الخطوات من هناك. تتم كل خطوة في وحدة تحكم Kakao باستثناء الحقلين المشار إليهما أدناه.

1. **أنشئ بوتًا** في Kakao i Open Builder. يضم بوت واحد كل كتل السيناريو التي تُجيب بها القناة؛ تخطَّ هذه الخطوة إذا كانت القناة مرتبطة ببوت يمكنك تعديله.
2. **أضف مهارة (skill)** وعيّن عنوانها إلى **Skill URL** الخاص بالموصّل، ثم أضف ترويسة طلب مخصّصة `X-Kakao-Bot-Secret` تحمل **Bot secret** الخاص بك. لا توقّع Kakao طلبات المهارات، لذا فإن هذه الترويسة هي الدليل الوحيد على أن الاستدعاء جاء من بوتك.
3. **وجّه كتلة الاحتياط (fallback) إلى المهارة** حتى يصل إلى الوكيل كل سؤال لا تعالجه سيناريوهاتك. اربط كتلة سيناريو مسمّاة بالمهارة نفسها إذا كان يجب أن يجيب عنها الوكيل أيضًا.
4. **فعّل خيار callback** لتلك الكتلة. تتجاهل Kakao استجابة المهارة التي تستغرق أكثر من خمس ثوانٍ؛ ومع تفعيل callback يعيد Make Agent Fast فقاعة انتظار فورًا ثم ينشر الإجابة النهائية إلى `userRequest.callbackUrl` خلال الدقيقة التي نعدّ فيها هذا العنوان الذي يُستخدم مرة واحدة صالحًا.
5. **اربط قناة KakaoTalk** بالبوت، ثم الصق معرّف القناة نفسه في حقل **Channel ID** الخاص بالموصّل في Make Agent Fast.
6. **انشر البوت.** لا تصل تغييرات Open Builder إلى الزوار إلا بعد النشر، وكل تغيير لاحق في مهارة أو كتلة يحتاج إلى نشر آخر.

تمثّل بقية هذه الصفحة الشرح التفصيلي للخطوات الست نفسها.

## تجهيز أصول Kakao [#تجهيز-أصول-kakao]

أنشئ أو اختر تطبيق Kakao Developers وقناة KakaoTalk وبوت Kakao i Open Builder التي ستتولى التكامل. راجع [وثائق Open Builder](https://i.kakao.com/docs/key-concepts-block#skill) الرسمية من Kakao الخاصة بالمهارات والكتل.

اجمع هذه القيم أو أنشئها:

| حقل Make Agent Fast | المصدر                                    | الغرض                                                |
| ------------------- | ----------------------------------------- | ---------------------------------------------------- |
| **Channel ID**      | المعرّف العام/معرّف البحث لقناة KakaoTalk | يربط الموصّل بالقناة المقصودة                        |
| **REST API key**    | مفاتيح تطبيق Kakao Developers             | يتحقق من صحة تطبيق Kakao                             |
| **Bot secret**      | سر عشوائي طويل تنشئه بنفسك                | يوثّق طلبات المهارة الواردة عبر `X-Kakao-Bot-Secret` |

يُشترط وجود Bot secret في بيئات Make Agent Fast المنشورة لأن استدعاءات مهارات Kakao لا توفّر توقيعًا من المنصة. أنشئ قيمة فريدة عالية الإنتروبيا ولا تعيد استخدام REST API key كسر.

## حفظ الموصّل [#حفظ-الموصّل]

افتح صفحة **القنوات** الخاصة بالوكيل، واختر **KakaoTalk Channel**، وأدخل القيم الثلاث جميعها، ثم اختر **اتصال**. يتحقق Make Agent Fast من REST API key حيثما تسمح أذونات Kakao، ويعرض **Webhook URL** الفريد للموصّل بعد الحفظ.

لا يستطيع Make Agent Fast إنشاء مهارة Open Builder أو ربطها بكتلة نيابةً عنك؛ يتم باقي العمل في وحدة تحكم Kakao.

## ضبط مهارة Open Builder [#ضبط-مهارة-open-builder]

1. في Kakao i Open Builder، أنشئ مهارة للبوت المقصود.
2. عيّن عنوان المهارة إلى **Webhook URL** المنسوخ من الموصّل.
3. أضف ترويسة طلب مخصّصة باسم `X-Kakao-Bot-Secret` تطابق قيمتها تمامًا **Bot secret**.
4. اربط المهارة بكتلة الاحتياط أو كتلة السيناريو التي يجب أن تستدعي الوكيل.
5. فعّل خيار callback لتلك الكتلة حتى تتجاوز الإجابات البطيئة مهلة المهارة في Kakao البالغة خمس ثوانٍ.
6. احفظ إعدادات البوت وانشرها وفق آلية العمل في Kakao.

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

## اختبار القدرات [#اختبار-القدرات]

استخدم أداة الاختبار في Open Builder أولًا، ثم قناة KakaoTalk المرتبطة. أرسل سؤالًا نصيًا واقعيًا بالكورية أو بإحدى اللغات المدعومة، وتأكد من الإجابة المضمّنة ومن **آخر رسالة** ومن سلسلة **المحادثات**.

تنسخ بطاقة الموصّل نص الطلب أدناه؛ ويعمل النص نفسه مع `curl` على Skill URL. وهو لا يتضمن `callbackUrl`، لذا تعود الإجابة مضمّنة، وهذا أبسط ما يمكن التحقق منه أولًا.

```json
{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}
```

تستجيب المهارة السليمة ضمن مهلة الخمس ثوانٍ بمخرج `simpleText` واحد:

```json
{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}
```

عند تفعيل خيار callback للكتلة، يضيف Open Builder `userRequest.callbackUrl` إلى الطلب. عندها يردّ Make Agent Fast أولًا بفقاعة انتظار ثم يرسل الرد النهائي بطلب POST إلى ذلك العنوان الذي يُستخدم مرة واحدة:

```json
{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}
```

عقد المهارة الحالي نصي فقط. يكون ردّ الوكيل `skillResponse` واحدًا من Kakao بالإصدار `2.0` مع مخرج `simpleText`، ضمن حدّ أقل من حد النص في Kakao، ويُعاد مضمّنًا أو على عنوان callback. الصوت والملفات والصور والإرسال الصوتي المنفصل غير مدعومة.

## التدوير أو قطع الاتصال [#التدوير-أو-قطع-الاتصال]

لتدوير Bot secret، حدّث الموصّل وترويسة Open Builder المخصّصة كتغيير منسّق واحد، ثم اختبر فورًا. أي عدم تطابق يوقف كل الطلبات الواردة. دوِّر REST API key في Kakao Developers وفي Make Agent Fast قبل إلغاء المفتاح القديم.

لا يؤدي تعطيل الموصّل أو إزالته إلى حذف مهارة Open Builder أو الكتلة. أزل هذه العناصر في جانب المزوّد أو افصلها عند إيقاف التكامل نهائيًا.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                      | الحل                                                                                   |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| الموصّل يتطلب Bot secret                     | أنشئ واحدًا؛ فالبيئات المنشورة ترفض webhook من Kakao غير موثَّق                        |
| رفض REST API key                             | استخدم REST API key من تطبيق Kakao المقصود وتأكد من أذونات قناته                       |
| يتلقى Open Builder استجابة غير مصرّح بها     | أضف/حدّث `X-Kakao-Bot-Secret` ليطابق تمامًا قيمة الموصّل                               |
| تعرض أداة الاختبار كتلة الاحتياط بدل الإجابة | تأكد من أن الكتلة تستدعي عنوان المهارة المحفوظ وافحص سجلات الطلبات/الاستجابات في Kakao |
| انتهاء مهلة الطلبات                          | فعّل خيار callback للكتلة؛ ودونه تمنح Kakao المهارة خمس ثوانٍ فقط                      |
| يتم تجاهل الصوت أو الصور                     | هذا متوقع؛ يقبل الموصّل الحالي النص فقط                                                |

لا تعرض REST API key أو Bot secret في شيفرة العميل أو في الوثائق العامة.

---

# Messenger

Source: /ar/docs/connectors/messenger.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصّلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; }
]"
/>

<TutorialVideo episode="ep09" start="31" />

## تجهيز تطبيق Meta والصفحة [#تجهيز-تطبيق-meta-والصفحة]

اتبع [دليل البدء الرسمي لـ Messenger Platform](https://developers.facebook.com/docs/messenger-platform/get-started) من Meta. أضف Messenger إلى تطبيق Meta، واربط صفحة Facebook التي ستستقبل الرسائل، وتأكد من أن حسابك يملك صلاحية إدارة الأصلين معًا.

اجمع القيم من التطبيق نفسه والصفحة نفسها:

| حقل Make Agent Fast | القيمة لدى المزوّد                                    | الغرض                                    |
| ------------------- | ----------------------------------------------------- | ---------------------------------------- |
| **رمز وصول الصفحة** | الرمز الصادر للصفحة المحددة                           | قراءة هوية الصفحة وإرسال الردود          |
| **سر التطبيق**      | سر تطبيق Meta المكوّن من 32 خانة بالنظام السداسي عشري | التحقق من طلبات webhook الواردة الموقّعة |

لا تستخدم رمز وصول مستخدم ولا رمزًا يخص صفحة أخرى. تحدد حالة تطوير التطبيق ومراجعته لدى Meta الأشخاص الذين يمكنهم استخدام التكامل.

## حفظ بيانات الاعتماد والتحقق منها [#حفظ-بيانات-الاعتماد-والتحقق-منها]

افتح صفحة **القنوات** الخاصة بالـ agent، واختر **Messenger**، وأدخل رمز وصول الصفحة وسر التطبيق، ثم اختر **اتصال**.

يستدعي Make Agent Fast واجهة Graph API باستخدام `appsecret_proof`، ويحدد معرّف الصفحة واسمها، ويربط الأحداث الواردة بهذه الصفحة تحديدًا. بعد ذلك تعرض بطاقة الموصّل **عنوان Webhook URL** و**رمز التحقق**.

## إعداد webhook الخاص بالصفحة [#إعداد-webhook-الخاص-بالصفحة]

في تطبيق Meta نفسه:

1. افتح إعدادات webhook الخاصة بـ Messenger.
2. الصق **Webhook URL** و**رمز التحقق** الخاصين بالموصّل.
3. أكمل خطوة التحقق (verification challenge).
4. اختر الاشتراك في أحداث الرسائل المطلوب لسير عمل Messenger لديك.
5. اشترك بصفحة Facebook المقصودة في التطبيق.
6. تأكد من أن اشتراك الصفحة ووضع التطبيق يسمحان لمستخدم الاختبار لديك.

يُستخدم رمز التحقق فقط في خطوة التحقق الأولية. أما أحداث التشغيل فيجب أن تحمل توقيعًا يطابق سر التطبيق. كما يرفض Make Agent Fast الأحداث الموجّهة إلى صفحة مختلفة حتى لو جاءت من تطبيق Meta نفسه.

## اختبار الإمكانات [#اختبار-الإمكانات]

أرسل رسالة عادية إلى الصفحة من حساب اختبار مسموح له وليس مسؤولًا، وتأكد من وصول الرد ومن ظهور المحادثة في **المحادثات**. ثم اختبر مرفق صوت إذا كانت الرسائل الصوتية الواردة مهمة لسير عملك.

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

## الجاهزية للإنتاج [#الجاهزية-للإنتاج]

أكمل الأذونات ومراجعة التطبيق والتحقق من النشاط التجاري ورابط الخصوصية وخطوات نشر الصفحة التي تطلبها Meta لجمهورك. نجاح الاختبار في وضع التطوير بحساب له دور في التطبيق لا يعني أن الجمهور العام قادر على مراسلة تكامل الصفحة.

وثّق تطبيق Meta المالك ومعرّف الصفحة (Page ID) للمشغّلين. قد يتوقف رمز الصفحة عن العمل عند تغيّر مالكه أو أذوناته أو ارتباطه بالنشاط التجاري أو سياسة المزوّد.

## التدوير أو قطع الاتصال [#التدوير-أو-قطع-الاتصال]

أنشئ رمز الصفحة البديل، ثم حدّث الموصّل، واختبر من مستخدم مسموح له، وبعدها أبطل الرمز القديم. حدّث Make Agent Fast فور تدوير سر التطبيق.

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

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                         | الحل                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| رفض الرمز                       | تأكد من أنه رمز وصول للصفحة المقصودة وأن سر التطبيق يعود للتطبيق نفسه                 |
| فشل التحقق من webhook           | انسخ العنوان الحالي ورمز التحقق كما هما تمامًا، واستخدم HTTPS عامًا                   |
| ينجح التحقق لكن الرسائل لا تصل  | اشترك بالصفحة وبحدث الرسائل، ثم افحص وضع التطبيق ودور المستخدم وسجلات التسليم في Meta |
| الطلبات غير مصرّح بها           | صحّح سر التطبيق؛ فطلبات POST الموقّعة لا تستخدم رمز التحقق                            |
| تظهر الرسالة الواردة دون رد     | افحص صلاحية رمز الصفحة وأذونات المراسلة وخطأ الإرسال لدى المزوّد وحالة الموصّل        |
| الرسالة الصوتية تحصل على رد نصي | هذا متوقع؛ الرد الصوتي الصادر في Messenger غير مدعوم حاليًا                           |

يجب ألا تُدخَل بيانات اعتماد المزوّد إلا في نموذج الموصّل بعد تسجيل الدخول أو في استدعاء API موثوق من جهة الخادم.

---

# نظرة عامة على الموصّلات

Source: /ar/docs/connectors/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/telegram&#x22;, label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; },
{ href: &#x22;/ar/docs/connectors/whatsapp&#x22;, label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; },
{ href: &#x22;/ar/docs/connectors/messenger&#x22;, label: &#x22;Messenger&#x22;, icon: &#x22;messenger&#x22; },
{ href: &#x22;/ar/docs/connectors/instagram&#x22;, label: &#x22;Instagram&#x22;, icon: &#x22;instagram&#x22; },
{ href: &#x22;/ar/docs/connectors/discord&#x22;, label: &#x22;Discord&#x22;, icon: &#x22;discord&#x22; },
{ href: &#x22;/ar/docs/connectors/kakao&#x22;, label: &#x22;KakaoTalk&#x22;, icon: &#x22;kakao&#x22; }
]"
/>

تستقبل الموصّلات الأحداث من منصة مراسلة خارجية، وتعالج النص أو الصوت المدعوم وتحوّله إلى صيغة موحّدة، وتشغّل وكيل الموقع نفسه، ثم تعيد ردًا مناسبًا للقناة. يحصل كل مستخدم خارجي على سجل محادثات خاص بالقناة يظهر في **المحادثات**.

يتطلب ربط قناة **جديدة** الاشتراك في باقة Operate أو Scale. تستمر الاتصالات الحالية في العمل على باقة Launch.

<TutorialVideo episode="ep09" start="15" />

## مصفوفة الإمكانات [#مصفوفة-الإمكانات]

| القناة    | النص الوارد     | الصوت الوارد | النص الصادر          | الصوت الصادر | إعداد المزوّد بعد الحفظ                                        |
| --------- | --------------- | ------------ | -------------------- | ------------ | -------------------------------------------------------------- |
| Telegram  | نعم             | نعم          | نعم                  | اختياري      | يُسجَّل الـ webhook تلقائيًا                                   |
| WhatsApp  | نعم             | نعم          | نعم                  | اختياري      | أضف webhook من Meta واشتراك `messages`                         |
| Messenger | نعم             | نعم          | نعم                  | لا           | أضف webhook من Meta واشترك في الصفحة                           |
| Instagram | نعم             | نعم          | نعم                  | لا           | أضف webhook الخاص بـ Instagram من Meta واشترك في `messages`    |
| Discord   | سؤال عبر `/ask` | لا           | رد عبر `/ask`        | لا           | الصق نقطة نهاية التفاعلات؛ يتم تسجيل الأمر تلقائيًا            |
| KakaoTalk | نعم             | لا           | رد مضمّن عبر المهارة | لا           | أضف عنوان URL الخاص بالمهارة والترويسة والكتلة في Open Builder |

يعني «الصوت الوارد» أنه يتم تنزيل رسالة صوتية أو ملف صوتي مدعوم ثم تحويله إلى نص. أما «الصوت الصادر» فيتطلب مزوّد كلام يعمل بشكل سليم وتفعيل خيار **الرد بالصوت** في الموصّل. تُتجاهل المرفقات غير المدعومة مثل الصور والمواقع الجغرافية ولا تُفسَّر على أنها تعليمات للوكيل.

## قبل الربط [#قبل-الربط]

1. اختبر الوكيل المقصود في لوحة التحكم. يمكن لموصّل في حالة المسودة أن يرد أيضًا.
2. لا تحتاج إلى مفتاح نموذج: توفّر المنصة النماذج. مفاتيح المزوّد اختيارية ومتاحة في باقة Scale فقط؛ راجع [مفاتيح المزوّد](/ar/docs/account/provider-keys).
3. أنشئ تطبيقًا أو بوتًا أو رقمًا أو قناة مخصصة في المزوّد الخارجي. لا تعِد استخدام بيانات اعتماد تخص تكاملًا إنتاجيًا غير مرتبط.
4. تأكد من أن بيئة النشر لديك تحتوي على عنوان أساسي عام للموصّل عبر HTTPS. لا تستطيع webhooks الخاصة بالمزوّدين التسليم إلى `localhost` دون نفق تطوير آمن.
5. افتح صفحة **القنوات** الخاصة بالوكيل واختر القناة.

عند الحفظ، يتصل Make Agent Fast بالمزوّد للتحقق من بيانات الاعتماد المُرسَلة. تعني تسمية «متصل» أن التحقق من بيانات الاعتماد وأي تجهيز تلقائي قد اكتملا؛ ولا تثبت أن خطوة يدوية في وحدة تحكم Meta أو Discord أو Kakao قد أُنجزت.

## التعامل مع بيانات الاعتماد [#التعامل-مع-بيانات-الاعتماد]

تقبل نماذج الموصّلات بيانات اعتماد المزوّد فقط من لوحة التحكم الموثّقة أو من Public API من جهة الخادم. تُشفَّر الأسرار أثناء التخزين ولا تُعاد أبدًا في استجابات قائمة الموصّلات. تعامل مع القيم التالية كما تتعامل مع كلمات المرور:

* رمز بوت Telegram
* رموز الوصول وسر التطبيق في Meta
* رمز بوت Discord
* مفتاح REST API وسر البوت في Kakao

لا تضعها في JavaScript داخل المتصفح، ولا في لقطات الشاشة، ولا في تذاكر الدعم، ولا في نظام التحكم بالإصدارات. عنوان webhook URL ورمز التحقق (verify token) من Meta هما قيم إعداد مخصّصة للنسخ إلى وحدة تحكم المزوّد المطابقة؛ ولا تحل محل بيانات اعتماد المزوّد.

## الربط عبر API [#الربط-عبر-api]

استخدم مفتاح MAF API محفوظًا على الخادم مع النطاق `connectors:write`. الكائن `credentials` الخاص بكل قناة للكتابة فقط. تحذف الاستجابة الأسرار بنصها الصريح وتتضمن عنوان webhook URL المطلوب للإعداد اليدوي لدى المزوّد.

```bash
curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'
```

الحقلان `reply_with_voice` و`display_label` الاختياري هما حقلان في المستوى الأعلى، وليسا داخل كائن `config`. يؤدي حفظ البوت أو الحساب نفسه مرة أخرى إلى تحديث بيانات اعتماده وإعداداته مع الحفاظ على رمز التوجيه الخاص به. في Telegram وInstagram، يؤدي استخدام بوت أو حساب مختلف إلى إضافة اتصال جديد بدلًا من ذلك (حتى خمسة اتصالات لكل وكيل)؛ أما في القنوات الأخرى فيستبدل الحفظ الاتصال الحالي. استخدم [مصادقة API](/ar/docs/api/authentication) و[النطاقات والأخطاء](/ar/docs/api/scopes-errors) و[مرجع API](/ar/docs/api/reference) لمعرفة قواعد التكامل في بيئة الإنتاج.

## الاختبار والمراقبة [#الاختبار-والمراقبة]

استخدم مستخدم اختبار لدى المزوّد وسؤالًا واقعيًا يعتمد على معرفة الوكيل. تأكد من كل ما يلي:

* يقبل المزوّد نقطة نهاية webhook أو يتحقق منها.
* تصل الرسالة إلى الوكيل وتتلقى الرد المتوقع.
* يتغير **آخر رسالة** على بطاقة الموصّل.
* تظهر المحادثة في **المحادثات** مع القناة الصحيحة.
* فهم أي قيود مفروضة من المزوّد تتعلق بالمراجعة أو وضع التطوير قبل الإطلاق العام.
* اختبار الصوت بشكل منفصل عن النص عندما تدعمه القناة.

تعرض بطاقة الموصّل آخر خطأ صادر عن المزوّد أو عن التسليم. كما تحتفظ لوحات تحكم المزوّدين بسجلات التسليم؛ قارن الطوابع الزمنية ومعرّفات الأحداث عندما يُبلغ أحد الطرفين فقط عن الطلب.

## التعطيل أو التدوير أو الإزالة [#التعطيل-أو-التدوير-أو-الإزالة]

يؤدي **التعطيل** إلى إيقاف المعالجة مع الاحتفاظ بسجل الموصّل. يبقى webhook الخاص بـ Telegram مسجّلًا أثناء تعطيل الاتصال (لا يستدعي Make Agent Fast الدالة `deleteWebhook`) وتُتجاهل الرسائل الواردة؛ وعند التفعيل يُسجَّل الـ webhook من جديد. تبقى اشتراكات المزوّد التي أُعدّت عبر وحدة التحكم كما هي، ويجب إيقافها من جهة المزوّد أيضًا عند الحاجة. تؤدي **الإزالة** إلى حذف موصّل Make Agent Fast ومحاولة تفكيك الإعداد لدى المزوّد بأفضل جهد، لكنها لا تحذف التطبيق الخارجي، ولا تلغي بيانات اعتماده، ولا تمحو سجل المحادثات الحالي.

لتدوير بيانات الاعتماد، أنشئ رمز المزوّد الجديد، ثم حدّث الموصّل، واختبره، وبعدها ألغِ الرمز القديم. إذا تعرّضت بيانات اعتماد للكشف، فألغِها لدى المزوّد أولًا وتعامل مع الفترة الزمنية المعنية على أنها حادث أمني.

## حالات الفشل الشائعة [#حالات-الفشل-الشائعة]

| العَرَض                         | ما يجب التحقق منه                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| تعذّر التحقق من بيانات الاعتماد | صحة التطبيق/البوت، ونوع الرمز، وتاريخ الانتهاء، وصلاحية المزوّد المطلوبة، وسلامة الأحرف المنسوخة                      |
| فشل التحقق من webhook           | عنوان HTTPS العام، ورمز التحقق (verify token) المطابق تمامًا، ومنتج المزوّد الصحيح، وسر توقيع الطلبات                 |
| ينجح التحقق لكن لا تصل أي رسائل | اشتراك الأحداث، وارتباط الصفحة/الرقم/القناة، ووضع تطبيق المزوّد، وحالة تفعيل الموصّل                                  |
| يعمل النص لكن يفشل الصوت        | إمكانات القناة، ومفتاح الكلام/النسخ الصوتي، والصوت المدعوم، وصلاحية الوسائط، وانتهاء صلاحية تنزيل المزوّد             |
| تتوقف الردود بعد التدوير        | حفظ بيانات الاعتماد الجديدة، وإلغاء القديمة بعد الاختبار فقط، وبقاء اشتراك المزوّد اليدوي موجّهًا إلى هذا الـ webhook |

تابع مع دليل القناة لمعرفة حقول المزوّد الدقيقة وتسلسل الخطوات في وحدة التحكم.

---

# Telegram

Source: /ar/docs/connectors/telegram.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;Telegram&#x22;, icon: &#x22;telegram&#x22; }
]"
/>

<TutorialVideo episode="ep03" />

## الإعداد السريع [#الإعداد-السريع]

إذا كان خيار **الإنشاء عبر رمز QR** متاحًا في موصل Telegram، فاخترْه، ثم امسح رمز QR أو اختر **فتح Telegram**، واضغط **إنشاء بوت** في بوت الإعداد. عُد إلى Make Agent Fast، وراجع اسم مستخدم البوت، ثم اختر **ربط هذا البوت**. لا حاجة إلى نسخ أي رمز مميز. تنتهي صلاحية الإعداد بعد 15 دقيقة، ويمكنك إلغاؤه وإعادة بدئه.

إذا لم يكن الإعداد السريع متاحًا، فاستخدم **الربط عبر رمز البوت المميز** أدناه. تستخدم الطريقتان فحوصات الربط نفسها وتأكيد الاستبدال نفسه.

يقترح نموذج الإنشاء الاسم المعروض لوكيلك واسم مستخدم بالصيغة `maf_<agent>_<random>_bot`. يمكن تعديل كليهما؛ فالجزء العشوائي يقلل من تعارض الأسماء، لكن Telegram هو من يجري فحص التوفر النهائي. لا تتم إعادة تسمية البوتات الموجودة.

بعد الإنشاء، يرسل بوت الإعداد زر **ربط هذا البوت** الذي يفتح صفحة مراجعة الربط الموثّقة الخاصة بوكيلك. إنشاء البوت وحده لا يربطه. وبعد نجاح التأكيد، يوصلك **فتح البوت** إلى المحادثة لإجراء الاختبار. يعيد الأمر `/start` أو `/help` عرض الإعداد النشط، أو يُظهر أزرار لوحة التحكم والدليل.

## إنشاء بوت وإعداده يدويًا [#إنشاء-بوت-وإعداده-يدويًا]

اتبع [Introduction to Bots](https://core.telegram.org/bots) الرسمي من Telegram و[BotFather guide](https://core.telegram.org/bots/features#botfather):

1. افتح حساب **@BotFather** الموثّق في Telegram.
2. نفّذ الأمر `/newbot`، واختر اسمًا معروضًا، ثم اختر اسم مستخدم فريدًا ينتهي بـ `bot`.
3. انسخ رمز البوت المميز. أي شخص يملك هذا الرمز يتحكم في البوت.
4. اختياريًا، اضبط الصورة والوصف ونص "حول" ومساعدة الأوامر المحلية في BotFather قبل الإطلاق.

هذا الرمز مخصص لواجهة Telegram Bot API؛ وهو ليس رمز تسجيل دخول إلى Telegram ولا API ID ولا API hash.

## الربط في Make Agent Fast [#الربط-في-make-agent-fast]

افتح صفحة **القنوات** الخاصة بالوكيل، واختر **Telegram**، والصق **رمز البوت المميز**، وحدّد ما إذا كان ينبغي نطق الردود المدعومة صوتيًا أيضًا، ثم اختر **ربط**.

يستدعي Make Agent Fast الدالة `getMe` في Telegram للتحقق من الرمز المميز وعرض اسم مستخدم البوت. ثم يستدعي `setWebhook` مع عنوان URL العام عبر HTTPS الخاص بالموصل، ورمز تحقق سري، وأنواع التحديثات المقبولة `message` و`callback_query` و`my_chat_member`. لا يتم تجاهل التحديثات المعلقة الموجودة.

لا تلزم عادةً أي خطوة يدوية لضبط webhook. أوقف أي خدمة polling قبل الربط. وإذا كان للبوت مستقبِل webhook آخر، فراجع استبداله وأكّده؛ فـ Make Agent Fast لا يستحوذ عليه بصمت. يمكن لوكيل واحد الرد عبر ما يصل إلى خمسة بوتات Telegram في الوقت نفسه؛ ويُعد كل بوت ربطًا مستقلًا. وحفظ بوت مختلف يضيف ربطًا جديدًا بدلًا من استبدال الربط الحالي. أما البوت المرتبط بوكيل آخر فيجب فصله هناك أولًا.

## اختبار المحادثة [#اختبار-المحادثة]

1. افتح رابط `t.me` الخاص بالبوت من حساب Telegram لا يعود للمالك.
2. اختر **Start**؛ فالبوتات لا تستطيع بدء محادثة مع مستخدم.
3. أرسل سؤالًا نصيًا يعتمد على المعرفة.
4. أرسل رسالة صوتية إذا كان الصوت مفعّلًا.
5. تأكد من وصول الردود، ومن تغيّر **آخر رسالة**، ومن ظهور المحادثة في **المحادثات**.

الرسائل الخاصة عامة افتراضيًا: لا يحتاج الزوار إلى موافقة المالك. أما الردود في المجموعات فهي متوقفة إلى أن يفعّل المالك **الرد في المجموعات عند الإشارة إلى البوت أو الرد على رسالته**. ويظل وضع الخصوصية (Privacy Mode) في Telegram وأذونات المجموعة ساريين. اختبر الرسائل المباشرة أولًا.

## سلوك الصوت [#سلوك-الصوت]

يدعم Telegram في هذا الموصل الصوت الوارد والصوت الصادر. يتم تنزيل الرسائل الصوتية الواردة وتحويلها إلى نص قبل أن يعالجها الوكيل. وعند تفعيل **الرد بالصوت** وتوفر مزوّد للكلام، يرسل Make Agent Fast ردًا صوتيًا إضافة إلى النص. وإذا فشل تحويل الصوت إلى نص أو توليد الكلام، فاطلب من المستخدم إعادة المحاولة بالنص وافحص خطأ الموصل.

## تغيير الرمز المميز أو التعطيل أو الإزالة [#تغيير-الرمز-المميز-أو-التعطيل-أو-الإزالة]

إذا تعرّض الرمز المميز للكشف، فأنشئ رمزًا جديدًا أو ألغِ القديم في BotFather فورًا، ثم حدّث الموصل بالرمز البديل واختبر مجددًا. تحديث بيانات الاعتماد للبوت نفسه يحافظ على إعداداته وعلى حالة الإيقاف المؤقت. أما استبداله ببوت مختلف فيتطلب تأكيدًا ويُبقي سجل البوت السابق منفصلًا.

يؤدي التعطيل إلى إيقاف الردود محليًا، بينما تؤدي الإزالة إلى أرشفة الربط مع الاحتفاظ بسجله. لا يحذف أي منهما بوت Telegram ولا يستدعي `deleteWebhook`، إذ قد يعطّل ذلك مستقبِلًا أحدث. تتجاهل الروابط المؤرشفة الرسائل الواردة. يمكن للبوتات المنشأة بالإعداد السريع تحديث بيانات اعتمادها بعد أحداث دورة حياة المدير، لكن البوت الموقوف مؤقتًا يبقى موقوفًا، وتغيير الملكية يعطّل الربط إلى حين مراجعته.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                           | الحل                                                                                                      |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| رفض الرمز المميز عند الحفظ                        | انسخ الرمز الحالي من BotFather؛ أزل المسافات وتأكد من أنه يخص هذا البوت                                   |
| تصل الرسائل إلى خدمة أقدم                         | أوقف polling هناك، وأعد الربط هنا، وأكّد صراحةً أي استبدال للمستقبِل                                      |
| تعمل الرسائل المباشرة لكن رسائل المجموعات لا تعمل | فعّل الردود في المجموعات، وأشر إلى البوت أو ردّ عليه، وراجع وضع الخصوصية في Telegram وأذونات المجموعة     |
| لا يراسل البوت المستخدم الجديد أولًا              | هذا سلوك متوقع في Telegram؛ اطلب من المستخدم فتح البوت واختيار **Start**                                  |
| يعمل النص لكن الصوت يفشل                          | تحقق من مفاتيح النموذج وتحويل الصوت إلى نص وتوليد الكلام، ثم أعد المحاولة برسالة صوتية مدعومة من Telegram |

لا تلصق أبدًا رمزًا مميزًا فعّالًا في الوثائق أو الشيفرة المصدرية أو أدوات التحليلات أو لقطات شاشة الدعم.

---

# WhatsApp

Source: /ar/docs/connectors/whatsapp.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/connectors/overview&#x22;, label: &#x22;جميع الموصلات&#x22;, icon: &#x22;connectors&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;صندوق الوارد&#x22;, icon: &#x22;message&#x22; },
{ label: &#x22;WhatsApp&#x22;, icon: &#x22;whatsapp&#x22; }
]"
/>

<TutorialVideo episode="ep04" />

## تجهيز تطبيق Meta والرقم [#تجهيز-تطبيق-meta-والرقم]

اتبع [دليل البدء الرسمي لـ WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) من Meta لإنشاء تطبيق Meta أو اختيار تطبيق موجود، وإضافة منتج WhatsApp، وربط حساب WhatsApp Business (WABA) ورقم الهاتف به.

اجمع هذه القيم الثلاث من التطبيق والرقم نفسيهما:

| حقل Make Agent Fast | القيمة لدى المزوّد                        | ملاحظات                                                                                                     |
| ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Phone number ID** | معرّف رقم الهاتف (Phone Number ID) الرقمي | ليس رقم الهاتف الظاهر الذي يبدأ بـ `+` ولا معرّف WABA                                                       |
| **Access token**    | رمز وصول Cloud API                        | تنتهي صلاحية الرموز المؤقتة في لوحة التحكم؛ استخدم رمز مستخدم نظام (system-user) طويل الأمد مناسبًا للإنتاج |
| **App secret**      | السر الخاص بتطبيق Meta                    | سر سداسي عشري من 32 حرفًا يُستخدم للتحقق من توقيع webhook                                                   |

امنح الأذونات اللازمة فقط للرقم وسير عمل المراسلة. وأبقِ أصول التطوير والاختبار منفصلة عن رقم الإنتاج.

## حفظ بيانات الاعتماد والتحقق منها [#حفظ-بيانات-الاعتماد-والتحقق-منها]

افتح صفحة **القنوات** الخاصة بالوكيل، واختر **WhatsApp**، وأدخل القيم الثلاث، ثم فعّل **الرد بالصوت** إذا لزم الأمر، واختر **اتصال**.

يتحقق Make Agent Fast من الرقم عبر Graph API باستخدام رمز الوصول مع `appsecret_proof`؛ وبذلك يُكتشف أي خطأ في الرقم أو الرمز أو سر التطبيق قبل بدء وصول حركة webhook. بعد ذلك تعرض بطاقة الموصل **Webhook URL** و**Verify token** فريدين.

## إعداد webhook في Meta [#إعداد-webhook-في-meta]

في تطبيق Meta نفسه:

1. افتح إعدادات webhook الخاصة بـ WhatsApp.
2. الصق **Webhook URL** الخاص بالموصل بوصفه عنوان callback.
3. الصق **Verify token** الخاص بالموصل كما هو تمامًا؛ فهو حساس لحالة الأحرف.
4. أكمل عملية التحقق.
5. اشترك بحساب WhatsApp Business أو الرقم في حقل webhook المسمى `messages`.
6. تأكد من أن التطبيق وأصول النشاط التجاري متاحة للمستخدمين المقصودين للاختبار أو الإنتاج.

يثبت verify token ملكيتك أثناء طلب التحقق GET. أما طلبات POST أثناء التشغيل فتُصادَق بشكل منفصل عبر توقيع سر تطبيق Meta؛ فلا تستبدل أحدهما بالآخر.

## اختبار النص والصوت [#اختبار-النص-والصوت]

أرسل رسالة أولًا من رقم اختبار مسموح به. في وضع التطوير لدى Meta قد لا يتمكن المستخدمون غير المسجلين من الوصول إلى التطبيق. تأكد من ظهور المحادثة والقناة في **المحادثات**، وراقب **آخر رسالة** في بطاقة الموصل.

الرسائل النصية والصوتية الواردة مدعومة. عند تفعيل **الرد بالصوت** وإعداد خدمة الكلام، يرفع Make Agent Fast الصوت المُنشأ عبر Cloud API ويرسله مع الرد النصي. أما الصور والمواقع وجهات الاتصال وأنواع الرسائل الأخرى غير المدعومة فتُتجاهل.

## الجاهزية للإنتاج [#الجاهزية-للإنتاج]

قبل الإعلان عن الرقم، أكمل الخطوات التي تفرضها Meta لحالتك: توثيق النشاط التجاري، ومراجعة التطبيق، واسم العرض، والقوالب، وسياسة المراسلة. هذه المتطلبات تحددها Meta وقد تتغير بمعزل عن Make Agent Fast.

استخدم بيانات اعتماد إنتاجية لها مالك محدد وإجراء واضح لانتهاء الصلاحية والتدوير. سجّل تطبيق Meta ومستخدم النظام وWABA وPhone Number ID الخاصة بهذا الموصل، حتى يتمكن المشغّل من تدويرها دون تخمين.

## التدوير أو قطع الاتصال [#التدوير-أو-قطع-الاتصال]

أنشئ رمزًا بديلًا بصلاحيات الوصول إلى الأصول نفسها، ثم حدّث الموصل، وأرسل رسالة اختبار، وبعد ذلك فقط ألغِ الرمز القديم. وإذا تغيّر سر التطبيق، فحدّثه في Make Agent Fast فورًا، وإلا فستفشل كل طلبات webhook الواردة الموقّعة.

لا يؤدي تعطيل الموصل أو إزالته إلى إلغاء اشتراك webhook في Meta أو حذف إعداده. أزل الاشتراك لدى المزوّد أيضًا عند إيقاف الرقم نهائيًا.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                          | الحل                                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| رفض بيانات الاعتماد              | تأكد من أن الرمز يستطيع قراءة Phone Number ID المحدد بدقة، وأن سر التطبيق من التطبيق نفسه                              |
| تعذّر تحقق Meta من callback      | استخدم عنوان HTTPS المنسوخ وverify token الصحيح تمامًا، وتأكد من أن الموصل لا يزال موجودًا                             |
| نجح التحقق لكن لا تصل أي رسائل   | اشترك في `messages`، وتحقق من ربط WABA والرقم، ووضع التطبيق، وصلاحية وصول مستخدمي الاختبار، وسجلات التسليم لدى المزوّد |
| ترجع webhooks الخطأ unauthorized | أعد إدخال سر التطبيق الصحيح؛ فتوقيعات POST في Meta لا تستخدم verify token                                              |
| فشل الردود الصادرة               | تحقق من انتهاء صلاحية الرمز، وأذونات الرقم، وسياسة المستلم أو نافذة المراسلة، وأخطاء Graph API                         |
| يعمل النص لكن يفشل الصوت         | تحقق من مفاتيح مزوّد تحويل الكلام إلى نص/نص إلى كلام، ومن صلاحية الرمز لرفع الوسائط وتنزيلها                           |

لا تكشف رمز الوصول أو سر التطبيق في شيفرة المتصفح أبدًا. استخدم Public API من خادم موثوق فقط عند أتمتة إنشاء الموصلات.

---

# Astro

Source: /ar/docs/embed/astro.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## تجهيز نطاق النشر [#تجهيز-نطاق-النشر]

فعّل **إظهاره على موقعي** لوكيل Make Agent Fast (صفحة الوكيل ← **انشره مباشرةً** ← **أداة الموقع**)، ثم أضف نطاقات Astro الدقيقة الخاصة بالتطوير والمعاينة والإنتاج ضمن **عناوين المواقع المسموح بها**. المهم هو المخطط (scheme) واسم المضيف والمنفذ كما تظهر في المتصفح في النهاية، وليس مضيف البناء ولا عنوان URL للمستودع.

## الإضافة إلى تخطيط مشترك [#الإضافة-إلى-تخطيط-مشترك]

ضع أداة التحميل الخارجية القياسية قبل `</body>` مباشرةً في تخطيط Astro الذي ينبغي أن يمتلك زر التشغيل.

```astro
---
// src/layouts/BaseLayout.astro
---

<html lang="en">
  <body>
    <slot />

    <script
      is:inline
      src="https://makeagent.fast/embed.js?v=20261022-open"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
      async
    ></script>
  </body>
</html>
```

تُخبر `is:inline` Astro بالإبقاء على وسم السكربت الخارجي وسمات `data-*` الخاصة به كما هي بدلًا من تجميعه أو تحويله. تظل أداة التحميل عامة ومستقلة عن أي إطار عمل؛ لا تستورِدها داخل وحدة خادم.

## الاقتصار على صفحات محددة [#الاقتصار-على-صفحات-محددة]

استخدم تخطيطًا متداخلًا أو أدرج الوسم في صفحات `.astro` المحددة فقط. تجنّب وضع الوسم نفسه في التخطيط الأساسي وفي الصفحة معًا. تتجاهل أداة التحميل أي جذر مكرر بنفس المعرّف (slug)، لكن تكرار HTML يجعل التنقل وعملية الإزالة أصعب في التتبع.

إذا كانت انتقالات العرض (view transitions) من جهة العميل في Astro مفعّلة، فاختبر التحميل المباشر للصفحات والتنقل داخل التطبيق. يُفضَّل استخدام تخطيط مشترك ثابت للوكيل المعروض في الموقع كله. أما للسلوك الخاص بمسارات معينة، فاحذف السكربت و`maf-embed-root-YOUR_SITE_SLUG` معًا عند مغادرة المسار، قبل إدراج سكربت جديد لاحقًا.

## ضبط CSP والموافقة [#ضبط-csp-والموافقة]

لا تزال ترويسات الاستضافة الثابتة هي التي تتحكم في المتصفح. اسمح بـ `https://makeagent.fast` في `script-src` و`frame-src` وسياسة الاتصال المعنية. إذا كان مدير الموافقة يحجب السكربت، فحمّل الوسم بعد الحصول على الموافقة المطلوبة فقط، بدلًا من إضعاف CSP أو تجاوز الموافقة.

## التحقق من المخرجات المبنية [#التحقق-من-المخرجات-المبنية]

1. شغّل بناء الإنتاج في Astro وافحص ملف HTML الناتج للتأكد من بقاء وسم `data-agent`.
2. افتح الصفحة المنشورة في نافذة خاصة.
3. تأكد من وجود جذر تضمين واحد ونجاح طلبات أداة التحميل وiframe.
4. تنقّل بين مسارات Astro وتأكد من الاستمرارية المقصودة.
5. أرسل رسالة حقيقية واختبر السلوك على الجوال والميكروفون.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                             | الحل                                                   |
| --------------------------------------------------- | ------------------------------------------------------ |
| يحذف HTML المبني السمات أو يغيّرها                  | أضف `is:inline` إلى السكربت الخارجي                    |
| يتم إخراج وسمي سكربت                                | أبقِ التثبيت في تخطيط أو صفحة واحدة تمتلكه             |
| يختلف التنقل من جهة العميل عن التحميل المباشر       | اختبر انتقالات العرض واختر تخطيطًا مشتركًا ثابتًا      |
| يعمل في بيئة التطوير ولا يعمل على الاستضافة الثابتة | أضف نطاق الإنتاج الدقيق وترويسات CSP الخاصة بالاستضافة |
| فشل الصوت                                           | اهيّئ HTTPS وإذن المتصفح وPermissions Policy           |

لا يتوفر حاليًا محوّل Astro منشور على npm؛ استخدم أداة التحميل المستضافة الموضّحة هنا.

---

# Cafe24

Source: /ar/docs/embed/cafe24.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

Cafe24 (카페24) منصة تجارة إلكترونية كورية يتم فيها تعديل تصميم واجهة المتجر عبر HTML. ثبّت أيقونة التشغيل في التخطيط المشترك للتصميم الذي تستخدمه فعليًا. لا يوجد حاليًا تطبيق Make Agent Fast في متجر تطبيقات Cafe24. أسماء القوائم الواردة هنا صحيحة حتى 2026-09؛ وإذا تغيّر موضع أي عنصر أو اسمه، فابحث عن الإعداد بحسب وظيفته لا بحسب مساره الدقيق.

## إضافة المحمِّل [#إضافة-المحمِّل]

1. في لوحة تحكم Make Agent Fast، افتح **انشره الآن** ← **ودجت الموقع** في صفحة الوكيل، وفعّل **إظهاره على موقعي**، ثم أضف إلى **عناوين المواقع المسموح بها** كل مصدر (origin) خاص بواجهة المتجر — أي عنوان المتجر على `cafe24.com` ونطاقك المخصص، إضافةً إلى عنوان الجوال إذا كان مختلفًا.
2. افتح إدارة التصميم وابدأ تحرير HTML للتصميم المنشور حاليًا. انسخ التصميم أو احتفظ بنسخة احتياطية منه أولًا، فأنت تعدّل الكود المصدري لواجهة المتجر.
3. في ملف التخطيط المشترك الذي تتضمنه كل الصفحات، الصق المقتطف البرمجي الذي تم إنشاؤه قبل وسم الإغلاق `</body>` مباشرةً.
4. احفظ، ثم طبّق التصميم على واجهة المتجر، وكرر الخطوات لتصميم الجوال إذا كان متجرك يحتفظ بتصميمي الكمبيوتر والجوال بشكل منفصل.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

إذا لم تعثر على ملف التخطيط، فالصق المقتطف في كتلة التذييل (footer) الخاصة بالقالب بدلًا من ذلك — يصلح أي مكوّن يظهر في كل الصفحات، بشرط أن يتم تضمينه مرة واحدة فقط.

## التحقق [#التحقق]

1. افتح واجهة المتجر في نافذة خاصة، على عنوان الكمبيوتر وعنوان الجوال معًا.
2. تأكد من أن المصدر (origin) الظاهر في شريط العنوان هو الذي أضفته إلى القائمة المسموح بها، بما في ذلك `www` إذا كان النطاق يعيد التوجيه إليه.
3. تأكد من أن `embed.js` يعيد الرمز `200` في لوحة Network، وأن عنصرًا واحدًا فقط من النوع `data-maf-embed="YOUR_SITE_SLUG"` موجود.
4. اطرح سؤالًا واقعيًا وتأكد من ظهور الرسالة في **المحادثات**.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                                | السبب المحتمل                       | الحل                                                  |
| ------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------- |
| يعمل على الكمبيوتر ولا يعمل على الجوال                 | تصميم الجوال له ملف تخطيط خاص به    | أضف المقتطف إلى تصميم الجوال أيضًا                    |
| اختفت أيقونة التشغيل بعد تغيير التصميم                 | تم تطبيق تصميم لا يحتوي على المقتطف | أعد إضافته إلى تخطيط التصميم المعروض حاليًا في المتجر |
| تغطي أيقونة التشغيل سلة التسوق أو شريطًا سفليًا ثابتًا | عنصران ثابتان يشغلان الزاوية نفسها  | غيّر زاوية أيقونة التشغيل باستخدام `data-position`    |

لا تضع مفتاح API أو رقم طلب أو بيانات العملاء في أي سمة `data-*`. يتناول دليل [الأمان وCSP](/ar/docs/embed/security) إعداد قائمة العناوين المسموح بها وسياسة أمان المحتوى (Content Security Policy) للمتاجر التي تفرضها.

---

# Framer

Source: /ar/docs/embed/framer.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## توفر المكوّن البرمجي [#توفر-المكوّن-البرمجي]

انسخ الملف `integrations/framer/MakeAgentFast.tsx` إلى مكوّن برمجي في Framer، ثم اختر الوكيل المنشور. يوفّر الكود المصدري عناصر تحكم في عنوان URL الخاص بالمنصة وموضع الأداة وتسميتها. هذا كود مصدري يُنسخ يدويًا، وليس مكوّنًا منشورًا في Framer Marketplace. لن يظهر رابط الإدراج هنا إلا بعد أن ينشره مالك مخوَّل ويتحقق منه.

## الشيفرة المخصصة [#الشيفرة-المخصصة]

أضف أداة التحميل القياسية في **إعدادات الموقع ← الشيفرة المخصصة** في نهاية الجزء `body`.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

انشر الموقع قبل الاختبار. قد تستخدم لوحة التصميم (canvas) ومضيف المعاينة في Framer أصولًا (origins) مختلفة عن اسم المضيف المنشور الفعلي.

---

# Ghost

Source: /ar/docs/embed/ghost.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

افتح **Settings → Code injection** (**الإعدادات ← حقن الشيفرة**) وأضف السكربت إلى تذييل الموقع (Site Footer).

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

استخدم حقن الشيفرة على مستوى المنشور فقط عندما تريد ظهور الوكيل في منشورات محددة. أما إذا عدّلت القالب بدلًا من ذلك، فضع المحمّل في الملف `default.hbs` قبل الوسم `</body>` وتحقق منه مجددًا بعد تحديثات القالب.

أضف أصل النشر العام (public publication origin) إلى القائمة المسموح بها، وامسح ذاكرة التخزين المؤقت الطرفية (edge cache) قبل اختبار أي slug تم تغييره.

---

# HTML وJavaScript

Source: /ar/docs/embed/html.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## تجهيز الموقع [#تجهيز-الموقع]

في صفحة **الوكيل** الخاصة بالوكيل، افتح **اجعله متاحًا للجمهور** ← **أداة الموقع**، ثم فعّل **إظهاره على موقعي**، وأضف أصل الصفحة المضيفة النهائي ضمن **عناوين المواقع المسموح بها**. أضف بيئة التطوير وبيئة الإنتاج كلًّا على حدة؛ فالعناوين `http://localhost:3000` و`https://example.com` و`https://www.example.com` لا تتطابق مع بعضها.

## تثبيت السكربت [#تثبيت-السكربت]

الصق المُحمِّل (loader) قبل وسم الإغلاق `</body>` مباشرةً في كل صفحة يجب أن يظهر فيها زر الفتح. استبدل فقط المعرّف العام للموقع (slug) وقيم العرض الاختيارية.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

السمة `data-agent` مطلوبة. المعرّف عام، ولا يجوز وضع أي مفتاح API في هذا الوسم. أبقِ معامل الاستعلام `?v=` كما هو في المقتطف الظاهر في لوحة التحكم. السمات الاختيارية `data-label` و`data-accent` (`#RGB` / `#RRGGBB`) و`data-locale` (`en` | `ko` | `uz` | `ru`) و`data-theme` (`light` | `dark`) موثّقة في [نظرة عامة على التضمين](/ar/docs/embed/overview). احذفها ليرث الوكيل إعدادات **العرض** المحفوظة وسلوك السمة التلقائي.

## اختيار التثبيت على مستوى الموقع أو على صفحات محددة [#اختيار-التثبيت-على-مستوى-الموقع-أو-على-صفحات-محددة]

في حال وجود قالب مشترك على الخادم، ضع السكربت في التخطيط العام أو التذييل. أما للصفحات المحددة، فأدرجه في قوالبها فقط. حمّل المعرّف نفسه مرة واحدة لكل مستند؛ إذ يتم تجاهل الوسوم المكررة التي تحمل المعرّف نفسه، لكن إزالة التكرار تُبقي الملكية وعملية الإزالة أكثر وضوحًا وقابلية للتوقع.

لا تلصق المقتطف داخل مُنقّي HTML أو حقل نص منسّق يزيل الوسم `<script>`. تأكد من أن مصدر الصفحة المعروضة أو لوحة العناصر (Elements) ما زال يحتوي على الوسم.

## الإزالة أو إعادة التركيب في تطبيق SPA [#الإزالة-أو-إعادة-التركيب-في-تطبيق-spa]

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

```js
const slug = "YOUR_SITE_SLUG";
document.getElementById("maf-agent")?.remove();
document.getElementById(`maf-embed-root-${slug}`)?.remove();
```

يُفضّل إبقاء عنصر جذر واحد على مستوى الموقع مركّبًا أثناء التنقل من جهة العميل حتى لا تُفقد المحادثة الجارية. وإذا أزلت العنصر الجذر، فأضف سكربت `embed.js` جديدًا لإنشائه من جديد.

## التحقق في المتصفح [#التحقق-في-المتصفح]

1. افتح الصفحة المنشورة في نافذة خاصة.
2. تأكد من أن `embed.js` يُرجع الحالة `200` وأنه غير محظور بسبب CSP أو الموافقة.
3. تأكد من وجود عنصر جذر واحد فقط `[data-maf-embed="YOUR_SITE_SLUG"]`.
4. افتح زر الفتح وتأكد من تحميل iframe على المسار `/embed/YOUR_SITE_SLUG`.
5. أرسل سؤالًا وتأكد من ظهور المحادثة في **المحادثات**.
6. اختبر العرض على عرض شاشة الجوال، واختبر إذن الميكروفون عند تفعيل الصوت.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                | الحل                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------ |
| تحذّر وحدة التحكم من غياب `data-agent` | ضع السمة على وسم `embed.js` نفسه                                         |
| السكربت موجود لكن زر الفتح لا يظهر     | تحقق من مفتاح التضمين، والأصل المطابق تمامًا، وCSP، وحالة الموافقة       |
| يعمل على اسم مضيف واحد فقط             | أضف كل مخطط/مضيف/منفذ فعلي إلى قائمة السماح                              |
| يختلف المظهر عن المتوقع                | تحقق من `data-accent` و`data-theme` ومظهر الموقع المحفوظ                 |
| يفشل الصوت داخل iframe                 | اسمح بالميكروفون في المتصفح وفي Permissions Policy الخاصة بالموقع المضيف |

لا تستخدم وكيلًا وسيطًا (proxy) للمُحمِّل ولا تنسخه إلى نسخة محلية معدّلة لم تُراجَع؛ استخدم السكربت المستضاف ليبقى التحقق من الأصل والإصلاحات محدّثة دائمًا.

---

# Imweb

Source: /ar/docs/embed/imweb.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

Imweb (아임웹) هو منصة كورية لبناء المواقع، تستخدمها متاجر واستوديوهات صغيرة كثيرة. ثبّت زر التشغيل عبر إعداد إدراج الشيفرة المتوفر في Imweb نفسها. لا يوجد تطبيق خاص بـ Make Agent Fast في كتالوج Imweb. أسماء القوائم هنا صحيحة حتى 2026-09؛ وإذا تغيّرت تسمية ما، فابحث عن الإعداد بحسب وظيفته لا بحسب مساره الدقيق.

## إضافة المحمّل [#إضافة-المحمّل]

1. في لوحة تحكم Make Agent Fast، افتح **Put it live** → **Website widget** في صفحة الوكيل، وفعّل **Show it on my website**، ثم أضف إلى **Allowed website addresses** كل أصل (origin) تقدّم منه Imweb موقعك، أي نطاقك المخصص وعنوان `imweb.me` المجاني إن كنت لا تزال تستخدمه.
2. افتح إعدادات الموقع وابحث عن قسم إدراج الشيفرة: وهو الحقول التي تضيف شيفرة إلى `<head>` في كل صفحة أو إلى نهاية body. يعتمد توفره على باقة Imweb التي تشترك فيها.
3. الصق المقتطف الذي تم إنشاؤه في حقل head. المحمّل من النوع `async`، لذا يعمل في head وفي نهاية body على حد سواء.
4. احفظ التغيير وطبّقه على الموقع المباشر، ثم أعد تحميل المتجر في علامة تبويب جديدة.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

إذا لم تجد هذا الإعداد، فالصق المقتطف بدلًا من ذلك في كتلة التذييل (footer) ضمن القالب: فعنصر HTML الموضوع في قسم التذييل يعمل في كل صفحة تستخدم هذا القسم.

## التحقق [#التحقق]

1. افتح الرابط المنشور في نافذة خاصة، وليس داخل محرر Imweb. فقد يمنع وضعا المحرر والمعاينة تشغيل السكربتات المُدرجة.
2. تأكد من أن أصل الموقع في شريط العناوين هو الذي أضفته إلى قائمة السماح، بما في ذلك `www` إذا كان النطاق يعيد التوجيه إليه.
3. تأكد من أن `embed.js` يُرجع الرمز `200` في لوحة Network، وأن عنصرًا واحدًا فقط من النوع `data-maf-embed="YOUR_SITE_SLUG"` موجود.
4. اطرح سؤالًا واقعيًا وتأكد من ظهور الرسالة في **Conversations**.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العرض                                  | السبب المحتمل                                         | الحل                                      |
| -------------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
| لا يتم تحميل أي شيء على النطاق المخصص  | تمت إضافة عنوان `imweb.me` فقط إلى قائمة السماح       | أضف أيضًا أصل النطاق المخصص بالضبط        |
| يظهر زر التشغيل مرتين                  | المقتطف موجود في حقل head وفي عنصر HTML بالتذييل معًا | احتفظ بنسخة واحدة في حقل head             |
| يتداخل زر التشغيل مع زر عائم في المتجر | عنصران ثابتان يشغلان الزاوية نفسها                    | غيّر زاوية زر التشغيل عبر `data-position` |

إذا كان المتجر يستخدم شريط موافقة أو أداة لحظر السكربتات، فصنّف التضمين ضمن سياسة الموافقة لديك وحمّله وفقًا لذلك. تعرض صفحة [الأمان وCSP](/ar/docs/embed/security) الأصول التي ينبغي السماح بها.

---

# Notion وLinktree

Source: /ar/docs/embed/notion-linktree.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

لا توفّر صفحات Notion ولا ملفات Linktree الشخصية مساحة لتشغيل JavaScript عشوائي على مستوى الموقع بالكامل، ولذلك لا يمكن استخدام الودجت العائم فيها. شارك بدلًا من ذلك **رابط الوكيل** الخاص بوكيلك، وهو صفحة دردشة عامة واحدة على عنوان الوكيل نفسه.

## إضافة رابط [#إضافة-رابط]

1. في خطوة الإعداد الأخيرة، فعّل **رابط الوكيل** ضمن **اختبر على هاتفك**. يوجد المفتاح نفسه في تبويب **العرض** في صفحة الوكيل.
2. انسخ عنوان URL الفعلي لرابط الوكيل الذي تعرضه Make Agent Fast. لا تختلق معرّف الوكيل (slug) أو النطاق.
3. أضف رابطًا أو إشارة مرجعية (bookmark) في Notion، أو أضف رابطًا في Linktree مثل **تحدّث مع وكيلنا**.
4. افتح الرابط على هاتفك. يستطيع أي شخص لديه الرابط إجراء محادثة ما دامت الصفحة مفعّلة، وعند إيقافها تصبح الصفحة غير متاحة.

لا يحتاج موقع عميلك إلى السكربت حتى يعمل هذا الرابط. وإذا كنت تفضّل الربط بموقعك الإلكتروني، فثبّت الودجت هناك أولًا واستخدم عنوان URL لتلك الصفحة. الرابط العادي أكثر موثوقية من وضع الصفحة داخل iframe في منصة أخرى، فقد يقيّد ذلك الوصول إلى الميكروفون وتخطيط الصفحة.

---

# نظرة عامة على التضمين

Source: /ar/docs/embed/overview.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/html&#x22;, label: &#x22;HTML&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/react-next&#x22;, label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/ar/docs/embed/vue-nuxt&#x22;, label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/ar/docs/embed/sveltekit&#x22;, label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/ar/docs/embed/astro&#x22;, label: &#x22;Astro&#x22;, icon: &#x22;astro&#x22; },
{ href: &#x22;/ar/docs/embed/wordpress&#x22;, label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/ar/docs/embed/shopify&#x22;, label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/ar/docs/embed/webflow&#x22;, label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/ar/docs/embed/framer&#x22;, label: &#x22;Framer&#x22;, icon: &#x22;framer&#x22; },
{ href: &#x22;/ar/docs/embed/wix&#x22;, label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/ar/docs/embed/squarespace&#x22;, label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/ar/docs/embed/ghost&#x22;, label: &#x22;Ghost&#x22;, icon: &#x22;ghost&#x22; },
{ href: &#x22;/ar/docs/embed/notion-linktree&#x22;, label: &#x22;Notion&#x22;, icon: &#x22;notion&#x22; },
{ href: &#x22;/ar/docs/embed/tilda&#x22;, label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/imweb&#x22;, label: &#x22;Imweb&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/cafe24&#x22;, label: &#x22;Cafe24&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: &#x22;CSP&#x22;, icon: &#x22;shield&#x22; }
]"
/>

<TutorialVideo episode="ep02" />

## كيف يعمل التضمين [#كيف-يعمل-التضمين]

يضيف `embed.js` زر تشغيل ثابتاً واحداً إلى مستند الموقع المضيف. ويمكنه تحميل إطار iframe المخفي مسبقاً من `https://makeagent.fast` لتقييم مشغّلات الصفحة قبل النقرة الأولى؛ ويفتح الزائر المحادثة الكاملة من زر التشغيل أو من أحد المشغّلات. لا يمكن لأنماط CSS الخاصة بالموقع المضيف أن تعيد تنسيق المحادثة. ولا تُنفَّذ التغييرات على صفحة الموقع المضيف إلا عبر [معالجات إجراءات الصفحة](/ar/docs/build/page-actions) المسجّلة والمعتمدة من المالك.

المحمّل عام ولا **يستخدم** مفتاح API. يتم التحكم في الوصول عبر مفتاح التبديل **عرضه على موقعي** الخاص بالوكيل وقائمة السماح الدقيقة للأصل الأب (**عناوين المواقع المسموح بها**). المعرّف المختصر للموقع (site slug) مجرد معرّف وليس سراً.

## المتطلبات الأساسية [#المتطلبات-الأساسية]

قبل نسخ الشيفرة:

1. أنشئ وكيلاً واختبره في لوحة التحكم.
2. استخدم المقتطف الذي يولّده الوكيل؛ فتفعيل **رابط الوكيل** المنفصل الخاص به ليس مطلوباً.
3. في صفحة **الوكيل** الخاصة بالوكيل، افتح **انشره** ← **أداة الموقع**. إذا لم تكن الأداة مفعّلة بعد، فاختر **تفعيل التضمين**؛ ثم تأكد من تشغيل **عرضه على موقعي**.
4. ضمن **عناوين المواقع المسموح بها**، أضف كل أصل أب (origin) سيعرض زر التشغيل.
5. اختر **حفظ إعدادات التضمين**، ثم انسخ المقتطف المولَّد.

يتكوّن الأصل (origin) من المخطط (scheme) واسم المضيف (hostname) ومنفذ اختياري فقط، ولا يحتوي أبداً على مسار. هذه أربعة أصول مختلفة ويجب إضافة كل منها على حدة عند استخدامها:

```text
https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000
```

لا تُدخل `https://example.com/pricing` ولا `*.example.com` ولا أي حرف عام (wildcard) في النهاية. إذا كان موقع الإنتاج يعيد التوجيه من النطاق المجرّد إلى `www`، فأضف إلى قائمة السماح الأصل الذي يبقى في شريط عنوان المتصفح بعد إعادة التوجيه.

## تثبيت المحمّل [#تثبيت-المحمّل]

ضع نصاً برمجياً واحداً قبل وسم الإغلاق `</body>`، أو استخدم دورة الحياة الخاصة بالمتصفح فقط التي يوصي بها دليل إطار العمل لديك.

تنسخ ورقة **أداة الموقع** (صفحة الوكيل ← **انشره**) هذه الصيغة (المعرّف المختصر للموقع، والموضع، والتسمية الاختيارية، ومعامل كسر التخزين المؤقت `?v=`). أبقِ على `async`. وأبقِ على معامل الاستعلام `?v=` من المقتطف حتى لا تثبّت المواقع المضيفة محمّلاً قديماً.

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>
```

السمة `data-agent` وحدها مطلوبة. وفيما يلي السمات الاختيارية التي يقرؤها المحمّل فعلاً:

```html
<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>
```

لا تضع مفتاح API الخاص بـ MAF، ولا مفتاح مزوّد، ولا رمز موصّل، ولا هوية زائر، ولا بيانات عملاء خاصة في أي سمة `data-*`. ولا تخترع سمات مثل `data-api-key` أو `data-z-index` أو `data-offset` أو `data-delay`. أما `data-maf-bootstrapped` فيضبطها المحمّل نفسه.

## ضبط السمات [#ضبط-السمات]

تُقرأ من وسم `embed.js` فقط. ويقبل الـ iframe ألوان التمييز بصيغة hex فقط.

| السمة                  | القيمة المقبولة                                                                                               | الافتراضي                              | التأثير                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-agent`           | المعرّف المختصر لموقع الوكيل                                                                                  | مطلوبة                                 | تحدد الموقع والوكيل. في حال غيابها ← تحذير في وحدة التحكم (console) ولا يظهر زر التشغيل                                                       |
| `data-position`        | `bottom-left`، `bottom-right`، `top-left`، `top-right` (وما زالت `left` / `right` تعنيان الزاويتين السفليتين) | `right` (أسفل اليمين)                  | أي قيمة أخرى تُعامل على أنها أسفل اليمين                                                                                                      |
| `data-label`           | نص عادي                                                                                                       | أيقونة فقط                             | نص زر التشغيل المرئي واسمه المتاح لقارئات الشاشة. اهرب من `"` و`<`. تضع واجهة لوحة التحكم حداً أقصى قدره 40 حرفاً                             |
| `data-accent`          | `#RGB` أو `#RRGGBB`                                                                                           | مظهر الموقع المحفوظ                    | تجاوز من الموقع المضيف لزر التشغيل؛ تُتجاهل القيم غير hex داخل الـ iframe                                                                     |
| `data-locale`          | `en` أو `ko` أو `uz` أو `ru`                                                                                  | اللغة الأساسية للوكيل                  | لغة افتتاح الوكيل في صفحة الموقع المضيف هذه، تُختار من اللغات المفعّلة لديه                                                                   |
| `data-theme`           | `light` أو `dark`                                                                                             | خلفية الموقع المضيف، وإلا نظام التشغيل | تُتجاهل القيم الأخرى                                                                                                                          |
| `data-auto-form-error` | `true`                                                                                                        | معطّلة                                 | تفعيل اختياري لأحداث مشغّل أخطاء النماذج؛ تُبلغ عن معرّف النموذج ولا تُبلغ أبداً عن قيم الحقول                                                |
| `data-analytics`       | `off` (وكذلك `false` و`0` و`no`)                                                                              | مفعّلة                                 | استخدمها عندما لا يكون زائرك قد وافق على التحليلات: لا يحمّل إطار المحادثة أي تحليلات للصفحة ولا يرسل إشارة مشاهدة. وتبقى المحادثة نفسها تعمل |

يستخدم الجذر المولَّد أيضاً `data-maf-open` داخلياً لتتبّع ما إذا كانت المحادثة مفتوحة. وهي ليست إعداداً في وسم النص البرمجي ولا أمراً عاماً لفتح الأداة. راجع [المتابعات](/ar/docs/build/follow-ups) لمعرفة سلوك المشغّلات.

في غياب `data-theme`، يأخذ المحمّل عيّنة من خلفية الموقع المضيف ثم يعود إلى تفضيل نظام تشغيل الزائر. كما يمرّر عائلة خط الموقع المضيف إلى الإطار ويجلب أحدث مظهر لزر التشغيل. ولا يمنع فشل طلب المظهر ظهور زر التشغيل؛ إذ يحتفظ بالنمط الافتراضي الآمن. وتؤدي تغييرات **العرض** في لوحة التحكم إلى تحديث هذا الجلب دون إعادة نشر الموقع.

## سلوك وقت التشغيل [#سلوك-وقت-التشغيل]

* حمّل النص البرمجي مرة واحدة لكل مستند. تكرار المعرّف المختصر نفسه آمن (idempotent) ولا ينتج إلا جذراً واحداً هو `maf-embed-root-YOUR_SITE_SLUG`.
* يمكن لوكلاء مختلفين التعايش في مستند واحد. يضع المحمّل علامة `data-maf-bootstrapped` على كل نص برمجي عولج، بحيث يهيّئ الاحتياطي غير المتزامن كل وسم `data-agent` مختلف مرة واحدة بالضبط.
* يمكن تحميل الـ iframe مسبقاً من أجل مشغّلات الصفحة. ويظل مخفياً إلى أن يظهر أحد المشغّلات أو يفتح الزائر المحادثة؛ أما الجلسات التي استخدمت مشغّلاً من قبل فتحتفظ بمسار الفتح الكسول. ويبقى الميكروفون والتشغيل التلقائي والكتابة في الحافظة خاضعة لنموذج أذونات الـ iframe في المتصفح.
* في تطبيق يعتمد التوجيه من جهة العميل، ركّب المحمّل في أعلى تخطيط (layout) ينبغي أن يملكه حتى لا تعيد تغييرات المسار تحميل المحادثة.
* إزالة عنصر النص البرمجي وحده لا تزيل زر تشغيل أُنشئ بالفعل. وللتفكيك الخاص بمسار معيّن، أزل أيضاً العنصر المطابق `maf-embed-root-...`. وأعد تحميل النص البرمجي بعد التفكيك لتركيبه من جديد.
* يتبادل الإطار والمحمّل رسائل ذات مساحة أسماء تخص دورة الحياة والهوية والمشغّلات وإجراءات الصفحة. ويرفض المحمّل الرسائل التي لا تأتي من أصل Make Agent Fast ومن المعرّف المختصر الحالي للموقع.

## التحقق من التثبيت [#التحقق-من-التثبيت]

اختبر الصفحة المنشورة، لا معاينة محرّر منشئ المواقع فقط:

1. افتح عنوان URL المنشور في نافذة خاصة وتأكد من أن أصله الدقيق مضاف إلى قائمة السماح.
2. تأكد من أن `https://makeagent.fast/embed.js?v=20261022-open` يعيد `200` في لوحة الشبكة (Network).
3. تأكد من وجود عنصر واحد فقط يحمل `data-maf-embed="YOUR_SITE_SLUG"`.
4. افتح زر التشغيل وتأكد من نجاح طلب الـ iframe إلى `/embed/YOUR_SITE_SLUG`.
5. أرسل سؤالاً واقعياً وتأكد من ظهوره في **المحادثات**.
6. اختبر نافذة عرض ضيقة للجوال، واختبر إذن الميكروفون إن كان مفعّلاً.

## تشخيص اختفاء زر التشغيل [#تشخيص-اختفاء-زر-التشغيل]

| العَرَض                                     | السبب المحتمل                                                      | الحل                                                                      |
| ------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| تعرض وحدة التحكم تحذير `missing data-agent` | السمة الخاصة بالمعرّف المختصر غائبة أو موجودة على نص برمجي آخر     | ضع `data-agent` على وسم `embed.js`                                        |
| تم حظر `embed.js`                           | رفضت سياسة CSP أو أداة إدارة الموافقة النص البرمجي                 | اسمح بأصل النص البرمجي أو حمّله بعد الحصول على الموافقة المطلوبة          |
| يظهر زر التشغيل لكن الإطار يرفض التحميل     | التضمين متوقف أو أن الأصل الأب مختلف                               | أعد فحص **عرضه على موقعي** و**عناوين المواقع المسموح بها** في لوحة التحكم |
| يعمل على localhost ولا يعمل في الإنتاج      | الأصل الخاص بالتطوير فقط هو المضاف إلى قائمة السماح                | أضف أصل HTTPS المنشور بالضبط                                              |
| يظهر وكيلان مختلفان                         | يحمّل المستند معرّفين مختصرين مختلفين                              | أبقِ على المعرّف المختصر المقصود فقط                                      |
| تُفتح المحادثة لكن الصوت لا يعمل            | إذن المتصفح أو سياسة الأذونات (Permissions Policy) تحظر الميكروفون | اتبع [الأمان وCSP](/ar/docs/embed/security)                               |

## اختيار دليل التثبيت [#اختيار-دليل-التثبيت]

استخدم [HTML وJavaScript](/ar/docs/embed/html) للوسم البرمجي العادي. وبالنسبة إلى React وVue وSvelteKit وAstro وWordPress وShopify وWebflow وFramer وWix وSquarespace أو Ghost، اختر الدليل المطابق في الشريط الجانبي. أما المنصات التي لا تسمح بشيفرة JavaScript اعتباطية، مثل كثير من واجهات Notion وLinktree، فيمكنها الإحالة إلى **رابط الوكيل** الخاص بالوكيل — وهو صفحة محادثة عامة واحدة على عنوان الوكيل نفسه، تُفعَّل في الخطوة الأخيرة من الإعداد الأولي (**جرّبه على هاتفك**) وفي تبويب **العرض** بصفحة الوكيل. ومن الخيارات الأخرى موقع أحد العملاء الذي يتضمن التضمين.

## لوكلاء البرمجة [#لوكلاء-البرمجة]

هل تثبّت هذا على موقع أحد العملاء باستخدام Claude Code أو Cursor أو Codex؟ انسخ `skills/embed-agent/SKILL.md` من مستودع Make Agent Fast إلى `.cursor/skills/embed-agent/` أو `.claude/skills/embed-agent/`. هذا الملف هو وصفة التثبيت (السمات وCSP والموضع). وتبقى هذه الصفحة الدليل المخصص للبشر.

---

# React وNext.js

Source: /ar/docs/embed/react-next.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;React&#x22;, icon: &#x22;react&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## تجهيز النطاقات ونطاق التطبيق [#تجهيز-النطاقات-ونطاق-التطبيق]

فعّل خيار **إظهاره على موقعي** للـ agent (صفحة الـ agent ← **انشره الآن** ← **أداة الموقع**)، وأضف عناوين النطاقات (origins) المحلية وعناوين المعاينة والإنتاج بدقة ضمن **عناوين المواقع المسموح بها**. حدّد ما إذا كان يجب أن تبقى أيقونة التشغيل ظاهرة عند كل تنقّل داخل العميل (التخطيط الجذري)، أم أن تظهر فقط ضمن مسارات محددة (تخطيط أو مكوّن متداخل).

## Next.js App Router [#nextjs-app-router]

استخدم `next/script` في مكوّن يعرضه التخطيط الذي يملك أيقونة التشغيل. المعرّف المختصر (slug) آمن للكشف عنه؛ لا تستخدم مفتاح API ولا متغير بيئة سرّيًا.

```tsx
import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20261022-open"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
    />
  );
}
```

اعرض `<AgentEmbed />` مرة واحدة في `app/layout.tsx` للحصول على agent يعمل في الموقع بالكامل، أو في تخطيط متداخل لمجموعة مسارات. لا تعرض نسخة منفصلة من كل مكوّن صفحة. الاستراتيجية `afterInteractive` تتجنب الوصول إلى DOM من جهة الخادم ولا تعطّل تحليل HTML الأولي.

في Next.js Pages Router، اعرض المكوّن نفسه مرة واحدة من `pages/_app.tsx` للحصول على سلوك يشمل الموقع كله. لا يكون عرضه من صفحة بعينها مناسبًا إلا عندما يجب إزالة الـ agent بمجرد مغادرة تلك الصفحة؛ وفي هذه الحالة استخدم نمط التأثير/التنظيف الصريح أدناه، لأن السكربت الخارجي بعد تحميله يكون قد أنشأ عناصر DOM خارج شجرة React.

## React بدون Next.js [#react-بدون-nextjs]

أنشئ السكربت داخل تأثير (effect). يمنع معرّف السكربت الثابت الإدراج المكرر في وضع Strict Mode أثناء التطوير. إذا كان المكوّن مرتبطًا بمسار معين، فيجب أن يزيل التنظيف كلًا من السكربت والعنصر الجذري الذي أنشأه المُحمِّل.

```tsx
import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}
```

لعرض أيقونة التشغيل في الموقع بالكامل، ثبّت هذا المكوّن فوق جهاز التوجيه (router) وتجنّب إلغاء التثبيت المرتبط بالمسارات. يحافظ إبقاء العنصر الجذري على iframe والمحادثة أثناء التنقّل.

## إعداد البيئة [#إعداد-البيئة]

يمكن لمتغير عام يُحدَّد وقت البناء أن يحمل **الـ slug** لأنه ليس سريًا. تحقّق منه قبل العرض، وأبقِ مفاتيح MAF API الحقيقية وبيانات اعتماد المزوّدين على الخادم فقط. عند غياب الـ slug يحذّر المُحمِّل ثم يتوقف بدلًا من إنشاء أيقونة تشغيل.

إذا كان تطبيقك يخدم عدة مستأجرين (tenants) من عملائك عبر بناء React واحد، فلا تغيّر `data-agent` في سكربت نُفِّذ بالفعل. امنح المستأجر الحالي slug ثابتًا واحدًا، وأزل العنصر الجذري الخاص بالـ slug القديم أثناء تبديل المستأجر بعد المصادقة، ثم ثبّت سكربتًا جديدًا. لا تسمح أبدًا لمعامل استعلام غير موثوق باختيار slug يعود إلى مستأجر آخر.

## التحقق من الترطيب (hydration) والتنقّل [#التحقق-من-الترطيب-hydration-والتنقّل]

1. حمّل مسارًا عامًا مباشرة وتأكد من ظهور أيقونة تشغيل واحدة.
2. تنقّل من جهة العميل عبر المسارات التي يجب أن تحتفظ بها.
3. في التثبيت المتداخل أو المرتبط بمسار، اخرج من المسار وتأكد من اختفاء السكربت والعنصر الجذري معًا، ثم عُد وتأكد من ظهور أيقونة تشغيل جديدة واحدة.
4. افحص Network وCSP، وجرّب إرسال رسالة حقيقية.
5. شغّل بناء الإنتاج؛ فوضع Strict Mode في التطوير وحده لا يمثل السلوك النهائي.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                     | الحل                                                                   |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| `document is not defined`                   | نُفّذ كود DOM أثناء SSR؛ انقله إلى `useEffect` أو استخدم `next/script` |
| ظهور أيقونتي تشغيل أو agent اثنين           | هناك عدة slugs أو مكوّنات مثبّتة؛ أبقِ تخطيطًا واحدًا مالكًا           |
| تبقى أيقونة التشغيل بعد مغادرة المسار       | أزل `maf-embed-root-SLUG` في التنظيف، وليس السكربت فقط                 |
| تختفي أيقونة التشغيل عند كل تنقّل           | ثبّتها في مستوى أعلى من شجرة التخطيط أو جهاز التوجيه                   |
| يعمل محليًا لكن لا يعمل في المعاينة/الإنتاج | أضف عنوان النطاق (origin) الدقيق لكل عملية نشر إلى قائمة السماح        |

لا يتوفر حاليًا محوّل npm لـ React/Next منشور؛ تستخدم هذه الأمثلة المُحمِّل العام المدعوم الذي لا يعتمد على REST.

---

# الأمان وسياسة CSP

Source: /ar/docs/embed/security.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; },
{ href: &#x22;/ar/docs/build/appearance&#x22;, label: 'المظهر', icon: &#x22;spark&#x22; }
]"
/>

## قائمة السماح بالأصول [#قائمة-السماح-بالأصول]

يفشل التضمين افتراضيًا (إغلاق عند الفشل) ما لم يكن التضمين مفعَّلًا وكان أصل الصفحة الأم في المتصفح مسموحًا به تمامًا. الأصل (origin) هو `scheme://hostname[:port]`؛ أما المسارات وسلاسل الاستعلام فليست جزءًا منه.

| صفحة الموقع المضيف                      | القيمة في قائمة السماح             |
| --------------------------------------- | ---------------------------------- |
| `https://example.com/pricing`           | `https://example.com`              |
| `https://www.example.com/help`          | `https://www.example.com`          |
| `https://preview.example.com:8443/demo` | `https://preview.example.com:8443` |
| `http://localhost:3000`                 | `http://localhost:3000`            |

أضف أصول الإنتاج والمعاينة والتطوير المحلي كلًّا على حدة. لا تضف حرفًا بديلًا (wildcard) لحل خطأ في التثبيت: فبخلاف ذلك يمكن لأي شخص ينسخ المعرّف العام (slug) أن يضمّن الوكيل ويستهلك الرصيد (Credits) الخاص بالموقع.

## سياسة أمان المحتوى (CSP) [#سياسة-أمان-المحتوى-csp]

يحتاج المحمِّل (loader) إلى إذن للسكربت، وتحتاج أداة الدردشة إلى إذن للإطار، وقد يحتاج طلب المظهر الذي يرسله المحمِّل إلى إذن للاتصال. ادمج هذه المصادر في التوجيهات الحالية لدى الموقع المضيف، ولا تستبدل سياسة مكتملة بهذا المثال المختصر.

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

إذا كان الموقع يستخدم `script-src-elem`، فأضف `https://makeagent.fast` إليه أيضًا. لا يتطلب المحمِّل الخارجي `unsafe-inline`، لكن إطار العمل الخاص بالموقع المضيف قد تكون له متطلبات مستقلة تخص nonce أو التجزئة (hash). تفيد سياسة «الإبلاغ فقط» (report-only) أثناء الاختبار:

```http
Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;
```

عندما تُبلغ وحدة تحكم المتصفح عن انتهاك لسياسة CSP، عدّل التوجيه المذكور تحديدًا، لا `default-src` بشكل واسع، ثم أعد اختبار الصفحة العامة.

## الميكروفون وأذونات المتصفح [#الميكروفون-وأذونات-المتصفح]

ينشئ المحمِّل الإطار (iframe) بالسمة `allow="microphone; autoplay; clipboard-write"`. ومع ذلك قد تتجاوز سياسة أذونات (Permissions Policy) أكثر صرامة على مستوى الموقع المضيف هذا الإذن. إذا كان الصوت مفعَّلًا، فاسمح بأصل إطار Make Agent Fast في استجابة الموقع المضيف:

```http
Permissions-Policy: microphone=(self "https://makeagent.fast")
```

يجب أيضًا أن يمنح الزائر إذن الوصول إلى الميكروفون في المتصفح. اختبر عبر HTTPS؛ إذ تقيّد المتصفحات عادةً الوصول إلى الميكروفون على الأصول العامة غير الآمنة. أما الدردشة النصية فلا تتطلب إذن الميكروفون.

## حدود الرسائل والإطار [#حدود-الرسائل-والإطار]

يقبل المحمِّل فقط الرسائل `maf:ready` و`maf:open` و`maf:close` ورسائل دورة حياة السمة المرتبطة بمعرّف الموقع (slug) الحالي. ويجري التحقق من رسائل الإطار الواردة مقابل `https://makeagent.fast`. لا تنسخ المحمِّل إلى حزمتك الخاصة ولا تزل التحقق من الأصل هذا.

يجب ألا يحاول الكود في الصفحة المضيفة الوصول إلى DOM الخاص بالإطار. فالإطار عابر للأصول (cross-origin) بالتصميم، وسطح التكامل المدعوم هو المحمِّل وسمات `data-*` الموثقة له وطرق تعريف الهوية الموضحة أدناه.

## الأسرار وهوية الزائر [#الأسرار-وهوية-الزائر]

معرّف الموقع (slug) ورابط المحمِّل عامّان. أما كل ما عدا ذلك فيجب إبقاؤه خارج مصدر الصفحة:

* لا تضف أبدًا مفتاح MAF API أو رمز OAuth أو مفتاح مزوّد الذكاء الاصطناعي أو رمز موصِّل (Connector) أو سرّ webhook إلى المقتطف.
* لا تضمّن أي سرّ داخل حزمة JavaScript ولا تكشفه عبر `NEXT_PUBLIC_*` أو `VITE_*` أو متغيرات بيئة المتصفح المشابهة.
* استخدم تكاملًا مع API من جهة الخادم عندما يحتاج تطبيقك إلى إنشاء مواقع أو تحديث وكلاء أو جلب بيانات مساحة العمل الخاصة.
* لا تضع عناوين البريد الإلكتروني أو معرّفات الحسابات أو أي بيانات أخرى عن الزائر في `data-label` أو `data-locale` أو معلمات الاستعلام.

## تعريف العملاء المسجَّلين دخولهم [#تعريف-العملاء-المسجَّلين-دخولهم]

في **الوكيل ← الإجراءات ← العملاء المسجَّلون دخولهم**، أنشئ سرًّا وانسخه عند ظهوره. احفظه على خادمك فقط باسم `MAF_SECRET_KEY`؛ ولا تضعه أبدًا في كود المتصفح أو متغيرات البيئة العامة أو المستودع. هذا السر الخاص بالوكيل منفصل عن مفتاح API الخاص بمساحة العمل. يؤدي تدويره إلى إبطال الرموز القديمة ويغيّر مفتاح التوقيع الخاص بـ[عمليات البحث (Lookups)](/ar/docs/build/lookups)؛ أما حذفه فيعطّل هوية العميل الموثّقة وعمليات البحث إلى أن يُهيَّأ سر جديد.

استخدم رابط المحمِّل المحدَّث `https://makeagent.fast/embed.js?v=20261022-open` في المقتطف الحالي لديك. قد تبقى الروابط القديمة ذات الإصدارات مخزَّنة مؤقتًا لمدة عام ولا توفّر هذا الـSDK. حافظ على قائمة السماح بالأصول وعلى حمايات CSP.

ينبغي لخادمك الموثَّق إصدار الرمز اعتمادًا على العميل من جلسته الخاصة. لا تقبل أبدًا معرّف عميل عشوائيًا قادمًا من المتصفح ليكون الهوية التي تُوقَّع. تعمل هذه الدالة المساعدة **على الخادم فقط**:

```js
import { createHmac } from "node:crypto";

export function signCustomerIdentity(customer) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const now = Math.floor(Date.now() / 1000);
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    sub: customer.id,
    email: customer.email,
    name: customer.name,
    iat: now,
    exp: now + 3600,
  });
  const body = `${header}.${payload}`;
  const signature = createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}
```

يجب أن يتضمن الترويس `alg: "HS256"` و`typ: "JWT"`. والحقل `sub` سلسلة نصية ثابتة غير فارغة بطول لا يتجاوز 128 حرفًا؛ و`exp` طابع زمني Unix صحيح بالثواني، في المستقبل وبما لا يتجاوز 24 ساعة من الآن. أما `iat` الاختياري فيجب أن يكون عددًا صحيحًا؛ و`email` الاختياري يجب أن يكون صالحًا وبطول لا يتجاوز 160 حرفًا؛ و`name` الاختياري بطول لا يتجاوز 120 حرفًا. ويجب أن يتسع الرمز الكامل ضمن 2,048 حرفًا. احذف المطالبات الاختيارية التي لا تحتاج إليها. حمولات JWT موقَّعة وليست مشفَّرة.

أعد الرمز فقط إلى جلسة المتصفح الموثَّقة تلك عبر HTTPS، مع `Cache-Control: no-store`. لا تسجّله في السجلات ولا تضفه إلى الروابط ولا تخزّنه في localStorage. بعد تحميل `embed.js`، مرّر رمز الاستجابة هذا إلى الأداة:

```js
window.MakeAgentFast.identify(token);
```

للتهيئة قبل تشغيل المحمِّل، اضبط `window.MakeAgentFastSettings = { identityToken: token }` في مرحلة إقلاع تطبيقك بدلًا من ذلك. يحتفظ المحمِّل بأحدث رمز في الذاكرة ويمرّره عندما يكون الإطار جاهزًا. جدّد الرمز من خادمك الموثَّق قبل انتهاء صلاحيته واستدعِ `identify` مرة أخرى. يتضمنه كل طلب دردشة؛ وتستخدم طلبات المحادثة الترويس `x-maf-identity`. ولا تعتمد هوية المضيف الموثّقة أبدًا على ملف تعريف الارتباط `af_xid`.

عند تسجيل الخروج من تطبيقك، استدعِ ما يلي قبل عرض دردشة حساب آخر، وامسح أي رمز إقلاع احتفظ به تطبيقك:

```js
window.MakeAgentFast.logout();
```

يعيد هذا ضبط هوية الأداة وذاكرة المحادثات المحلية المؤقتة؛ لكنه لا يسجّل خروج العميل من تطبيقك ولا يلغي رمزًا جرى نسخه. كما أن `sub` لعميل مختلف يمسح ذاكرة الأداة المؤقتة أيضًا. لا يمكن للرموز غير الصالحة أو المنتهية أو الخاصة بوكيل آخر الوصول إلى سجل ذلك العميل المسجَّل دخوله، وتعود إلى مسار الزائر العادي. استخدم مدد صلاحية قصيرة وأبقِ سر كل وكيل منفصلًا. تتجاهل تجربة المالك (Owner rehearsal) رموز الهوية؛ لذا تحقق من العزل على التضمين الفعلي باستخدام حسابَي اختبار منفصلَين.

## الموافقة والخصوصية والاحتفاظ بالبيانات [#الموافقة-والخصوصية-والاحتفاظ-بالبيانات]

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

أخبر الزوار عندما تستخدم التجربة الذكاء الاصطناعي أو تسجيل الميكروفون أو التقاط بيانات العملاء المحتملين (Leads) أو التحليلات أو مزوّد مراسلة خارجيًا، وفق ما تقتضيه سياستك والقانون المعمول به. تأكد من سير عمل الاحتفاظ بالمحادثات وحذفها في موقعك قبل الإطلاق؛ فقطع الاتصال أو إزالة التضمين لا يحذف المحادثات الموجودة بحد ذاته.

## قائمة التحقق الأمنية قبل الإطلاق [#قائمة-التحقق-الأمنية-قبل-الإطلاق]

* موقع العميل منشور، ووكيله المضمَّن مفعَّل ومختبَر.
* تُدرج في قائمة السماح الأصول الأم المقصودة بدقة فقط.
* تسمح سياسة CSP للموقع المضيف بالسكربت والإطار وطلب المظهر دون أحرف بديلة واسعة.
* يُسمح بالميكروفون فقط إذا كان الصوت مفعَّلًا وتم اختباره عبر HTTPS.
* لا تظهر أي بيانات اعتماد أو قيم خاصة بالزوار في HTML أو مخرجات الحزمة أو سجلات المتصفح.
* جرى اختبار سلوك مدير الموافقة قبل الموافقة وبعدها.
* يفشل المقتطف المنسوخ على أي أصل غير مُدرج في قائمة السماح.

---

# Shopify

Source: /ar/docs/embed/shopify.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Shopify&#x22;, icon: &#x22;shopify&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## توفر theme app extension [#توفر-theme-app-extension]

يوجد المصدر البرمجي لـ theme app extension في المسار `integrations/shopify`. وهو قالب مخصص للتطوير وليس تطبيقًا عامًا متاحًا في متجر تطبيقات Shopify (Shopify App Store). ويجب على حساب Partner مخوَّل وضعه داخل هيكل تطبيق (app shell) ونشره واستكمال مراجعة Shopify قبل أن يتمكن التجار من تثبيته من متجر التطبيقات.

## Custom Liquid [#custom-liquid]

من **Online Store → Themes → Customize**، أضف كتلة Custom Liquid حيثما كان ذلك مدعومًا، أو عدّل الملف `theme.liquid` وضع السكريبت قبل `</body>`.

```liquid
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

أضف الأصل (origin) الأساسي للمتجر إلى قائمة السماح. قد تختلف أسماء المضيف المخصصة للمعاينة عن `myshopify.com` المباشر أو عن اسم المضيف المباشر الخاص بالمتجر، ويجب إضافتها بشكل منفصل لأغراض الاختبار.

## تغييرات القالب [#تغييرات-القالب]

أعد التحقق من تضمين التطبيق (app embed) بعد نشر قالب جديد. اختبر زر فتح المحادثة (launcher) بالقرب من أدراج سلة التسوق ولافتات الموافقة وقائمة التنقل على الجوال، حتى لا تتداخل العناصر الثابتة.

---

# Squarespace

Source: /ar/docs/embed/squarespace.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Squarespace&#x22;, icon: &#x22;squarespace&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

للحصول على زر تشغيل يظهر في جميع صفحات الموقع، الصق المقتطف البرمجي في **الإعدادات ← متقدم ← حقن الشيفرة ← التذييل** إذا كانت باقة Squarespace لديك تدعم ذلك.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

لعرض الأداة في صفحات محددة فقط، استخدم كتلة شيفرة مدعومة أو حقنًا خاصًا بالصفحة. اختبر الأداة بعد الحفظ وعلى النطاق العام للموقع، فقد يمنع وضع المحرر تشغيل السكربتات المخصصة.

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

---

# SvelteKit

Source: /ar/docs/embed/sveltekit.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;SvelteKit&#x22;, icon: &#x22;svelte&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وسياسة CSP', icon: &#x22;shield&#x22; }
]"
/>

## تجهيز المصدر [#تجهيز-المصدر]

فعّل خيار **اعرضه على موقعي** للوكيل (صفحة الوكيل ← **ابدأ النشر** ← **أداة الموقع**)، ثم أضف كل مصدر (origin) دقيق لبيئات التطوير والمعاينة والإنتاج في SvelteKit ضمن **عناوين المواقع المسموح بها**. استخدم تخطيطًا جذريًا (root layout) للحصول على أيقونة تشغيل تظهر في الموقع كله، أو استخدم تخطيطًا فرعيًا أو مكوّن صفحة لمسارات محددة.

## إنشاء المكوّن [#إنشاء-المكوّن]

لا يعمل `onMount` إلا في المتصفح. أعد دالة تنظيف عندما يكون من الممكن إلغاء تركيب التخطيط أو المكوّن المالك.

```svelte
<script lang="ts">
  import { onMount } from "svelte";

  const slug = "YOUR_SITE_SLUG";

  onMount(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  });
</script>
```

ركّب المكوّن مرة واحدة من `src/routes/+layout.svelte` ليشمل التطبيق بأكمله. أما لمجموعة مسارات (route group)، فضعه في ملف `+layout.svelte` الخاص بتلك المجموعة؛ إذ تزيل دالة التنظيف أيقونة التشغيل عندما يغادر الزائر المجموعة.

## استخدام الإعدادات بأمان [#استخدام-الإعدادات-بأمان]

يمكن أن يكون معرّف الموقع العام (slug) قيمة بيئة عامة في SvelteKit لأنه ليس بيانات اعتماد. لا تستخدم `$env/static/public` أو كود المتصفح لمفاتيح MAF API أو مفاتيح مزوّدي الذكاء الاصطناعي أو أسرار الموصّلات. احتفظ بها في وحدات أو مسارات تعمل على الخادم فقط.

## الحفاظ على حالة المحادثة أو إعادة ضبطها [#الحفاظ-على-حالة-المحادثة-أو-إعادة-ضبطها]

يحافظ إبقاء المكوّن في التخطيط الجذري على الـ iframe نفسه عبر التنقل من جهة العميل. أما التنظيف المرتبط بمسار معيّن فيتخلص عمدًا من ذلك الـ iframe ومن حالته الحالية داخل الصفحة. اختر سلوكًا واحدًا بدلًا من إعادة التركيب في كل صفحة.

## التحقق من نسخة الإنتاج [#التحقق-من-نسخة-الإنتاج]

1. شغّل محوّل (adapter) الإنتاج أو عملية البناء في SvelteKit.
2. حمّل المسار العام مباشرة وتأكد من وجود أيقونة تشغيل واحدة وعنصر جذري واحد.
3. تنقّل إلى التخطيط المالك ثم اخرج منه.
4. افحص Network/CSP والمصدر الأب (parent origin) الدقيق.
5. جرّب رسالة حقيقية وعرضًا ضيقًا، واختبر الميكروفون عند تفعيله.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                | الحل                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------- |
| خطأ `document` أثناء SSR               | أبقِ كل كود التحميل داخل `onMount`                                        |
| تبقى أيقونة التشغيل بعد مغادرة التخطيط | أعد دالة تنظيف وأزل العنصر الجذري الذي تم إنشاؤه                          |
| تُعاد ضبط المحادثة في كل صفحة          | ركّب المكوّن في `+layout.svelte` أب دائم                                  |
| يمنع حارس التكرار التركيب الجديد       | تأكد من أن التنظيف السابق أزال العنصر الجذري القديم قبل إضافة سكربت جديد  |
| يفشل في الإنتاج فقط                    | أضف مصدر HTTPS النهائي إلى قائمة السماح وافحص ترويسات CSP الخاصة بالمحوّل |

لا يتوفر حاليًا محوّل SvelteKit منشور عبر npm؛ والسكربت المستضاف هو واجهة التكامل المدعومة.

---

# Tilda

Source: /ar/docs/embed/tilda.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Tilda&#x22;, icon: &#x22;html&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

تنشر Tilda نسخة ثابتة (static export) من موقعك، لذلك يتم تثبيت زر الودجت عبر ميزة الأكواد المخصصة في Tilda نفسها. لا يوجد تطبيق لـ Make Agent Fast في كتالوج Tilda. أسماء القوائم هنا صحيحة حتى تاريخ 2026-09؛ وإذا تغيّر موضع أي عنصر، فابحث عن الإعداد بحسب وظيفته لا بحسب مساره الدقيق.

## إضافة المُحمِّل (loader) [#إضافة-المُحمِّل-loader]

1. في لوحة تحكم Make Agent Fast، افتح **انشره الآن** ← **ودجت الموقع** في صفحة الـ agent، وفعّل خيار **إظهاره على موقعي**، ثم أضف إلى **عناوين المواقع المسموح بها** كل origin تقدّم منه Tilda موقعك — أي نطاقك المخصص، وكذلك عنوان المعاينة `tilda.ws` الخاص بالمشروع أثناء الاختبار.
2. افتح إعدادات الموقع للمشروع وابحث عن قسم الأكواد المخصصة / حقن HTML: وهي الحقول التي تضيف الشيفرة إلى وسم `<head>` في كل صفحة أو قبل وسم إغلاق body مباشرة. يعتمد توفر هذه الميزة على باقة Tilda التي تستخدمها.
3. الصق الشيفرة التي تم إنشاؤها في حقل head. المُحمِّل يعمل بوضع `async`، لذا يصلح الوضع في head أو في نهاية body.
4. احفظ، ثم أعد نشر الصفحات التي يجب أن يظهر عليها زر الودجت. تقدّم Tilda نسخة ثابتة، ولذلك لا يصل الكود المضاف على مستوى الموقع إلى الزوار إلا بعد إعادة النشر.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

إذا لم تجد هذا الإعداد، فالصق الشيفرة في كتلة التذييل (footer) الخاصة بالقالب بدلًا من ذلك. تضيف كتلة HTML في Tilda زر الودجت إلى الصفحة الوحيدة التي تحتويها، وهذه أيضًا هي الطريقة المناسبة لقصر ظهور الـ agent على صفحة هبوط واحدة.

## التحقق [#التحقق]

1. افتح الرابط المنشور في نافذة خاصة، وليس في محرر Tilda. فقد يمنع وضعا المحرر والمعاينة تشغيل السكربتات المحقونة.
2. تأكد من أن origin الظاهر في شريط العنوان هو الذي أضفته إلى القائمة المسموح بها، بما في ذلك `www` إذا كان النطاق يعيد التوجيه إليه.
3. تأكد من أن `embed.js` يعيد الرمز `200` في لوحة Network، وأن عنصرًا واحدًا فقط من النوع `data-maf-embed="YOUR_SITE_SLUG"` موجود.
4. اطرح سؤالًا واقعيًا وتأكد من ظهور الرسالة في **المحادثات**.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                              | السبب المحتمل                                                            | الحل                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| يظهر زر الودجت في المحرر ولا يظهر في الصفحة المنشورة | لم تتم إعادة نشر الصفحات بعد حفظ الكود على مستوى الموقع                  | أعد نشر كل صفحة يجب أن يظهر عليها الزر                                  |
| يتم تحميل الزر لكن إطار الدردشة يرفض الفتح           | الـ origin المنشور غير مضاف إلى القائمة المسموح بها، أو أن التضمين معطّل | أضف الـ origin المنشور بالضبط، وأعد التحقق من خيار **إظهاره على موقعي** |
| تظهر الشيفرة في صفحة واحدة فقط                       | تمت إضافتها عبر كتلة HTML على مستوى الصفحة                               | انقلها إلى حقل الحقن في head على مستوى الموقع                           |

قد تؤخّر خيارات الموافقة على ملفات تعريف الارتباط وسرعة الصفحة في Tilda تحميل السكربتات الخارجية. إذا كان تقييد التحميل بالموافقة مفعّلًا، فحمّل الـ embed ضمن الفئة التي تخصصها سياستك له، وراجع [الأمان وCSP](/ar/docs/embed/security) لمعرفة الـ origins التي يجب السماح بها.

---

# Vue وNuxt

Source: /ar/docs/embed/vue-nuxt.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Vue&#x22;, icon: &#x22;vue&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## تجهيز التضمين [#تجهيز-التضمين]

فعّل خيار **Show it on my website** للـ agent (صفحة الـ agent ← **Put it live** ← **Website widget**)، وأضف الأصل (origin) الدقيق لبيئات التطوير المحلي والمعاينة والإنتاج ضمن **Allowed website addresses**. وحدِّد ما إذا كان الـ agent سيخدم التطبيق بأكمله أم مكوّنات مسارات محددة فقط.

## إضافة Nuxt على مستوى الموقع [#إضافة-nuxt-على-مستوى-الموقع]

أنشئ إضافة بصيغة `.client.ts` حتى لا يُنفَّذ أي كود يتعامل مع DOM أثناء العرض على الخادم. يحمّلها Nuxt مرة واحدة في المتصفح، مما يُبقي زر الفتح والمحادثة مستقرَّين أثناء التنقل داخل جانب العميل.

```ts
// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "Ask us";
  script.async = true;
  document.body.appendChild(script);
});
```

لا تضع أي سرّ في `runtimeConfig.public`؛ فالمعرّف العام للموقع (site slug) والإعدادات المرئية فقط هي ما يجوز أن يصل إلى المتصفح. أما مفاتيح MAF API ومفاتيح المزوّدين الحقيقية فتبقى في إعدادات التشغيل الخاصة بالخادم.

لا تتضمن الإضافة على مستوى الموقع تنظيفًا عند إلغاء التركيب عمدًا، لأنها ترتبط بدورة حياة تطبيق Nuxt. أثناء استبدال الوحدات الفوري (HMR) في بيئة التطوير، قد يبقى الجذر السابق إلى أن تعيد تحميل الصفحة بالكامل؛ ويمنع فحص الجذر ظهور زر فتح ثانٍ. تحقّق من السلوك النهائي باستخدام نسخة إنتاج نظيفة بدلًا من تعديل الإضافة مرارًا في علامة تبويب واحدة طويلة العمر.

## مكوّن Vue خاص بمسار محدد [#مكوّن-vue-خاص-بمسار-محدد]

للمسارات المحددة، ثبّت الأداة في `onMounted` واحذف السكربت والجذر المُنشأ في `onBeforeUnmount`.

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20261022-open";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>
```

اجعل مكوّنًا واحدًا فقط هو المسؤول عن التضمين. استخدام عدة مكوّنات بمعرّفات (slugs) مختلفة ينشئ عدة agents عمدًا، وهو أمر نادرًا ما يكون مرغوبًا.

إذا بدّل تطبيق Vue بين مستأجرين (tenants) مصادَقين دون إعادة تحميل كاملة للصفحة، فتعامل مع ذلك على أنه إزالة وإعادة تركيب صريحتان. احذف جذر المعرّف (slug) القديم، وتحقّق من المعرّف العام للمستأجر الجديد اعتمادًا على حالة تطبيق موثوقة، ثم أضف سكربتًا جديدًا. تغيير `script.dataset.agent` بعد تشغيل أداة التحميل لا يعيد توجيه الـ iframe الموجود.

تظل ترويسات الأمان الخاصة بالموقع المضيف سارية على مخرجات Nuxt/Vue. أضف أصل أداة التحميل والإطار إلى CSP، واسمح بالميكروفون فقط عند تفعيل الصوت؛ فالإضافة التي تعمل في جانب العميل فقط لا يمكنها تجاوز سياسة المتصفح المحددة على مستوى الاستجابة.

## التحقق من SSR والتوجيه [#التحقق-من-ssr-والتوجيه]

1. شغّل نسخة الإنتاج من Nuxt/Vue وتأكد من عدم ظهور الخطأ `document is not defined`.
2. حمّل مباشرةً مسارًا يحتوي على التضمين وتأكد من وجود جذر واحد.
3. تنقّل داخل جانب العميل وتأكد من السلوك المطلوب: على مستوى الموقع أو على مستوى المسار.
4. افحص `embed.js` وiframe وCSP والأصل (origin) الدقيق.
5. أرسل رسالة واختبر السلوك على الجوال والميكروفون.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                         | الحل                                                                         |
| ------------------------------- | ---------------------------------------------------------------------------- |
| تعطّل SSR                       | أعد تسمية إضافة Nuxt إلى `.client.ts` أو أبقِ العمل على DOM داخل `onMounted` |
| يبقى زر الفتح بعد مغادرة المسار | احذف الجذر الخاص بالمعرّف (slug) في `onBeforeUnmount`                        |
| يُعاد ضبط زر الفتح مع كل مسار   | استخدم إضافة العميل أو التخطيط (layout) على مستوى الموقع بدلًا من مكوّن صفحة |
| يفشل نطاق المعاينة              | أضف أصل HTTPS هذا بالضبط بشكل منفصل                                          |
| يُدرَج السكربت مرتين            | استخدم مالكًا واحدًا ثابتًا مع فحص الجذر/المعرّف (ID)                        |

لا يوجد حاليًا محوّل npm منشور لـ Vue/Nuxt؛ يستخدم هذا الدليل أداة التحميل المستضافة المدعومة مباشرةً.

---

# Webflow

Source: /ar/docs/embed/webflow.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Webflow&#x22;, icon: &#x22;webflow&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## التوفر [#التوفر]

التكامل المدعوم حاليًا هو الشيفرة المخصصة. لا يوجد اليوم تطبيق عام لـ Make Agent Fast في Webflow Marketplace. يحتوي المجلد `integrations/webflow` في المستودع على مقتطف الشيفرة نفسه الخاص بالتذييل والمعروض أدناه، وليس تطبيق Webflow أصليًا.

## الشيفرة المخصصة [#الشيفرة-المخصصة]

أضف النص البرمجي الذي تم إنشاؤه إلى **إعدادات الموقع ← الشيفرة المخصصة ← شيفرة التذييل**، ثم انشر الموقع.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

قد لا تُنفَّذ الشيفرة المخصصة داخل معاينة Webflow Designer. اختبر نطاقات الاختبار (staging) والإنتاج المنشورة، وأضف كل أصل (origin) تستخدمه إلى قائمة السماح.

---

# Wix

Source: /ar/docs/embed/wix.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;Wix&#x22;, icon: &#x22;wix&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## توفر العنصر المخصص [#توفر-العنصر-المخصص]

استخدم العنصر المخصص في الملف `integrations/wix/make-agent-fast.js` أو واجهة الشيفرة المخصصة المعتمدة في Wix والمخصصة لنهاية الجسم (body-end). هذا المصدر ليس تطبيقًا منشورًا في متجر تطبيقات Wix (Wix App Market) للعموم. لن يظهر رابط الإدراج هنا إلا بعد أن تعتمد المراجعة الخارجية التطبيق وتنشره.

## الشيفرة المخصصة [#الشيفرة-المخصصة]

في إعدادات الموقع، أضف أداة التحميل (loader) التي تم إنشاؤها كشيفرة مخصصة في نهاية الجسم (body-end)، ثم طبّقها على الصفحات المطلوبة.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

قد تقدّم Wix المعاينة والموقع المباشر على نطاقات مختلفة. أضف فقط النطاقات التي تحتاج إليها في **عناوين المواقع المسموح بها**، ثم أعد النشر بعد أي تغيير.

---

# WordPress

Source: /ar/docs/embed/wordpress.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: 'نظرة عامة على التضمين', icon: &#x22;embed&#x22; },
{ label: &#x22;WordPress&#x22;, icon: &#x22;wordpress&#x22; },
{ href: &#x22;/ar/docs/embed/security&#x22;, label: 'الأمان وCSP', icon: &#x22;shield&#x22; }
]"
/>

## مصدر الإضافة للتثبيت اليدوي [#مصدر-الإضافة-للتثبيت-اليدوي]

يوجد مصدر الإضافة القابل للتثبيت يدويًا في المسار `integrations/wordpress/make-agent-fast`. هذه الإضافة غير مدرجة في دليل WordPress.org. قم بضغط هذا المجلد بصيغة zip، ثم ارفعه من **الإضافات ← أضف جديدًا ← رفع إضافة**، ثم اضبط المعرّف المنشور (slug) من **الإعدادات ← Make Agent Fast**. سيظهر رابط الدليل هنا فقط بعد موافقة المراجعة الخارجية.

## HTML مخصّص [#html-مخصّص]

إذا اخترت التثبيت اليدوي، فأضِف السكربت القياسي باستخدام قالب فرعي (child theme)، أو أداة موثوقة لإضافة سكربتات الترويسة/التذييل، أو كتلة HTML مخصّص تتيحها خطة WordPress الخاصة بك.

```html
<script src="https://makeagent.fast/embed.js?v=20261022-open"
        data-agent="YOUR_SITE_SLUG"
        async></script>
```

أضف كلًّا من نطاق الإنتاج (origin) وأي نطاق تجريبي (staging) منفصل إلى قائمة السماح في لوحة التحكم. وامسح ذاكرة التخزين المؤقت للصفحات وشبكة CDN بعد تغيير المقتطف.

<Callout title="تجنّب تعديل القالب الأب">
  قد يؤدي تحديث القالب الأب إلى الكتابة فوق التعديلات المباشرة. استخدم الإضافة اليدوية أو قالبًا فرعيًا للحصول على تثبيت دائم.
</Callout>

---

# المفاهيم الأساسية

Source: /ar/docs/getting-started/concepts.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;site&#x22;, title: &#x22;الموقع&#x22;, description: &#x22;وحدة مساحة العمل: الوكيل، وعرض الأداة، والمعرفة، والتضمين، ورابط الوكيل، ونقاط الدخول عبر المراسلة. المعرّف المختصر (slug) هو معرّف التضمين.&#x22; },
{ icon: &#x22;chat&#x22;, title: &#x22;الوكيل&#x22;, description: &#x22;الهوية والتعليمات واللغات والشخصية الصوتية والنصية التي يتعامل معها الزوار.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;المعرفة&#x22;, description: &#x22;عناوين URL والملفات والملاحظات والأسئلة الشائعة والمنتجات التي تستند إليها الإجابات.&#x22; },
{ icon: &#x22;connectors&#x22;, title: &#x22;القنوات&#x22;, description: &#x22;أدوات التضمين وموصّلات المراسلة التي تقدّم الوكيل نفسه في أماكن أخرى.&#x22; },
{ icon: &#x22;layers&#x22;, title: &#x22;الرصيد&#x22;, description: &#x22;وحدات قياس لاستخدام النماذج والصوت والمنصة ضمن خطتك.&#x22; }
]"
/>

## مساحة العمل [#مساحة-العمل]

حسابك هو حدّ مساحة العمل الذي يضم المواقع والفوترة وبيانات اعتماد API وعمليات الفريق. لا يمنحك الوصول إلى مساحة عمل واحدة أي وصول إلى مساحة عمل أخرى.

## الموقع [#الموقع]

الموقع هو وحدة مساحة العمل. يملك الموقع الوكيل الخاص به، وإعدادات عرض الأداة، والمعرفة، والموصّلات، والتحليلات، والمحادثات. يمكن أن تحدّ الخطة من عدد المواقع التي يمكنك إبقاؤها نشطة. النطاقات المخصصة غير متاحة. المعرّف المختصر العام (slug) هو معرّف التضمين (`data-agent`) وعنوان صفحة الدردشة الخاصة بـ**رابط الوكيل**، وليس نطاقًا تقوم بإعداده.

## الوكيل [#الوكيل]

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

## المعرفة [#المعرفة]

مصادر المعرفة هي مواد مفهرسة مثل الملاحظات وعناوين URL والملفات والأسئلة الشائعة والمنتجات. وهي تدعم الإجابات لكنها لا تحلّ محل التعليمات السلوكية. حدّث المصدر عندما تتغير أي معلومة.

## القناة [#القناة]

القناة هي المكان الذي يتحدث فيه الزائر إلى الوكيل: أداة مضمّنة في موقعك الحالي، أو صفحات العرض التجريبي المستضافة المتبقية، أو الصوت، أو Telegram، أو WhatsApp، أو Messenger، أو Instagram، أو Discord، أو KakaoTalk. تختلف الإمكانات من قناة إلى أخرى.

## الرصيد والاستحقاقات [#الرصيد-والاستحقاقات]

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

## حالة النشر [#حالة-النشر]

يؤدي الإطلاق من عنوان URL إلى إنشاء مسودة غير منشورة. يؤدي الزر **اعرضه على موقعي** ضمن **ضعه حيث يتواجد عملاؤك** (أو من صفحة الوكيل) إلى تفعيل التضمين في موقعك الحالي، ويؤكد **تحقق من موقعي** أن الشيفرة موجودة فعلًا. لا تحصل الوكلاء الجدد على صفحة تسويقية مستضافة. ولا تُنشر اختبارات المالك أبدًا للعامة.

**التفعيل** هو أول محادثة مع زائر أو أول Lead يتم جمعه، وليس اختبارًا يجريه المالك.

تُحفظ تغييرات **العرض** (وشارة العلامة التجارية) تلقائيًا وتُحدّث التضمين المباشر دون إعادة نشر. كما تُحفظ التعليمات تلقائيًا، بينما تُطبَّق المعرفة بمجرد فهرسة المصدر. ويعتمد سلوك الموصّلات والتضمين على حالة الوكيل المنشورة أو المُعدّة حاليًا كما هو موضح في دليل كل ميزة.

---

# جولة في لوحة التحكم

Source: /ar/docs/getting-started/dashboard.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;layers&#x22;, title: &#x22;الصفحة الرئيسية لمساحة العمل&#x22;, description: &#x22;قائمة المواقع وحالة الخطة ونقطة البداية للمشاريع الجديدة.&#x22; },
{ icon: &#x22;build&#x22;, title: &#x22;عناصر التحكم في الوكيل&#x22;, description: &#x22;إيصال الإطلاق، وإعدادات الوكيل والعرض والتثبيت لوكيل واحد.&#x22; },
{ icon: &#x22;chart&#x22;, title: &#x22;أدوات التشغيل&#x22;, description: &#x22;صندوق الوارد والتحليلات والرسائل الجماعية وتحقيق الدخل والاستخدام.&#x22; },
{ icon: &#x22;code&#x22;, title: &#x22;إعدادات المطوّرين&#x22;, description: &#x22;مفاتيح API وwebhooks وتطبيقات OAuth وبيانات اعتماد التكامل.&#x22; }
]"
/>

تُنظَّم لوحة التحكم حول المواقع. استخدم مبدّل المواقع قبل تغيير المحتوى أو بيانات الاعتماد أو إعدادات التشغيل. يؤدي لصق عنوان URL لموقع ويب إلى إنشاء المسودة الأولى في شاشة الإنشاء، وليس في قائمة الصفحة الرئيسية هذه — راجع [إنشاء وكيل](/ar/docs/build/create-agent).

## الوكيل [#الوكيل]

يفتح **الوكيل** على إيصال الإطلاق — ما جرت مراجعته، وأين تم تثبيته، وهل تحدّث إليه أي عميل، ومتى تنتهي الفترة التجريبية — مع الأداة المباشرة بجانبه. تبويباته هي **نظرة عامة** (التعليمات وحالة المعرفة وفحص الإجابات وظهور الوكيل على الموقع)، و**العرض** (مظهر الأداة؛ تُحفظ التغييرات تلقائيًا وتُحدّث التضمين المباشر)، و**الصوت**، و**الإجراءات**. تضم قائمة **أطلِق الوكيل** رمز تثبيت **أداة الموقع** وروابط إلى كل قناة مراسلة. أما **المعرفة** فتضم كل ما يجيب منه الوكيل. وتربط **القنوات** قنوات المراسلة. وتبقى قائمة **البدء** المختصرة إلى أن تجري أول محادثة مع عميل.

## الموقع [#الموقع]

لا توجد صفحة تضمين منفصلة: يوجد رمز التثبيت و**عناوين المواقع المسموح بها** لموقع ويب قائم في **الوكيل ← أطلِق الوكيل ← أداة الموقع**. ويوجد مفتاح **رابط الوكيل** في تبويب **العرض**. ولا توجد ميزة للبناء عبر المحادثة أو لإنشاء موقع. أما الصفحات المستضافة المتبقية، إن وُجدت، فليست منتج الإنشاء.

## النشاط [#النشاط]

تجمع **المحادثات** سلاسل محادثات الويب والموصلات، ويمكنك فيها الرد كشخص. وتتتبّع **التذاكر** طلبات الدعم. وترسل **الرسائل الجماعية** رسائل معتمدة إلى الجمهور، بينما تمثّل **الإشعارات** الخلاصة داخل لوحة التحكم للعملاء المحتملين وعمليات التحويل إلى موظف والحجوزات والموافقات وغيرها من أحداث المالك؛ ويمكن لبطاقة **التنبيهات** فيها عكس الخلاصة إلى Telegram. وتعرض **التحليلات** حركة الزيارات والتفاعل.

## عناصر التحكم في الحساب [#عناصر-التحكم-في-الحساب]

يضم قسم **مساحة العمل** المثبَّت: **كل الوكلاء**، و**الاستخدام والرصيد** (الرصيد وحدود الخطة)، و**مفاتيح مزوّد الذكاء الاصطناعي**، و**المطوّرين**، و**البيانات والخصوصية**. مفاتيح API هي بيانات اعتماد على مستوى الحساب، ولا ينبغي إنشاؤها إلا للتطبيقات التي تثق بها.

<Callout title="تحقق من الموقع النشط">
  يظهر اسم الموقع النشط في مبدّل المواقع. تأكد منه قبل حذف المعرفة أو تدوير أسرار الموصلات أو النشر.
</Callout>

---

# البدء السريع

Source: /ar/docs/getting-started/quickstart.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/create-agent&#x22;, label: &#x22;إنشاء agent&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/ar/docs/build/knowledge&#x22;, label: &#x22;إضافة المعرفة&#x22;, icon: &#x22;book&#x22; },
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: &#x22;التضمين&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/ar/docs/operate/conversations&#x22;, label: &#x22;مراجعة صندوق الوارد&#x22;, icon: &#x22;message&#x22; }
]"
/>

يأخذك هذا الدليل من حساب جديد إلى agent يعمل على موقعك الإلكتروني. لا تحتاج إلى كتابة أي شيفرة. تبدأ فترتك التجريبية البالغة 7 أيام عند التسجيل، دون بطاقة ودون الحاجة إلى اختيار خطة. يُنقل أي رابط تلصقه في الصفحة الرئيسية معك عبر خطوات التسجيل. وتتيح صفحة `/try` للزوار لصق رابط والتحدث مع نسخة مسودة تحمل علامة مائية قبل المطالبة بها عند التسجيل.

<TutorialVideo episode="ep01" />

## قبل أن تبدأ [#قبل-أن-تبدأ]

تحتاج إلى حساب ورابط موقع عام يُفترض أن يمثّله الـ agent. اجعل النسخة الأولى محدودة النطاق، فمنتج واحد أو مهمة واحدة أسهل في التقييم من agent يُنتظر منه الإجابة عن كل سؤال حول شركة كاملة.

## 1. الصق رابط الموقع [#1-الصق-رابط-الموقع]

في الصفحة الرئيسية لـ Make Agent Fast، الصق الرابط ثم تابع. وبعد التسجيل أو تسجيل الدخول يُنقل الرابط نفسه معك، فلا يُطلب منك لصقه مرة أخرى. لا يوجد منشئ صفحات في هذا المسار.

ليس لديك موقع بعد؟ تقبل الشاشة الأولى أيضًا بضع إجابات مكتوبة، أو نموذجًا جاهزًا لترى كيف يعمل الأمر. وإذا كان لديك حساب بالفعل، فإن لصق رابط يبدأ مسودة **جديدة** غير منشورة من ذلك الموقع.

## 2. انتظر أثناء إنشاء المسودة [#2-انتظر-أثناء-إنشاء-المسودة]

تعرض شاشة الإنشاء العمل الفعلي الجاري:

1. **قراءة الموقع**
2. **بناء الـ agent**
3. **اختبار الإجابات**

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

## 3. تعرّف على الـ agent الخاص بك [#3-تعرّف-على-الـ-agent-الخاص-بك]

تصل إلى شاشة **تعرّف على الـ agent الخاص بك**: المحادثة الحقيقية إلى جانب ثلاثة اختبارات سريعة، وهي شيء يعرفه، وشيء يجب ألا يختلقه، وطلب التحدث إلى شخص. اضغط **اسأل هذا**، واقرأ الإجابة، ثم اقبلها أو صحّحها. تتحول الإجابة المصحَّحة إلى معرفة يستخدمها الـ agent من ذلك الحين فصاعدًا. تستهلك التجربة النصية credits. أما طلبات التواصل والإجراءات فهي محاكاة: لا يُرسل شيء ولا يُحجز شيء ولا يُحتسب أي customer. تتوفر مسارات الصوت والتذاكر بعد التجربة. وإذا غيّرت المعرفة أو ما يقوم به الـ agent، فكرر الاختبارات المتأثرة.

بعد ذلك اختر المهمة الرئيسية التي ينبغي أن يؤديها، والأماكن التي يتواصل منها customers معك. توجد قنوات المراسلة ضمن خطة Operate، ويمكن نقل تجربة Launch إلى Operate مرة واحدة بتاريخ الانتهاء نفسه.

## 4. ضعه حيث يوجد customers [#4-ضعه-حيث-يوجد-customers]

أخبرنا من سيضيفه إلى موقعك، واحفظ عنوان الصفحة التي سيعمل فيها، ثم فعّله، وأضف الشيفرة المكونة من سطر واحد (أو أرسلها إلى المطوّر لديك، أو اطلب إعدادًا بمساعدتنا). ثم اضغط **تحقق من موقعي**. سنبحث في صفحتك عن شيفرة تثبيت صالحة ونتحقق من أن الموقع مسموح به. بعد ذلك افتح موقعك واطرح سؤالًا على الأداة. يُعرض التأكيد اليدوي بتسمية منفصلة، وإذا فشلت إعادة التحقق فسيُطلب منك التحقق مرة أخرى. نسخ الشيفرة ليس نهاية الطريق، بل التحقق هو النهاية. ولا تحصل الـ agents الجديدة على صفحة تسويقية مستضافة.

## 5. فعّله بزائر حقيقي [#5-فعّله-بزائر-حقيقي]

التفعيل هو أول محادثة مع **زائر**، أو أول lead يتم التقاطه، وليس اختبارًا من المالك. تحتفظ صفحة الـ agent بإيصال إطلاق وقائمة موجزة للبدء إلى أن يحدث ذلك. راجع [إنشاء agent](/ar/docs/build/create-agent) للاطلاع على الدورة الكاملة.

## الخطوات التالية [#الخطوات-التالية]

* [تخصيص الأداة](/ar/docs/build/appearance)
* [تضمين الـ agent](/ar/docs/embed/overview)
* [مراجعة المحادثات وleads](/ar/docs/operate/conversations)

---

# التوثيق

Source: /ar/docs.md

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

وكيل لخدمة عملاء شركتك، يعمل على صفحتك وفي قنوات المراسلة لديك، ولا يجيب إلا بما اعتمدتَه، ويحيل الباقي إلى شخص مختص.

## دروس الفيديو [#دروس-الفيديو]

<TutorialSeries />

## ابدأ من هنا [#ابدأ-من-هنا]

اختر المسار المناسب بحسب ما تريد إطلاقه أولًا.

<CardGrid>
  <DocCard href="/ar/docs/getting-started/quickstart" title="أنشئ وكيلك الأول" description="الصق رابط موقعك، وراجع المسودة، ثم فعّل التضمين." art="quickstart" />

  <DocCard href="/ar/docs/embed/overview" title="أضف وكيلًا إلى موقعك" description="ثبّت أيقونة المحادثة العائمة باستخدام وسم script أو عبر دليل خاص بإطار العمل أو نظام إدارة المحتوى." art="embed" />

  <DocCard href="/ar/docs/connectors/overview" title="اربط قناة" description="رُدّ على العملاء من WhatsApp وMessenger وDiscord وغيرها من القنوات المدعومة." art="channel" />

  <DocCard href="/ar/docs/api/overview" title="ابنِ باستخدام API" description="أتمتة سير العمل الخاص بالوكلاء والمواقع والمحتوى والمحادثات والعمليات." art="api" />
</CardGrid>

## سير العمل الأساسي [#سير-العمل-الأساسي]

<Steps>
  <Step title="أنشئ">
    الصق رابط موقعك. سنزحف على صفحاته ونُعدّ مسودة وكيل. لن يصل أي شيء إلى العملاء قبل الخطوة الأخيرة من الإعداد.
  </Step>

  <Step title="راجع">
    تعرّف على الوكيل، وتحقق من بعض إجاباته، ثم ضعه حيث يتواجد عملاؤك.
  </Step>

  <Step title="انشر">
    أضف كود التثبيت من 

    **أطلقه**

     إلى موقعك الحالي، أو شارك رابط الوكيل، أو اربط قناة مراسلة.
  </Step>

  <Step title="حسّن">
    أضف مصادر معرفة، وعدّل 

    **العرض**

     الخاص بالأداة، وراجع المحادثات والعملاء المحتملين.
  </Step>
</Steps>

<Callout title="استخدم هذا التوثيق مع مساعد ذكاء اصطناعي">
  كل صفحة متاحة بصيغة Markdown. افتح قائمة إجراءات الصفحة لنسخها أو تنزيلها، أو أرسل رابط Markdown الأساسي الخاص بها إلى ChatGPT أو Claude. والمجموعة الكاملة المقروءة آليًا متاحة على [/docs/llms-full.txt](/ar/docs/llms-full.txt).
</Callout>

## ما الذي يمكنك بناؤه [#ما-الذي-يمكنك-بناؤه]

<FeatureGrid>
  <FeatureItem icon="embed" title="تضمين في الموقع" description="مساعد للدعم أو المبيعات على موقعك الحالي، بوسم script واحد." />

  <FeatureItem icon="message" title="وكيل مراسلة" description="وكيل واحد يجيب العملاء على Telegram وWhatsApp وMessenger وInstagram وDiscord وKakaoTalk." />

  <FeatureItem icon="voice" title="تجارب صوتية" description="رسائل صوتية ومكالمات مباشرة في الباقات المدعومة." />

  <FeatureItem icon="code" title="أتمتة عبر API" description="تحكّم برمجي في المواقع ومصادر المعرفة والمحادثات وwebhooks." />

  <FeatureItem icon="chart" title="أدوات التشغيل" description="صندوق الوارد، والتحليلات، والعملاء المحتملون، والرسائل الجماعية، وتحقيق الدخل، وضوابط الاستخدام." />

  <FeatureItem icon="site" title="رابط الوكيل" description="صفحة محادثة عامة واحدة على عنوان وكيلك الخاص، لمشاركتها حيث لا يمكن تشغيل سكربت. لا تحصل الوكلاء الجدد على صفحة تسويقية مستضافة." />
</FeatureGrid>

## الحصول على المساعدة [#الحصول-على-المساعدة]

إذا لم يجب أحد الأدلة عن سؤالك، فاستخدم عنصر إرسال الملاحظات في أسفل الصفحة أو تواصل مع الدعم من لوحة التحكم. وللاطلاع على حدود المنتج والفوترة، راجع [الباقات والأسعار](/ar/docs/account/pricing).

---

# استخدم Claude وCodex وCursor وChatGPT

Source: /ar/docs/operate/ai-assistants.md

اربط Make Agent Fast بمساعد ذكاء اصطناعي وأدر وكلاء خدمة العملاء لديك من المحادثة التي تستخدمها أصلًا. اسأل المساعد عمّا سأله العملاء هذا الأسبوع، أو اقرأ محادثة من Telegram، أو صحّح إجابة أخطأ فيها وكيلك، أو أنشئ وكيلًا جديدًا انطلاقًا من موقع إلكتروني. يعمل المساعد فقط مع الشركة التي توافق عليها، وبالصلاحيات والأرصدة (Credits) نفسها المتاحة في لوحة التحكم.

<TutorialVideo episode="ep10" />

## ماذا يمكنك أن تسأل [#ماذا-يمكنك-أن-تسأل]

* "اعرض وكلاء Make Agent Fast لديّ وأخبرني أيّها مفعّل فيه ودجت الموقع."
* "اعرض تقرير هذا الأسبوع لوكيل المخبز الخاص بي والأسئلة التي لم يستطع الإجابة عنها."
* "اقرأ أحدث محادثة على WhatsApp وصُغ مسودة رد."
* "عندما يسأل عميل عن التوصيل إلى Samarkand، أجبه: نوصّل أيام الثلاثاء والجمعة."
* "أنشئ وكيل دعم من [https://example.com](https://example.com) باللغة الأوزبكية."
* "ما العملاء المحتملون (Leads) الذين وصلوا منذ يوم الإثنين؟ علّم عميل كعكة الزفاف المحتمل على أنه مؤهَّل."

## الربط مع Claude [#الربط-مع-claude]

1. افتح [Make Agent Fast في دليل موصّلات Claude](https://claude.ai/directory/44ae8877-eaf6-46db-a4f6-049162fead01) واختر **اتصال**. يفتح الزر **الاتصال بـ Claude** في [صفحة إعداد الوكيل](/connect) الصفحة نفسها. يمكنك أيضًا فتح **تخصيص ← الموصّلات** في Claude والبحث عن **Make Agent Fast**. إذا لم يكن مدرجًا لحسابك بعد، فاختر **إضافة ← إضافة موصّل مخصص** وأدخل عنوان الخادم أدناه.
2. يفتح Claude نافذة تسجيل الدخول إلى Make Agent Fast. سجّل الدخول أو أنشئ حسابًا.
3. اختر الشركة التي تريد ربطها، وراجع الصلاحيات، ثم اختر **السماح بالوصول**. إذا لم تكن للشركة خطة بعد ولم تستخدم الفترة التجريبية المجانية من قبل، فإن السماح بالوصول يبدأ الفترة التجريبية البالغة 7 أيام. لا حاجة إلى بطاقة دفع.
4. عد إلى Claude واكتب "اعرض وكلاء Make Agent Fast لديّ" للتحقق من الاتصال.

```text
https://makeagent.fast/api/mcp
```

في Claude Team وEnterprise، يجب على المالك تفعيل الموصّل للمؤسسة قبل أن يتمكن الأعضاء من ربطه.

يعمل اتصال واحد في تطبيق Claude لسطح المكتب، وعلى claude.ai، وفي Claude Code المسجَّل الدخول بحساب Claude نفسه. يمكنك أيضًا لصق مطالبة الإعداد من **قم بتهيئة وكيلك** في [صفحة إعداد الوكيل](/connect) داخل محادثة Claude: سيعرض Claude موصّل Make Agent Fast مع زر **اتصال**.

## الربط مع ChatGPT [#الربط-مع-chatgpt]

إضافة Make Agent Fast لـ ChatGPT قيد المراجعة. إلى أن تُدرَج، يمكن لمستخدمي ChatGPT الذين يستطيعون إضافة اتصالات مخصصة (مثلًا في وضع المطوّر أو بصفة مسؤولي مساحة العمل) إضافة عنوان الخادم نفسه. تسجيل الدخول واختيار الشركة والصلاحيات هي نفسها كما في Claude.

## الربط مع Codex أو Cursor [#الربط-مع-codex-أو-cursor]

أسرع طريقة هي **قم بتهيئة وكيلك** في [صفحة إعداد الوكيل](/connect). فهي تنسخ مطالبة إعداد. الصقها في محادثة داخل تطبيقك، وسيضيف الوكيل Make Agent Fast نيابةً عنك. يسجّل كل تطبيق الدخول عبر متصفحك، ولا حاجة إلى مفتاح API.

* **Codex:** الصق المطالبة في محادثة Codex جديدة. يضيف Codex الخادم ويفتح صفحة تسجيل الدخول في متصفحك. وافق على الوصول، ثم ابدأ محادثة جديدة ليتم تحميل الأدوات.
* **Cursor:** الصق المطالبة في محادثة Cursor. يضيف Cursor الخادم إلى `~/.cursor/mcp.json`. افتح **تخصيص ← MCPs**، واختر **مصادقة** بجانب `makeagentfast`، ثم وافق على الوصول.

في كليهما، اختر الشركة، وراجع الصلاحيات، واكتب "اعرض وكلاء Make Agent Fast لديّ". وتستخدم التطبيقات الأخرى التي تدعم MCP عن بُعد مع تسجيل الدخول عبر المتصفح، مثل VS Code، عنوان الخادم نفسه.

### الإعداد يدويًا [#الإعداد-يدويًا]

Claude Code: أضف الخادم، ثم اكتب `/mcp` وسجّل الدخول.

```bash
claude mcp add --transport http makeagentfast https://makeagent.fast/api/mcp
```

Codex: يتيح لك `codex mcp login` تسجيل الدخول مجددًا لاحقًا.

```bash
codex mcp add makeagentfast --url https://makeagent.fast/api/mcp
codex mcp login makeagentfast
```

Cursor: أضف هذا إلى `~/.cursor/mcp.json`، ثم اختر **مصادقة** في **تخصيص ← MCPs**.

```json
{
  "mcpServers": {
    "makeagentfast": { "url": "https://makeagent.fast/api/mcp" }
  }
}
```

VS Code: أضف الخادم، ثم شغّل `makeagentfast` من قائمة خوادم MCP.

```bash
code --add-mcp '{"name":"makeagentfast","type":"http","url":"https://makeagent.fast/api/mcp"}'
```

## ما الذي يستطيع المساعد فعله [#ما-الذي-يستطيع-المساعد-فعله]

| الأداة                                    | وظيفتها                                                                               | تغيّر البيانات |
| ----------------------------------------- | ------------------------------------------------------------------------------------- | -------------- |
| `list_agents`, `get_agent`                | وكلاؤك، وحالة الودجت، والقنوات، وكود التثبيت، وآخر استيراد لصفحة ويب                  | لا             |
| `get_report`, `list_unanswered_questions` | المحادثات، والعملاء المحتملون (Leads)، وأكثر الأسئلة تكرارًا، والأسئلة التي بلا إجابة | لا             |
| `list_conversations`, `get_conversation`  | محادثات الموقع الإلكتروني والصوت وكل قناة مرتبطة                                      | لا             |
| `list_leads`                              | العملاء المحتملون (Leads) مع الاسم والبريد الإلكتروني والرسالة                        | لا             |
| `create_agent_from_website`               | ينشئ وكيلًا خاصًا بصيغة مسودة انطلاقًا من موقع إلكتروني                               | نعم            |
| `create_agent_from_notes`                 | ينشئ وكيلًا خاصًا بصيغة مسودة من حقائق مكتوبة، لنشاط تجاري بلا موقع إلكتروني          | نعم            |
| `test_agent`                              | يطرح سؤالًا على وكيلك دون إنشاء محادثة مع عميل؛ ويستهلك أرصدة (Credits)               | نعم            |
| `add_knowledge`, `save_answer`            | يضيف صفحة ويب أو نصًا، أو يحفظ الإجابة الصحيحة عن سؤال                                | نعم            |
| `reply_to_customer`                       | يرسل ردّك على قناة المحادثة ويوقف الوكيل مؤقتًا هناك                                  | نعم            |
| `update_lead`                             | يحدّد ما إذا كان العميل المحتمل (Lead) مؤهَّلًا أم لا                                 | نعم            |
| `set_website_widget`                      | يشغّل ودجت الدردشة في الموقع أو يوقفه. لا تتغير قنوات المراسلة.                       | نعم            |

يسألك Claude وChatGPT قبل تشغيل أي أداة تغيّر البيانات. تُقرأ صفحة الويب المضافة عبر `add_knowledge` في الخلفية؛ اطلب من المساعد التحقق عبر `get_agent` بعد دقيقة أو دقيقتين.

## بطاقات الموافقة في Claude [#بطاقات-الموافقة-في-claude]

يمكن لاتصالات Claude المؤهَّلة استخدام `list_pending_approvals` و`decide_approval` و`list_action_runs`. اطلب مراجعة التغييرات المعلّقة التي أكّدها العملاء أو النتائج الأخيرة. يمكن للمضيفات المتوافقة مع MCP Apps عرض بطاقات الموافقة وتشغيلات الإجراءات؛ وتبقى النتائج النصية متاحة عندما يتعذّر عرض البطاقة. تظل `list_unanswered_questions` الأداة الحالية للأسئلة التي بلا إجابة.

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

يقتصر هذا الامتداد على اتصال Claude الموثَّق. أما ChatGPT والعملاء الآخرون فيحتفظون بالأدوات الـ 15 الأصلية المذكورة أعلاه. هذا الاتصال الخاص بالمالك منفصل عن [أدوات MCP الخاصة بك في دردشة العملاء](/ar/docs/build/mcp-tools).

## الصلاحيات والبيانات والأرصدة [#الصلاحيات-والبيانات-والأرصدة]

يستطيع الاتصال قراءة الوكلاء والتقارير والمحادثات والعملاء المحتملين (Leads)، كما يستطيع تغيير المعرفة والإجابات والعملاء المحتملين والردود وودجت الموقع الإلكتروني. ولا يستطيع الاطلاع على تفاصيل الفوترة أو وسائل الدفع أو أعضاء الفريق أو بيانات اعتماد قنوات المراسلة. تستهلك إجابات `test_agent` والمعرفة المضافة حديثًا الأرصدة (Credits) تمامًا كما في لوحة التحكم.

تتولى الجهة المزوِّدة للمساعد معالجة المعلومات التي يتلقاها المساعد وفق شروطها، مثل Anthropic لـ Claude أو OpenAI لـ ChatGPT. توضح [سياسة الخصوصية](/privacy) لدينا ما يمكن أن يتلقاه الاتصال وما نسجّله.

## قطع الاتصال [#قطع-الاتصال]

احذف Make Agent Fast من إعدادات موصّلات المساعد. ولإنهاء الوصول من جانبنا، افتح **الإعدادات ← المطوّر** في لوحة تحكم Make Agent Fast وألغِ مفتاح OAuth الذي يحمل اسم المساعد. وإذا أعدت الربط لاحقًا فسيبدأ تسجيل دخول جديد.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

* **"انتهت الخطة أو الفترة التجريبية."** لا توجد خطة نشطة للشركة المرتبطة. يمكن للمالك اختيار خطة من لوحة التحكم؛ ويبقى المساعد متصلًا.
* **الشركة غير مدرجة عند الربط.** يتطلب الربط دور المالك أو المسؤول في تلك الشركة.
* **تفيد إحدى الأدوات بأن الاتصال لم يُمنح حق الوصول.** أزل الاتصال وأعد الربط حتى يطلب المساعد الصلاحيات الحالية.
* **لم تظهر صفحة الويب.** اطلب من المساعد تشغيل `get_agent`؛ إذ يوضح `latest_web_import` ما إذا كانت الصفحة قد قُرئت أو سبب فشلها، وتظهر الصفحة الفاشلة أيضًا ضمن **الإشعارات** في لوحة التحكم.

---

# التحليلات

Source: /ar/docs/operate/analytics.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ label: &#x22;الزيارات&#x22;, icon: &#x22;globe&#x22; },
{ label: &#x22;التفاعل&#x22;, icon: &#x22;chat&#x22; },
{ label: &#x22;النتائج&#x22;, icon: &#x22;chart&#x22; },
{ label: &#x22;القنوات&#x22;, icon: &#x22;connectors&#x22; }
]"
/>

<TutorialVideo episode="ep08" />

## تحديد نطاق القياس [#تحديد-نطاق-القياس]

افتح صفحة **التحليلات** الخاصة بموقعك واختر 7 أو 30 أو 90 يومًا، أو حدّد تاريخ بداية ونهاية مخصصين. اختر المقياس الأساسي، ومرشّح القناة أو المصدر إن لزم، ثم فعّل **المقارنة بالفترة السابقة** عندما تحتاج إلى خط أساس مماثل للمقارنة.

تُطبَّق المرشّحات على التقرير وعلى عنوان URL، بحيث يمكن إعادة إنتاج العرض نفسه. عند تفسير أي مقارنة، استخدم فترات متكافئة من حيث مدة الحملة وأيام الأسبوع والموسمية وحالة النشر. فالنسبة المئوية الكبيرة الناتجة عن حدث واحد أو حدثين ليست دليلًا موثوقًا.

## فهم المقاييس الرئيسية [#فهم-المقاييس-الرئيسية]

| المقياس                       | المعنى                                                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **الزيارات**                  | مشاهدات الصفحات العامة المسجّلة، مع إزالة التكرار حيثما يستطيع نموذج التحليلات التعرّف على الزائر نفسه في اليوم نفسه |
| **المحادثات**                 | بدء محادثة، وليس كل رسالة منفردة                                                                                     |
| **العملاء المحتملون (Leads)** | أحداث أو سجلات العملاء المحتملين التي جرى التقاطها ضمن السياق المحدد                                                 |
| **التحويل**                   | نسبة الزيارات إلى عملاء محتملين؛ راجع أيضًا نسبة الزيارات إلى محادثات ونسبة المحادثات إلى عملاء محتملين              |

يُعدّ حجم الرسائل ومتوسط عدد الرسائل في كل محادثة مقياسين للتفاعل، وليسا بدايات محادثات إضافية. أما مقاييس الزوار العائدين، والأسئلة غير المُجابة، وتحويل المحادثات إلى موظف (Handoff)، والحجوزات، والعملاء المحتملين المؤهَّلين، فتصف كلٌّ منها جزءًا مختلفًا من رحلة العميل.

## قراءة الاتجاهات والمسار والتوقيت [#قراءة-الاتجاهات-والمسار-والتوقيت]

استخدم الاتجاه اليومي لتحديد نقطة التغيّر، ثم قارنها بالإصدارات والحملات وتحديثات المصادر وحوادث المزوّدين وتغييرات النشر. يفصل مسار التحويل بين ثلاثة أسئلة: هل بدأ الزوار محادثة؟ وهل أنتجت المحادثات عملاء محتملين؟ وهل أنتجت الزيارات عملاء محتملين بوجه عام؟

تعرض عروض الساعات وأيام الأسبوع وقت حدوث النشاط المسجّل. وهي مفيدة لتحديد أوقات التوظيف وتوقيت الحملات، لكن اختلاف التوقيت الزمني والموقع الجغرافي للجمهور وصغر العيّنات قد تشوّه أي استنتاج بسيط عن «أفضل وقت».

## فحص مصادر الزيارات والقنوات [#فحص-مصادر-الزيارات-والقنوات]

تعتمد أبرز المصادر على معلومات المُحيل (referrer) ومعلمات UTM عند توفرها. ويشمل «مباشر/بدون مصدر» الزيارات التي يغيب مصدرها أو يكون مخفيًا. وتجعل خصوصية المتصفح وتطبيقات الروابط وعمليات إعادة التوجيه وضوابط الموافقة والرحلات عبر أجهزة متعددة إسناد الزيارات ناقصًا؛ فلا تُلحق الزيارات غير المنسوبة بحملة بعينها قسرًا.

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

## اكتشاف فجوات المعرفة والمحادثات [#اكتشاف-فجوات-المعرفة-والمحادثات]

يعرض جدول الأسئلة المواضيع الأكثر تكرارًا وأعداد الأسئلة غير المحسومة أو التي تمثل فجوات. ويعرض قسم **ما استند إليه وكيلك** الإجابات الأخيرة مع مصادر المعرفة المسجّلة. استخدم الاثنين مع صندوق **المحادثات** الفعلي:

1. حدّد سؤالًا عالي الحجم أو عالي الفجوات.
2. اقرأ عدة محادثات كاملة.
3. حدّد ما إذا كانت المشكلة تتعلق بنقص المعرفة أو تعارضها أو الشخصية أو اللغة أو الواجهة أو نيّة الزائر.
4. أجرِ تغييرًا واحدًا مضبوطًا.
5. أعد تشغيل اختبارات القبول وقارن بفترة جديدة.

يشير المقياس إلى مكان التحقيق، لكنه لا يفسّر السبب بمفرده.

## إدارة العملاء المحتملين والمتابعة [#إدارة-العملاء-المحتملين-والمتابعة]

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

## تصدير التقرير [#تصدير-التقرير]

استخدم **تصدير** لإنشاء ملف Markdown (`.md`) أو Excel (`.xlsx`) أو عرض للطباعة/PDF وفق المرشّحات الحالية. يفتح خيار PDF صفحة مهيأة للطباعة؛ اختر **حفظ بصيغة PDF** في المتصفح. سجّل سياق المرشّحات والتواريخ مع الملف المُصدَّر، واحمِ أي بيانات زوار أو عملاء محتملين يتضمنها.

التصديرات هي لقطات ثابتة؛ فهي لا تتحدّث باستمرار، ولا ينبغي التعامل معها كمصدر حقيقة مستقل بعد تغيّر مرشّحات لوحة التحكم أو الأحداث الأساسية.

## الخصوصية وجودة البيانات [#الخصوصية-وجودة-البيانات]

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

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                                  | ما يجب فحصه                                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| التقرير فارغ                                             | صحة الموقع والتاريخ والمرشّحات، والزيارات المنشورة، وآخر حدث، وحجب الموافقة، والاختبار العام |
| تختلف أعداد الزيارات/المحادثات عن الرسائل                | أمر متوقع؛ إذ تُزال التكرارات من البدايات والمشاهدات بطريقة تختلف عن رسائل المحادثة          |
| تختلف أعداد العملاء المحتملين المصفّاة عن إجمالي الصندوق | إسناد الأحداث المصفّى مقابل جميع سجلات العملاء المحتملين المخزّنة                            |
| المصدر مباشر/بدون مصدر                                   | المُحيل أو UTM مفقود أو مخفي؛ أعد الاختبار برابط عام موسوم                                   |
| يختلف التصدير عن الشاشة                                  | تطابق المرشّحات والتاريخ وقت التصدير، وهل تغيّرت البيانات الحية بعد ذلك                      |

## التحويل والنتائج التجارية [#التحويل-والنتائج-التجارية]

يتبع مسار تحويل الموقع الآن أحداث **زيارة ← محادثة ← عميل محتمل** المسجّلة بالترتيب، للزائر نفسه في يوم UTC نفسه. تعرض كل خطوة الأعداد، ونسبة التحويل من الخطوة السابقة، ونسبة التسرّب الملحوظة. ويقيس الوقت الوسيط إتمام الانتقال من الزيارة إلى العميل المحتمل. وتشمل النطاقات الجاهزة أيام UTC التقويمية بما فيها اليوم الحالي؛ واليوم الحالي غير مكتمل.

مرّر المؤشر أو المس أو استخدم مفاتيح الأسهم على مخطط الاتجاه لفحص القيم اليومية الدقيقة. يرسم عرض التحويل نسبة مئوية من مسار تحويل الموقع المرتّب. وسّع **عرض البيانات اليومية** للحصول على جدول متاح للوصول. تتيح رؤوس جدول المصادر ترتيب الأعداد أو التحويل؛ ويؤدي تحديد مصدر إلى تطبيق مرشّح URL.

يعرض **تأهيل العملاء المحتملين** الحالة الراهنة للعملاء المحتملين الذين أُنشئوا في الفترة المحددة. ويعرض **نتائج الدفع** حالات الدفع الأصلية والمبالغ المدفوعة حسب العملة، باستثناء المدفوعات التجريبية. وتتطلب الطلبات الخارجية تكاملًا موثَّقًا؛ فعدم وجود عمليات دفع مسجّلة لا يثبت عدم وجود مبيعات. وتظهر فرص البيع الحالية بحسب مرحلتها الراهنة، مع أسباب الخسارة التي يسجّلها الفريق. وتستخدم هذه اللوحات النطاق الزمني عبر جميع المصادر والأوضاع.

يفصل **قنوات التواصل** بين الويب والصوت ومنصات المراسلة الفعلية. ويحتسب المحادثات النشطة والرسائل الواردة وردود الوكيل وردود الفريق البشري. والردود ليست حلولًا للمشكلات. وتفتح روابط الصندوق سجل القناة بمرشّحاته الخاصة. وتُضمَّن جميع الجداول الجديدة في تصديرات التقرير.

---

# الرسائل الجماعية

Source: /ar/docs/operate/broadcasts.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;المستلمون&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;القالب&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;قائمة الإرسال&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep07" start="146" />

## تعرّف على النطاق الحالي [#تعرّف-على-النطاق-الحالي]

تستهدف ميزة الرسائل الجماعية في لوحة التحكم حاليًا **Kakao AlimTalk**. وهي ليست أداة عامة لإنشاء حملات على Telegram أو WhatsApp أو Messenger أو Discord. يتطلب تشغيل بوابة AlimTalk الفعلية ملف مرسل مسجّلًا، وقالبًا معتمدًا، ومزوّد منصة مهيّأً، ورقم هاتف كوري يمكن الوصول إليه لكل مستلم.

يُحتسب عدد المستلمين من العملاء المحتملين (Leads) غير المحذوفين في الموقع الحالي ممن لديهم وسيلة اتصال يمكن الوصول إليها، مع إزالة التكرار بحسب وسيلة الاتصال. قد يقبل وضع التطوير/الوضع التجريبي بريدًا إلكترونيًا بديلًا، لكن بوابة AlimTalk الفعلية تتطلب رقم هاتف مناسبًا. تأكد من أن الوضع المعروض هو الوضع الفعلي قبل اعتبار الرسالة الموضوعة في قائمة الإرسال تسليمًا حقيقيًا.

## افهم حدود الإرسال [#افهم-حدود-الإرسال]

يؤدي اختيار **إرسال** إلى وضع مهمة دائمة واحدة في قائمة الإرسال لكل مستلم مؤهل حاليًا. ولا توفر لوحة التحكم حاليًا تقسيم الجمهور لكل عملية إرسال، ولا تعديل المستلمين، ولا جدولة الوقت، ولا معاينة الجمهور، ولا الإيقاف المؤقت أو سحب الرسالة. لا تستخدم الزر إلا إذا كان الجمهور الكامل الذي تم تحديده مقصودًا ومخوّلًا بتلقي الرسالة.

يقبل النموذج رمز قالب معتمدًا ونصًا يصل إلى 2,000 حرف. وقد يفرض المزوّد قالبًا أقصر، أو صياغة ومتغيرات معتمدة بدقة، أو قيودًا على التوقيت وملف المرسل والسياسات. ولا يتجاوز وضع الرسائل في قائمة الإرسال في Make Agent Fast هذه القواعد.

## جهّز رسالة جماعية متوافقة [#جهّز-رسالة-جماعية-متوافقة]

1. تأكد من أن مسار جمع العملاء المحتملين في الموقع طلب وسيلة الاتصال المعنية والموافقة أو الأساس القانوني.
2. أزل أو احذف الأشخاص الذين لا ينبغي التواصل معهم قبل احتساب الجمهور.
3. تأكد من إعداد مزوّد AlimTalk فعلي ومفتاح مرسل مسجّل.
4. احصل على رمز القالب المعتمد من المزوّد وطابق النص مع ذلك القالب.
5. تحقق من هوية المرسل، والغرض، والروابط، والإفصاحات المطلوبة، ومسار إلغاء الاشتراك.
6. استخدم موقعًا/جمهورًا منفصلًا للاختبار إذا احتجت إلى اختبار إنتاجي صغير؛ فأداة الإنشاء الحالية تستهدف جميع العملاء المحتملين المؤهلين في موقعها.

لا ترسل بيانات اعتماد، أو تفاصيل حساب حساسة، أو سجلات محمية، أو تخصيصًا مُختلقًا، أو عرضًا لم يعتمده الـ agent أو الموقع.

## ضع الرسالة في قائمة الإرسال وراقبها [#ضع-الرسالة-في-قائمة-الإرسال-وراقبها]

بعد الإرسال، يعرض السجل النص والحالة وعدد المستلمين المقصودين وعدد عمليات الإرسال الناجحة. المهام غير مكررة (idempotent) لكل رسالة جماعية ولكل عميل محتمل، لذلك لا ينبغي أن تؤدي إعادة محاولة قائمة الإرسال إلى إنشاء نسخة ثانية عن قصد من الزوج نفسه (الرسالة الجماعية/المستلم).

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

إذا فشلت بعض المهام، تحتفظ الرسالة الجماعية بآخر خطأ من المزوّد بينما يزداد عدد عمليات الإرسال الناجحة بشكل مستقل. لا تنشئ رسالة جماعية مطابقة جديدة قبل أن تفهم ما إذا كان المزوّد قد قبل أيًّا من المحاولات السابقة.

## الأتمتة عبر API [#الأتمتة-عبر-api]

استخدم `broadcasts:write` لإنشاء مسودة ووضعها في قائمة الإرسال عبر Public API من خادم موثوق. حافظ على عدم التكرار (idempotency) وراجع احتساب المستلمين وجاهزية المزوّد. لا يمكن لـ API جعل قالب AlimTalk غير معتمد متوافقًا.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                   | ما يجب التحقق منه                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| زر الإرسال معطّل                          | لا يوجد عملاء محتملون مؤهلون في الموقع لديهم وسيلة اتصال يمكن الوصول إليها                       |
| يظهر الوضع محليًا/تطويرًا                 | لم يتم إعداد مزوّد AlimTalk الفعلي أو بيانات اعتماده؛ لا يوجد تسليم حقيقي للعملاء                |
| ترفض البوابة القالب                       | رمز القالب المعتمد، والنص/المتغيرات، وملف المرسل، وتنسيق المستلم                                 |
| يتضمن عدد المستلمين وسيلة اتصال غير صالحة | يتطلب التسليم الفعلي رقم هاتف؛ نظّف جمع العملاء المحتملين/البيانات قبل الإرسال                   |
| يظل السجل في حالة الإرسال                 | خطأ قائمة الإرسال/المزوّد، و`sent count` مقارنةً بعدد المستلمين                                  |
| الحاجة إلى التواصل مع شريحة فقط           | غير مدعوم حاليًا في أداة الإنشاء هذه؛ أنشئ مسار عمل منفصلًا لجمهور معتمد بدلًا من الإرسال للجميع |

أوقف الإرسال عند ظهور شكاوى أو مستلمين غير متوقعين أو عدم تطابق القالب أو أخطاء من المزوّد.

---

# المحادثات والعملاء المحتملون

Source: /ar/docs/operate/conversations.md

{/* docs-visuals */}

<DocsIconList
  items="[
{ icon: &#x22;message&#x22;, title: &#x22;سلاسل محادثات موحّدة&#x22;, description: &#x22;تظهر سجلات الويب والصوت والمحادثات الفورية والموصّلات في صندوق وارد واحد يمكنك التدخل والرد منه.&#x22; },
{ icon: &#x22;book&#x22;, title: &#x22;الاستناد إلى المصادر&#x22;, description: &#x22;تعرض رسائل المساعد الاستشهادات المخزّنة بالمصادر عند توفرها.&#x22; },
{ icon: &#x22;account&#x22;, title: &#x22;العملاء المحتملون&#x22;, description: &#x22;تدعم الأسماء والبريد الإلكتروني والنوايا المسجّلة متابعةً مدروسة.&#x22; }
]"
/>

<TutorialVideo episode="ep06" />

## قراءة صندوق الوارد الموحّد [#قراءة-صندوق-الوارد-الموحّد]

افتح صفحة **المحادثات** الخاصة بالـ agent لعرض أحدث 30 سلسلة محادثة عبر دردشة الويب المستضافة أو المضمّنة، والرسائل الصوتية، ونصوص المكالمات المباشرة، وTelegram وWhatsApp وMessenger وInstagram وDiscord وKakaoTalk. استخدم **تحميل المزيد** للرجوع إلى الأقدم بحسب وقت آخر نشاط.

يعرض كل صف القناة، وأفضل هوية متاحة للزائر، ومعاينة لآخر رسالة، وعدد الرسائل، ووقت آخر نشاط. افتح الصف لقراءة النص الكامل المخزّن للمحادثة مع الطوابع الزمنية. يمكن أن تعرض فقاعات المساعد مصدر المعرفة والقسم المسجّلين للإجابة المستندة إلى المصادر.

يمكنك أيضًا التدخل في المحادثة. في صفحة السلسلة، تتيح لك **الرد كشخص** الكتابة إلى الزائر ثم اختيار **إرسال الرد**. يؤدي الرد إلى إيقاف الـ agent مؤقتًا لمدة 30 دقيقة حتى لا يقاطعك؛ ويوقفه **إيقاف الـ agent مؤقتًا 30 دقيقة** دون رد، بينما يعيد **استئناف الـ agent** المحادثة إليه مبكرًا. وينتهي الإيقاف المؤقت من تلقاء نفسه أيضًا. تعمل ردود المالك في محادثات الموقع وفي محادثات Telegram وWhatsApp وMessenger وInstagram؛ وتوضع ردود قنوات المراسلة في قائمة الانتظار وتُسلَّم عبر القناة. أما محادثات Discord وKakaoTalk ومحادثات الضيوف في Telegram ونصوص المكالمات المباشرة فلا يمكن الرد عليها من لوحة التحكم، لذا قم بالرد في تطبيق المراسلة الأصلي. تتوفر الإجراءات نفسها لواجهة API العامة باستخدام `conversations:write`.

## فهم حدود الهوية [#فهم-حدود-الهوية]

يستخدم الويب والصوت المباشر وكل موصّل معرّفات زوار مختلفة. ويُعدّ مستخدم Telegram وزائر المتصفح ورقم WhatsApp هويات منفصلة ما لم تتوفر بيانات ربط صريحة وبموافقة. إن تشابه أسماء العرض ليس دليلًا على أن سلسلتين تعودان إلى الشخص نفسه.

قد تحدّد تسميات الموصّلات البوت أو الصفحة أو التطبيق بدلًا من الزائر عندما لا توفر المنصة الخارجية هوية عرض آمنة. تعامل مع معرّفات القنوات والأسماء المستنتجة على أنها بيانات وصفية غير موثوقة، وليست تفويضًا.

## مراجعة جودة الإجابات [#مراجعة-جودة-الإجابات]

لمراجعة سلسلة محادثة تمثيلية:

1. اقرأ سؤال الزائر في سياقه بدلًا من الحكم على الإجابة الأخيرة وحدها.
2. تأكد من أن الرد يلتزم بحدود الشخصية واللغة.
3. افحص مصادر الاستناد المعروضة وقارنها بإصدار المعرفة الحالي.
4. دوّن الأسئلة غير المجاب عنها أو المتكررة أو المضللة أو أسئلة المتابعة غير الضرورية.
5. أضف المعلومة الناقصة بعد التحقق منها إلى المعرفة أو الأسئلة الشائعة، ثم اختبرها في محادثة جديدة.

لا يعاد كتابة الرسائل السابقة عند تغيّر مصدر المعرفة. ابدأ سلسلة جديدة لاختبار الانحدار بعد أي تحديث.

## تسجيل العملاء المحتملين وإدارتهم [#تسجيل-العملاء-المحتملين-وإدارتهم]

يمكن لتسجيل العملاء المحتملين تخزين اسم الزائر وبريده الإلكتروني وطلبه المعلن عندما يسمح بذلك مسار عمل الـ agent. تظهر أحدث العملاء المحتملين في **التحليلات**، حيث يمكن للمالك إنشاء متابعة معتمدة وإرسالها، أو تصدير بيانات العملاء المحتملين، أو حذف عميل محتمل بعينه.

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

نص المتابعة المُنشأ هو مسودة. راجع المستلم والادعاءات والروابط والأسعار والنبرة والبيانات الشخصية قبل الإرسال. لا تسمح أبدًا للـ agent باختلاق عرض أو وعد غير موجود في المعرفة المعتمدة.

## التصدير والحذف بأمان [#التصدير-والحذف-بأمان]

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

كما أن فصل عنصر مضمّن أو موصّل لا يمحو تلقائيًا سلاسل محادثاته التاريخية. اتبع مسار الخصوصية الخاص بالحساب عندما يقدّم زائر طلب حذف أو وصول، وأزل النسخ اللاحقة أيضًا.

## روتين المراجعة التشغيلية [#روتين-المراجعة-التشغيلية]

* يوميًا أثناء الإطلاق: افحص السلاسل الجديدة وحالات التحويل (Handoff) وأعطال المزوّد والإجابات عالية المخاطر.
* أسبوعيًا: جمّع الأسئلة المتكررة، وحدّد الفجوات المعرفية، وتحقق من حالة متابعة العملاء المحتملين.
* بعد تغييرات المحتوى أو النموذج: أعد تشغيل مجموعة القبول وافحص الاستشهادات.
* بعد وقوع حادثة: احتفظ بالطوابع الزمنية والمعرّفات الآمنة، واحتوِ القناة المتأثرة، وتجنب تداول النصوص الخاصة الخام.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                           | ما يجب التحقق منه                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| السلسلة المتوقعة غير موجودة       | الموقع الصحيح، وتسليم القناة، وآخر حدث للموصّل، واكتمال الاختبار العام، ووقت النشاط                       |
| تُفتح السلسلة بعدد أقل من الأدوار | هل كان المصدر نص مكالمة مباشرة أم سجل موصّل أم هوية زائر/قناة مختلفة                                      |
| الاستشهاد مفقود                   | قد لا تكون الإجابة استخدمت معرفة قابلة للاسترجاع، أو قد تفتقر السجلات الأقدم إلى بيانات الاستشهاد الوصفية |
| يظهر الشخص نفسه مرتين             | أمر متوقع عبر معرّفات المتصفح/القنوات المنفصلة؛ لا تدمج بالاسم وحده                                       |
| المتابعة غير متاحة                | بريد/وسيلة تواصل العميل المحتمل، وحالة الوصول، وإعدادات الإرسال، وحدود المعدل، ومتطلبات مراجعة المالك     |

---

# تحقيق الدخل

Source: /ar/docs/operate/monetization.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;العروض&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;الدفع&#x22;, icon: &#x22;bolt&#x22; }, { label: &#x22;الطلبات&#x22;, icon: &#x22;chart&#x22; }]" />

## تعرّف على علاقتَي الفوترة [#تعرّف-على-علاقتَي-الفوترة]

تتيح **تحقيق الدخل** لمالك الموقع بيع عرض إلى زائر. وهذا منفصل عن خطة Make Agent Fast الخاصة بالمالك وعن حزم الرصيد (Credits). يجب مطابقة سجلات إيرادات/طلبات المنشئ واستخدام المالك للمنصة كلٍّ على حدة.

تعرض الصفحة وضع الدفع الحالي. يمكن لوضع **Polar (مدفوعات حقيقية)** قبول المشتريات الفعلية المُعدّة. أما **محلي/تطوير (وضع الاختبار)** فهو مخصص لسلوك بيئة التطوير، ويجب ألا يُعرض أبدًا على أنه دفعة إنتاج مسوّاة.

## أنشئ عرضًا [#أنشئ-عرضًا]

اختر أحد الأنواع المدعومة:

| النوع                     | الاستخدام المقصود                   |
| ------------------------- | ----------------------------------- |
| **وصول مدفوع**            | فتح تجربة وكيل خاصة بالأعضاء فقط    |
| **مكالمة/استشارة مدفوعة** | بيع استشارة أو نتيجة مكالمة         |
| **إكرامية**               | دعم بسعر ثابت أو بمبلغ يحدده الداعم |
| **منتج رقمي**             | بيع مُنتَج رقمي أو وصول محدد        |

أدخل عنوانًا ووصفًا محددين، والسعر بالسنتات، والعملة، ومفتاح منتج Polar الاختياري. يربط المفتاح العرض بمنتج مُعدّ لدى مزوّد الدفع. يمكن عرض العرض النشط أو اقتراحه في محادثة الوكيل، أما العرض غير النشط فيبقى ظاهرًا للمالك لكن لا ينبغي بيعه.

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

## اجعل الوصول إلى الوكيل مدفوعًا [#اجعل-الوصول-إلى-الوكيل-مدفوعًا]

أنشئ عرض **وصول مدفوع** وفعّله أولًا، ثم اختره ضمن **وكيل للأعضاء فقط**. يحصل الزوار الذين لم يفتحوا الوصول على مسار شراء/فتح بدلًا من الوصول العادي إلى المحادثة. يمكن اختيار منتجات الوصول النشطة فقط؛ كما أن وقت التشغيل يتجاوز القفل (fail open) بدلًا من تعطيل المحادثة نهائيًا إذا اختفى العرض المحدد.

اختبر قبل الإطلاق حالات: الزائر الجديد/غير المسجّل، والدفع الناجح، والعودة إلى الوصول، وإلغاء الدفع، وحدث المزوّد المكرر، والعرض غير النشط، والاسترداد/سحب الوصول.

## اضبط مسارات الدفع [#اضبط-مسارات-الدفع]

للدفع المباشر عبر Polar، يجب ضبط نشر المنصة وربط المنتجات. يمكن لعنصر تحكم اختياري للدفع في كوريا عرض KakaoPay/Naver Pay/Toss لعروض KRW فقط عندما تفيد المنصة بأن هذا المسار متاح؛ وتفعيل مفتاح غير متاح لا ينشئ تكاملًا مع مزوّد الدفع.

استخدم وضع الاختبار لدى المزوّد حيثما كان مدعومًا، ثم تحقق من عملية شراء حقيقية صغيرة وفق سياستك التشغيلية. تأكد من الوحدات الصغرى للعملة: بالنسبة إلى USD، تعني `2500` المبلغ `$25.00`. لا تخمّن سلوك السنتات لعملة تعتمد أعراف وحدات صغرى مختلفة.

## راجع الطلبات والإيرادات [#راجع-الطلبات-والإيرادات]

تعرض الصفحة عدد الطلبات المدفوعة وملخص الإيرادات وأحدث المشتريات. تعكس حالة «مدفوع» حالة الدفع/المزوّد المسجّلة؛ طابق رسوم المزوّد والضرائب والمبالغ المستردة والنزاعات على المدفوعات والتحويلات والتسليم في النظام المالي المناسب.

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

## تسعير النتائج الاختياري [#تسعير-النتائج-الاختياري]

يمكن لـ **الدفع لكل نتيجة** خصم مبلغ ثابت من رصيد محفظة المالك مقابل Lead مؤهَّل من الوكيل أو طلب حجز يؤكده شخص لاحقًا، وذلك إضافة إلى الاستخدام العادي. وهو ليس دفعًا من الزائر ولا يتحول إلى إيراد للمنشئ. تأهيل الوكيل ليس قبولًا بيعيًا من إنسان، وطلب الحجز ليس اجتماعًا مؤكدًا. أبقِ هذا الوضع متوقفًا ما لم يفهم المالك الرسوم الإضافية على الرصيد والتعريفات الدقيقة للأحداث.

## قائمة التحقق قبل الإطلاق [#قائمة-التحقق-قبل-الإطلاق]

* وضع الدفع المباشر/الاختباري واضح لا لبس فيه.
* عنوان العرض ووصفه والعملة والسعر ومنتج المزوّد متطابقة.
* التسليم ومدة الوصول والاسترداد والضرائب والدعم والخصوصية موثّقة.
* تحتوي معرفة الوكيل على ادعاءات تجارية معتمدة فقط.
* جرى اختبار مسارات النجاح والإلغاء والتكرار والاسترداد والعرض غير النشط.
* تم تعيين المسؤول عن تنبيهات الشراء والتسليم، ومطابقة المحاسبة، وإجراءات الحوادث.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                       | ما يجب التحقق منه                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| لا يظهر العرض                 | أنه نشط، وذو صلة بالمحادثة، وأن حالة الموقع محدّثة                                          |
| الدفع المباشر غير متاح        | إعداد الدفع في النشر، ومفتاح منتج المزوّد الخاص بالعرض                                      |
| يبقى الوصول مقفلًا بعد الدفع  | حالة الشراء المسجّلة، والزائر/الجلسة الصحيحان، وwebhook المزوّد، ومعرّف العرض               |
| لا يؤثر مفتاح الدفع الكوري    | مسار المنصة غير مُعدّ/متاح، أو عملة العرض غير مدعومة                                        |
| تختلف الإيرادات عن التحويل    | رسوم المزوّد، والمبالغ المستردة، والنزاعات على المدفوعات، والضرائب، وتوقيت التسوية، والعملة |
| ينخفض رصيد المالك بعد النتائج | تسعير النتائج الاختياري مفعّل إضافة إلى الاستخدام العادي                                    |

---

# الإشعارات

Source: /ar/docs/operate/notifications.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;عميل محتمل&#x22;, icon: &#x22;account&#x22; }, { label: &#x22;تحويل إلى موظف&#x22;, icon: &#x22;message&#x22; }, { label: &#x22;حجز&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep06" start="95" />

## ما الذي يظهر هنا [#ما-الذي-يظهر-هنا]

صفحة **الإشعارات** الخاصة بالوكيل هي سجل أحداث داخل لوحة التحكم. وهي تسجّل أنواع الأحداث التالية الموجّهة إلى المالك:

| النوع                                           | المعنى                                           |
| ----------------------------------------------- | ------------------------------------------------ |
| **طلب عميل جديد** (عميل محتمل)                  | سجّل الوكيل بيانات اتصال أو نية لدى أحد الزوار   |
| **طلب الزائر التحدث إلى موظف** (تحويل إلى موظف) | طلبت المحادثة متابعة بشرية أو استدعتها           |
| **كتب الزائر أثناء ردّك**                       | كتب أحد الزوار بينما كنت قد توليت المحادثة       |
| **حجز جديد**                                    | تم تسجيل نتيجة حجز                               |
| **تذكرة دعم**                                   | تم فتح تذكرة دعم أو تحديثها                      |
| **إجراء بحاجة إلى الموافقة**                    | هناك تغيير أكّده العميل في انتظار موافقتك        |
| **إجراء بحاجة إلى انتباه**                      | تعذّر إكمال إجراء تمت الموافقة عليه              |
| **موصّل بحاجة إلى انتباه**                      | إحدى قنوات المراسلة تحتاج إلى انتباه             |
| **اقتراب موعد الرد ضمن اتفاقية مستوى الخدمة**   | حان موعد استحقاق الرد على أحد عملاء المبيعات     |
| **طلب خدمة الكونسيرج**                          | طلبت من المنصة ربط إحدى القنوات نيابةً عنك       |
| **تعذّرت إضافة صفحة الويب**                     | تعذّرت قراءة صفحة طلب مساعد ذكاء اصطناعي إضافتها |

يمكن أن يعرض كل عنصر نوع الحدث ووقت إنشائه واسم الزائر وبريده الإلكتروني عند توفرهما ومقتطفًا قصيرًا. ويتم تمييز العنصر غير المقروء بصريًا، ويُحتسب ضمن عدد العناصر غير المقروءة.

يمكن لبطاقة **التنبيهات** في هذه الصفحة نسخ السجل إلى Telegram: حدّد **أرسل لي التنبيهات عبر Telegram** وسيصلك كل إشعار جديد أيضًا كرسالة من بوت Telegram الخاص بك المتصل (أو من بوت التنبيهات الخاص بـ Make Agent Fast). تتضمن تنبيهات الموافقة زرَّي **موافقة** و**رفض**. التنبيهات معطّلة افتراضيًا، ويستمر عمل سجل لوحة التحكم والبريد الإلكتروني للمالك في الحالتين. لا يؤدي وضع علامة «مقروء» على عنصر إلى إرسال بريد إلكتروني إلى زائر، أو الرد عبر موصّل، أو تغيير عميل محتمل، أو إلغاء اشتراك أي شخص لدى مزوّد خارجي.

## مراجعة الأحداث وتمييزها [#مراجعة-الأحداث-وتمييزها]

1. افتح **الإشعارات** للموقع المقصود.
2. امنح الأولوية لطلبات التحويل إلى موظف والحجوزات الحساسة للوقت.
3. افتح سياق **المحادثات** أو **التحليلات** ذي الصلة عندما تحتاج إلى التأكد من الهوية والنية.
4. اختر **تحديد كمقروء** فقط بعد أن يقوم المالك المسؤول بفرز العنصر ومراجعته.
5. استخدم **تحديد الكل كمقروء** فقط عندما تكون قد راجعت عمدًا كل حدث ظاهر أو غير مقروء.
6. اختر **تحميل المزيد** لعرض الصفحات الأقدم.

حالة القراءة هي أداة مساعدة في سير عمل المالك، وليست دليلًا على أن الزائر تلقى متابعة. تتبّع المتابعة الفعلية في النظام المعتمد لحفظ السجلات.

## حماية بيانات الزوار [#حماية-بيانات-الزوار]

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

لا يؤدي حذف إشعار أو تمييزه تلقائيًا إلى إزالة العميل المحتمل أو المحادثة أو الحجز أو سجل المزوّد أو النسخة المصدَّرة المرتبطة به. استخدم سير عمل الخصوصية والحذف للتعامل مع طلبات أصحاب البيانات.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                            | ما يجب التحقق منه                                                                                                              |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| الحدث المتوقع غير موجود                            | تأكد من الموقع الصحيح، ومن اكتمال العميل المحتمل أو التحويل إلى موظف أو الحجز فعليًا، ومن وقت الحدث، ومن المحادثة المرتبطة به  |
| يبدو عدد العناصر غير المقروءة قديمًا               | حدّث الصفحة بعد إجراء التمييز وتأكد من أنه أُبلغ عن نجاحه                                                                      |
| لم يؤدِّ تمييز العنصر كمقروء إلى التواصل مع الزائر | هذا متوقع؛ فهذا السجل لا يرسل متابعة                                                                                           |
| عنصر أقدم غير موجود                                | استخدم **تحميل المزيد**؛ فالصفحة الأولى محدودة عمدًا                                                                           |
| تحتاج إلى تنبيهات خارج لوحة التحكم                 | فعّل Telegram في بطاقة **التنبيهات**؛ وللتوجيه عبر البريد الإلكتروني أو على غرار Slack، استخدم Public API أو webhooks الموقّعة |

للأتمتة، استخدم موارد Public API المدعومة أو أحداث webhook الموقّعة بدلًا من استخراج البيانات من لوحة التحكم هذه.

---

# الأرصدة والاستخدام

Source: /ar/docs/operate/usage.md

{/* docs-visuals */}

<DocsChipRow items="[{ label: &#x22;الأرصدة&#x22;, icon: &#x22;layers&#x22; }, { label: &#x22;دقائق الصوت&#x22;, icon: &#x22;voice&#x22; }, { label: &#x22;الشحن الإضافي&#x22;, icon: &#x22;bolt&#x22; }]" />

<TutorialVideo episode="ep08" start="157" />

## قراءة صفحة الاستخدام [#قراءة-صفحة-الاستخدام]

تجمع منطقة الاستخدام في لوحة التحكم بين سياق الفوترة والموارد التي قد توقف التشغيل: الخطة الحالية، ورصيد الأرصدة، وعدد المواقع المسموح به، ودقائق الصوت المباشر، وخيارات الشحن الإضافي، وإجراءات الفوترة. راجعها قبل الإطلاق، وبعد إضافة تضمين (embed) أو موصّل أو عميل API عالي الحجم.

لا تفسّر أي رقم على أنه حصة شاملة. فكل استحقاق يحمي موردًا مختلفًا.

## التمييز بين الأرصدة والحدود [#التمييز-بين-الأرصدة-والحدود]

| المورد                         | متى يُعاد ضبطه أو ينتهي                      | ما يحدث عند بلوغ الحد                                    |
| ------------------------------ | -------------------------------------------- | -------------------------------------------------------- |
| أرصدة الذكاء الاصطناعي الشهرية | تُرحَّل لدورة إضافية واحدة ثم تنتهي صلاحيتها | قد تُرفض إجراءات الذكاء الاصطناعي/المعرفة/الصوت المحتسبة |
| الأرصدة المشتراة               | لا تنتهي صلاحيتها ما دام الاشتراك نشطًا      | تستمر في تمويل العمل المحتسب ما دام الوصول فعّالًا       |
| عدد المواقع                    | استحقاق مرتبط بالخطة                         | يُمنع إنشاء موقع آخر                                     |
| دقائق الصوت المباشر            | الحصة الشهرية للخطة                          | تُقيَّد جلسات الوقت الفعلي الجديدة أو الجارية أو تُنهى   |
| طلبات API                      | لكل مفتاح API في الدقيقة                     | يعيد الطلب الرمز `429` مع ترويسات إعادة المحاولة         |

لا تشتري الأرصدة سعة إضافية لمعدل طلبات API ولا مواقع ولا دقائق مباشرة. كما أن الاستحقاق لا يضمن توفر مسار الأرصدة/المزوّد اللازم لإتمام العملية.

## ما الذي يستهلك الأرصدة [#ما-الذي-يستهلك-الأرصدة]

قد يشمل العمل المحتسب إنشاء الموقع/الـ agent، وإجابات الـ agent العادية، وتضمينات المعرفة (embeddings)، ونسخ الوسائط الصوتية والمرئية إلى نص، وتحويل النص إلى كلام، والصوت عبر الموصّلات. تختلف التكلفة بحسب المزوّد والنموذج وطول الموجّه/السياق وطول المخرجات ومدة الصوت ونوع العملية. لذلك لا يوجد سعر ثابت وشامل بالأرصدة لـ«رسالة» واحدة.

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

## قراءة سجل الاستخدام [#قراءة-سجل-الاستخدام]

يعرض **سجل الاستخدام** الأرصدة النهائية التي استُهلكت فعليًا في كل عملية مكتملة. أما حجوزات التفويض المؤقتة وتسويات الاحتياطي وعمليات الاسترداد فتبقى تفاصيل محاسبية داخلية ولا تظهر كصفوف منفصلة للعملاء. تُعرض عمليات التضمين الصغيرة جدًا بالشكل `<0.001` بدل تقريبها إلى صفر.

**تغيرات الرصيد الأخرى** جدول منفصل لمنح أرصدة الخطة، وعمليات الشحن الإضافي، وانتهاء الصلاحية، والتعديلات اليدوية. ولا يكرر الاستخدام العادي للذكاء الاصطناعي. وبينما تكون العملية قيد التنفيذ، قد يعكس الرصيد القابل للإنفاق حجزًا مؤقتًا قبل ظهور صف الاستخدام النهائي أو قبل تحرير العملية الفاشلة؛ حدّث الصفحة بعد الاكتمال عند مطابقة إجراء انتهى للتو.

## الأرصدة الشهرية والمشتراة [#الأرصدة-الشهرية-والمشتراة]

تأتي الحصة الشهرية من الخطة النشطة. تُرحَّل الأرصدة الشهرية غير المستخدمة لدورة إضافية واحدة ثم تنتهي صلاحيتها. تضيف الباقات لمرة واحدة 1,000 رصيد مقابل 8 دولارات، أو 5,000 مقابل 35 دولارًا، أو 15,000 مقابل 90 دولارًا؛ ولا تنتهي صلاحية الأرصدة المشتراة ما دام الاشتراك نشطًا.

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

## الشحن الإضافي التلقائي [#الشحن-الإضافي-التلقائي]

لا يتوفر الشحن الإضافي التلقائي إلا بعد تفعيل الخصم التلقائي من البطاقة في Make Agent Fast؛ وإلى أن يحدث ذلك تذكر الصفحة أنه غير متاح. وحيثما يكون متاحًا، فإنه يشتري لك باقة أرصدة عندما ينخفض الرصيد إلى حد تختاره. فعّله من **الاستخدام والأرصدة ← الشحن الإضافي التلقائي**: اختر الحد (بين 50 و5,000 رصيد) والباقة المراد شراؤها. يُخصم المبلغ من البطاقة المحفوظة مسبقًا لدى مزوّد الدفع؛ أضف تلك البطاقة أو غيّرها عبر رابط بوابة العميل المجاور للنموذج.

الضمانات المتّبعة مقصودة. تُنفَّذ عملية شراء واحدة فقط في كل مرة، وتذكر الصفحة أن عملية شراء قيد التنفيذ أثناء تسويتها. يُسمح بثلاث عمليات شراء تلقائية كحد أقصى في اليوم. تظهر الأرصدة عند تسوية الدفع، لا عند بدء الخصم. إذا رُفضت البطاقة فلا تُضاف أرصدة، وتعرض الصفحة آخر خطأ، ويُرسل بريد إلكتروني واحد في ذلك اليوم يوضح ما ينبغي إصلاحه؛ ولا يُعاد الخصم إلى أن تعمل وسيلة الدفع.

لا يتوفر الشحن الإضافي التلقائي إلا حيث يكون الخصم دون حضور المستخدم (off-session) مفعّلًا وتوجد بطاقة محفوظة. وعندما يكون غير متاح تذكر الصفحة ذلك بدلًا من عرض مفتاح تبديل لا يؤدي أي وظيفة.

## الإضافات [#الإضافات]

لا يمكن شراء الإضافات إلا بعد طرحها للبيع: تظهر الإضافة المطروحة ضمن **الاستخدام والأرصدة ← الإضافات**، وتُخفى البطاقة عندما لا تُطرح أي إضافة. أما الإضافة التي تدفع مقابلها بالفعل فتبقى مدرجة دائمًا حتى تتمكن من إلغائها. تضيف الإضافات المطروحة سعة فوق الخطة الحالية، وتُفوتَر شهريًا، ويمكن إلغاؤها في أي وقت.

| الإضافة      | السعر عند طرحها             | ملاحظات                                                                        |
| ------------ | --------------------------- | ------------------------------------------------------------------------------ |
| agent إضافي  | 10 دولارات لكل agent شهريًا | يمكن شراء أكثر من واحد؛ وتضيف كل إضافة خانة agent واحدة. مضمّنة في Scale.      |
| إزالة الشارة | 9 دولارات شهريًا            | تخفي "Made with Make Agent Fast" من الأداة المضمّنة. مضمّنة في Operate وScale. |

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

## احتساب الصوت المباشر [#احتساب-الصوت-المباشر]

تتضمن خطة Operate مدة 30 دقيقة مباشرة شهريًا، وتتضمن Scale مدة 90 دقيقة. ولكل مكالمة أيضًا حد تلقائي للمدة يضبطه المالك من 30 ثانية إلى 20 دقيقة. عند إصدار رمز المكالمة المباشرة، يُخصم من المحفظة مسبقًا ما يعادل الحد الأقصى للمدة الذي يفوّضه الخادم، بما لا يتجاوز الحصة الشهرية المتبقية. وتُحجز المدة نفسها من حصة الدقائق المباشرة حتى لا تتمكن المكالمات المتزامنة من تجاوزها.

تنتقل الوسائط المباشرة بين المتصفح ومزوّد الوقت الفعلي مباشرة، لذلك لا يستطيع الخادم التحقق بصورة مستقلة من مدة أقصر يبلغ عنها العميل. ولهذا لا يُسترد جزء من الوقت غير المستخدم بعد تسليم الرمز؛ وتُحتسب الجلسة المهجورة أو غير المبلَّغ عنها عند حدها المفوَّض. أما أي فشل من جهة الخادم قبل تسليم الرمز فيُحرّر الخصم. أنهِ المكالمات بشكل سليم لإغلاق الجلسة سريعًا، لكن توقّع الأرصدة بناءً على حد المكالمة المضبوط لا على مدة الحديث المتوقعة من المتصل.

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

## توقّع الاستخدام [#توقّع-الاستخدام]

1. اختر أسئلة زوار تمثيلية قصيرة وعادية وطويلة.
2. اختبر النص، والإجابات الكثيفة بالمعرفة، والرسائل الصوتية، والمكالمات المباشرة كلًّا على حدة.
3. سجّل التغيرات في الأرصدة/الدقائق لمجموعة اختبارات القبول.
4. اضرب في حركة الزيارات اليومية المتوقعة وتوزيع القنوات.
5. أضف هامشًا لإعادة المحاولات وعمليات الزحف وأعطال المزوّدين وضمان الجودة الداخلي والحملات وذروات الزيارات.
6. أعد التحقق بعد تغيير النموذج أو المزوّد أو حجم المصدر أو طول الإجابة أو سلوك الصوت.

استخدم التحليلات والمحادثات لمعرفة سبب النمو. فارتفاع الزيارات، أو عميل API يعمل في حلقة متكررة، أو مفتاح مسرَّب، أو تضمين منسوخ على أصل غير مقصود، أو إعادة محاولة من موصّل، أو مهمة فهرسة متكررة، يتطلب كل منها حلًا مختلفًا.

## منع الاستخدام غير المتوقع [#منع-الاستخدام-غير-المتوقع]

* قيّد التضمينات على الأصول (origins) المقصودة بدقة.
* امنح مفاتيح API أصغر النطاقات الممكنة، وافصل المفاتيح بحسب الخدمة/البيئة.
* اجعل عمليات التعديل idempotent والتزم بترويسات إعادة المحاولة للرمز `429`.
* تحقق من توقيعات webhook وأزل تكرار معرّفات الأحداث.
* بدّل فورًا أي بيانات اعتماد مسرَّبة لـ API/المزوّد/الموصّل.
* أبقِ الـ agents العامة ضمن حدود واضحة عبر تعليمات الشخصية والإجابة.
* أزل الأتمتة القديمة ونُسخ المعاينة والموصّلات والمفاتيح غير المستخدمة.
* نبّه المسؤولين التشغيليين قبل أن تقترب الأرصدة أو الدقائق المباشرة من الصفر.

## التحقيق في ارتفاع مفاجئ [#التحقيق-في-ارتفاع-مفاجئ]

سجّل مساحة العمل/الموقع المتأثر، والنطاق الزمني، والقناة، وعملية النشر، والتغييرات الأخيرة. قارن الاستخدام بالتحليلات والطوابع الزمنية للمحادثات ومعرّفات طلبات API وسجلات تسليم webhook وحالة آخر حدث/خطأ للموصّل. لا ترسل مفاتيح بنص صريح أو محتوى الزوار إلى الدعم ما لم تتطلب ذلك صراحةً عملية آمنة معتمدة.

احتوِ المصدر أولًا: عطّل موصّلًا، أو اسحب مفتاحًا، أو أزل أصلًا غير مقصود، أو أوقف حلقة إعادة المحاولة في العميل. ثم احتفظ بالأدلة الآمنة، وبدّل بيانات الاعتماد عند الحاجة، وأعد تفعيل مسار واحد في كل مرة.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                            | ما يجب فحصه                                                                               |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| نفدت الأرصدة رغم وجود دقائق مباشرة غير مستخدمة     | الموارد منفصلة؛ أضف/جدّد الأرصدة للعمل العادي بالذكاء الاصطناعي                           |
| الرسائل الصوتية تعمل لكن المكالمة المباشرة لا تعمل | استحقاق الصوت المباشر في الخطة، والدقائق المتبقية، وتوفر مزوّد الوقت الفعلي، وحالة الجلسة |
| تم شراء شحن إضافي لكن الميزة ما زالت مقفلة         | الباقات تضيف أرصدة فقط؛ افحص الخطة واستحقاق الـ agent                                     |
| يعيد API الرمز `429` مع بقاء أرصدة                 | معدل الطلبات لكل مفتاح؛ اتبع ترويسات إعادة الضبط/المحاولة                                 |
| ينخفض الرصيد بشكل غير متوقع                        | التضمينات والموصّلات ومفاتيح API والفهرسة والصوت وإعادات محاولة المزوّد/العميل الأخيرة    |

راجع [الخطط والأسعار](/ar/docs/account/pricing) للاطلاع على جدول الاستحقاقات الحالي.

---

# النطاقات المخصصة

Source: /ar/docs/publish/custom-domains.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: &#x22;نظرة عامة على التضمين&#x22;, icon: &#x22;embed&#x22; },
{ href: &#x22;/ar/docs/embed/html&#x22;, label: &#x22;مقتطف HTML&#x22;, icon: &#x22;code&#x22; }
]"
/>

لا تقوم Make Agent Fast **ببيع** نطاقات العملاء أو ربطها أو التحقق منها أو إعدادها. لا توجد لوحة تحكم لربط `yourname.com` أو لشراء نطاق. أما عنوان `slug.makeagent.fast` الخاص بالوكيل فيخدم صفحة الدردشة الخاصة بـ **رابط الوكيل** فقط، وليس موقعًا إلكترونيًا يمكنك إعداده.

أضف الوكيل إلى موقعك الإلكتروني الحالي باستخدام `embed.js` و`data-agent="<slug>"`. المعرّف المختصر (slug) هو معرّف التضمين وعنوان رابط الوكيل في الوقت نفسه، وليس نطاقًا يمكنك إعداده.

تُتجاهل أو تُلغى أي أحداث متبقية من الإضافة القديمة للنطاقات المخصصة في Polar، ولا تُنشئ رصيدًا أبدًا.

راجع [نظرة عامة على التضمين](/ar/docs/embed/overview) و[HTML وJavaScript](/ar/docs/embed/html).

---

# رابط الوكيل

Source: /ar/docs/publish/hosted-sites.md

{/* docs-visuals */}

<DocsChipRow
  items="[
{ href: &#x22;/ar/docs/build/appearance&#x22;, label: &#x22;العرض&#x22;, icon: &#x22;spark&#x22; },
{ href: &#x22;/ar/docs/embed/overview&#x22;, label: &#x22;التضمين&#x22;, icon: &#x22;embed&#x22; }
]"
/>

يحصل كل وكيل على **رابط الوكيل**: صفحة دردشة عامة واحدة على العنوان `https://YOUR_SLUG.makeagent.fast`. تعرض الصفحة شعار نشاطك التجاري واسمه، وسطرًا واحدًا عمّا يفعله الوكيل، وبعض المعلومات من ورقة الحقائق، والدردشة مفتوحة مسبقًا، والشعارات الرسمية للقنوات المتصلة. إنه رابط إلى الدردشة وليس موقعًا إلكترونيًا ولا صفحة رئيسية. **لا تحصل الوكلاء الجدد على صفحة تسويقية مستضافة** — فمواقع التسويق المولَّدة لم تعد موجودة، ولا تزال الطريقة الرئيسية للوصول إلى العملاء هي التضمين في موقعك الحالي. راجع [نظرة عامة على التضمين](/ar/docs/embed/overview).

لا تزال صفحات المستأجرين المنشورة سابقًا (بما فيها العرضان التجريبيان العامان `demo` و`demo-business`) تظهر على نطاقاتها الفرعية كبقايا من النظام السابق. النطاقات المخصصة غير متاحة. المعرّف المختصر (slug) هو معرّف التضمين (`data-agent`) وعنوان رابط الوكيل، وليس نطاقًا تقوم بإعداده.

<TutorialVideo episode="ep02" start="141" />

## لا يزال المعرّف المختصر هو معرّف التضمين [#لا-يزال-المعرّف-المختصر-هو-معرّف-التضمين]

استخدم اسمًا قصيرًا تتعرّف عليه بسهولة. يجب ألا يتعارض المعرّف المختصر الصالح مع مستأجر آخر أو مع مسار محجوز في المنصة مثل `docs` أو `dashboard` أو `api`. تعامل معه على أنه معلومة عامة. قد يؤدي تغييره بعد الإطلاق إلى تعطّل عمليات التضمين ورابط الوكيل.

## رابط الوكيل [#رابط-الوكيل]

تُفعِّل خطوة الإعداد الأخيرة رابط الوكيل لتتمكن من تجربة الوكيل على هاتفك ضمن **جرّب على هاتفك**. يمكنك تشغيله أو إيقافه لاحقًا عبر **رابط الوكيل** في تبويب **العرض** بصفحة الوكيل؛ ويظهر الرابط ورمز QR الخاص به طوال فترة التشغيل. يؤدي إيقافه إلى إزالة الرابط وحفظ اختيارك. لا يمكن تفعيل رابط يتضمن محتوى لا يجتاز فحوصات البريد المزعج.

لا تتم فهرسة الصفحة في محركات البحث. شارك الرابط في الأماكن التي لا يمكن فيها تشغيل سكربت — مثل قائمة Naver Place أو قناة Kakao أو نبذة Instagram أو توقيع البريد الإلكتروني أو رمز QR مطبوع.

تُحفَظ تغييرات **العرض** (وشارة العلامة التجارية) تلقائيًا وتُطبَّق على التضمين المباشر، وعلى الودجت في رابط الوكيل، وعلى أي صفحة مستضافة متبقية دون الحاجة إلى إعادة النشر. راجع [المظهر](/ar/docs/build/appearance).

## ربط واجهات أخرى [#ربط-واجهات-أخرى]

تُوجِّه موصّلات المراسلة المحادثات إلى الوكيل نفسه مع الحفاظ على هوية المحادثة الخاصة بكل قناة. لا يؤدي تشغيل ودجت الموقع إلى تثبيت المقتطف البرمجي تلقائيًا ولا إلى إعداد webhooks لدى مزوّدي الخدمة؛ أكمل هذه الأدلة بشكل منفصل.

بالنسبة إلى Notion وLinktree والواجهات الأخرى التي لا تستطيع تحميل JavaScript عشوائي، شارك رابط الوكيل، أو أضف رابطًا إلى صفحة في موقعك تتضمن التضمين. راجع [Notion وLinktree](/ar/docs/embed/notion-linktree).

## إلغاء النشر [#إلغاء-النشر]

يؤدي إيقاف رابط الوكيل (أو إرسال `POST /sites/{site_id}/publish` مع `{ "published": false }`) إلى إزالة صفحة الدردشة العامة وأي صفحة مستضافة متبقية. أما إخفاء ودجت الموقع عبر **إظهاره على موقعي** فهو مفتاح منفصل. لا يحذف أيٌّ منهما الموقع أو مصادر المعرفة أو الوكلاء أو سجل المحادثات أو إعدادات المزوّد الخارجي. قد تستمر روبوتات المراسلة المتصلة في الرد؛ لذا عطّل كل موصّل أو أزله بشكل منفصل.

## استكشاف الأخطاء وإصلاحها [#استكشاف-الأخطاء-وإصلاحها]

| العَرَض                                   | ما يجب التحقق منه                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| يعرض رابط الوكيل رسالة غير متاح/غير موجود | أن **رابط الوكيل** مفعّل في تبويب **العرض**، وصحة المعرّف المختصر بالضبط، وأن الوصول إلى الحساب نشط |
| لا يظهر تغيير أجريته في لوحة التحكم       | الوكيل الصحيح، ونصيحة **تم الحفظ** بجوار التغيير، واختبار **التضمين** أو رابط الوكيل في نافذة خاصة  |
| يرد الموصّل بينما التضمين متوقف           | هذا متوقع؛ عطّل الموصّل بشكل منفصل إذا كان يجب إيقاف الوصول عبر القناة بالكامل                      |

---

# اربط مساعد الذكاء الاصطناعي الخاص بك

Source: /ar/docs/tutorials/ai-assistants.md

<TutorialEpisode
  episode="ep10"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[12, &#x22;ما الذي يستطيع تطبيق الذكاء الاصطناعي فعله&#x22;],
[33, &#x22;صفحة إعداد الوكيل&#x22;],
[46, &#x22;انسخ موجّه الإعداد&#x22;],
[58, &#x22;الصقه في Claude ووافق&#x22;],
[87, &#x22;اسأل عن وكلائك&#x22;],
[107, &#x22;التقرير الأسبوعي&#x22;],
[119, &#x22;احفظ إجابة أفضل&#x22;],
[130, &#x22;Codex&#x22;],
[147, &#x22;Cursor وChatGPT&#x22;],
[165, &#x22;إلغاء الوصول&#x22;],
[177, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [استخدم Claude وCodex وCursor وChatGPT](/ar/docs/operate/ai-assistants)
* [إعداد الوكيل](/connect)

---

# التحليلات والفريق والفوترة

Source: /ar/docs/tutorials/analytics-team-billing.md

<TutorialEpisode
  episode="ep08"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[13, &#x22;الأرقام الرئيسية والمقارنة&#x22;],
[31, &#x22;الاتجاهات&#x22;],
[46, &#x22;مسار التحويل وأهم المصادر&#x22;],
[65, &#x22;ما يسأل عنه الزوار&#x22;],
[85, &#x22;الفريق وصلاحيات الوصول&#x22;],
[116, &#x22;التنبيهات&#x22;],
[132, &#x22;خطتك&#x22;],
[157, &#x22;الاستخدام والرصيد&#x22;],
[191, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [التحليلات](/ar/docs/operate/analytics)
* [الرصيد والاستخدام](/ar/docs/operate/usage)
* [الخطط والأسعار](/ar/docs/account/pricing)
* [الأمان](/ar/docs/account/security)

---

# أنشئ وكيلك

Source: /ar/docs/tutorials/build-agent.md

<TutorialEpisode
  episode="ep01"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[14, &#x22;إنشاء وكيل جديد&#x22;],
[33, &#x22;الموقع الإلكتروني والاسم والمهمة واللغات&#x22;],
[61, &#x22;الإنشاء انطلاقًا من موقعك الإلكتروني&#x22;],
[82, &#x22;ثلاثة فحوصات سريعة&#x22;],
[110, &#x22;اختر أين يجيب الوكيل&#x22;],
[129, &#x22;صفحة الوكيل&#x22;],
[153, &#x22;اختبر وكيلك&#x22;],
[168, &#x22;أضف المعرفة والأسئلة والأجوبة&#x22;],
[218, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [إنشاء وكيل](/ar/docs/build/create-agent)
* [مصادر المعرفة](/ar/docs/build/knowledge)
* [البدء السريع](/ar/docs/getting-started/quickstart)

---

# صندوق الوارد الخاص بك

Source: /ar/docs/tutorials/inbox.md

<TutorialEpisode
  episode="ep06"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[14, &#x22;المحادثات وعوامل التصفية&#x22;],
[37, &#x22;فتح محادثة&#x22;],
[50, &#x22;الرد بنفسك&#x22;],
[71, &#x22;تعديل إجابة&#x22;],
[95, &#x22;الإشعارات&#x22;],
[117, &#x22;التنبيهات على هاتفك&#x22;],
[134, &#x22;الموافقات&#x22;],
[151, &#x22;التذاكر&#x22;],
[171, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [المحادثات والـ Leads](/ar/docs/operate/conversations)
* [الإشعارات](/ar/docs/operate/notifications)
* [تغيير الإجراءات](/ar/docs/build/change-actions)

---

# Instagram: الرسائل المباشرة والتعليقات

Source: /ar/docs/tutorials/instagram.md

<TutorialEpisode
  episode="ep05"
  chapters="[
[0, &#x22;المقدمة&#x22;],
[15, &#x22;ما تحتاج إليه&#x22;],
[32, &#x22;الربط عبر Meta&#x22;],
[46, &#x22;اختيار حسابك&#x22;],
[60, &#x22;اختبار الرسائل المباشرة وتفعيل ردود الذكاء الاصطناعي&#x22;],
[78, &#x22;وكيلك في الرسائل المباشرة على Instagram&#x22;],
[95, &#x22;الرد على التعليقات (قريبًا)&#x22;],
[134, &#x22;محادثات Instagram في قسم المحادثات&#x22;],
[154, &#x22;الخلاصة&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [Instagram](/ar/docs/connectors/instagram)
* [المحادثات والعملاء المحتملون](/ar/docs/operate/conversations)

---

# العملاء المحتملون وخط المبيعات

Source: /ar/docs/tutorials/leads-sales.md

<TutorialEpisode
  episode="ep07"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[14, &#x22;تحديد المهمة البيعية&#x22;],
[33, &#x22;خط المبيعات والعملاء المحتملون&#x22;],
[62, &#x22;لوحة الفرص&#x22;],
[90, &#x22;سياسة الرد وإذن التواصل&#x22;],
[108, &#x22;سجل الفرصة&#x22;],
[123, &#x22;حزم المبيعات والتجارب الموجَّهة&#x22;],
[146, &#x22;البث عبر KakaoTalk&#x22;],
[168, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [البث](/ar/docs/operate/broadcasts)
* [المحادثات والعملاء المحتملون](/ar/docs/operate/conversations)

---

# Messenger وDiscord وKakaoTalk

Source: /ar/docs/tutorials/more-channels.md

<TutorialEpisode
  episode="ep09"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[15, &#x22;النمط نفسه في كل مكان&#x22;],
[31, &#x22;Messenger: سنتولى ربطه نيابةً عنك&#x22;],
[55, &#x22;Messenger: بيانات الاعتماد الخاصة بك&#x22;],
[67, &#x22;Messenger: webhook&#x22;],
[89, &#x22;Discord Developer Portal&#x22;],
[107, &#x22;ربط Discord&#x22;],
[123, &#x22;استخدام /ask في Discord&#x22;],
[145, &#x22;KakaoTalk: قائمة التحقق في Open Builder&#x22;],
[171, &#x22;KakaoTalk: بيانات الاعتماد والسر الخاص بالبوت&#x22;],
[196, &#x22;KakaoTalk أثناء العمل&#x22;],
[218, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [Messenger](/ar/docs/connectors/messenger)
* [Discord](/ar/docs/connectors/discord)
* [KakaoTalk](/ar/docs/connectors/kakao)

---

# Telegram: البوتات والمجموعات

Source: /ar/docs/tutorials/telegram.md

<TutorialEpisode
  episode="ep03"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[15, &#x22;الخطة&#x22;],
[27, &#x22;فتح القنوات&#x22;],
[45, &#x22;إنشاء بوت باستخدام BotFather&#x22;],
[80, &#x22;لصق الرمز المميز والربط&#x22;],
[103, &#x22;اختبار القناة وتفعيل ردود الذكاء الاصطناعي&#x22;],
[132, &#x22;أول محادثة خاصة&#x22;],
[151, &#x22;تفعيل الردود في المجموعات&#x22;],
[167, &#x22;إضافة البوت إلى مجموعة&#x22;],
[182, &#x22;كيف يتصرف في المجموعات&#x22;],
[202, &#x22;قواعد المجموعات ونصيحة احترافية&#x22;],
[224, &#x22;محادثات Telegram في المحادثات&#x22;],
[243, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [Telegram](/ar/docs/connectors/telegram)
* [المحادثات والعملاء المحتملون](/ar/docs/operate/conversations)

---

# أضف الوكيل إلى موقعك

Source: /ar/docs/tutorials/website.md

<TutorialEpisode
  episode="ep02"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[13, &#x22;التثبيت على موقعك&#x22;],
[25, &#x22;عناوين المواقع المسموح بها&#x22;],
[48, &#x22;انسخ الكود المناسب لمنصتك&#x22;],
[81, &#x22;الأداة على موقعك&#x22;],
[92, &#x22;التحقق من موقعي&#x22;],
[108, &#x22;الأنماط الجاهزة والألوان&#x22;],
[128, &#x22;الفقاعة العائمة&#x22;],
[141, &#x22;رابط الوكيل ورمز QR&#x22;],
[163, &#x22;إخفاء الأداة&#x22;],
[175, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [نظرة عامة على التضمين](/ar/docs/embed/overview)
* [العرض](/ar/docs/build/appearance)
* [رابط الوكيل](/ar/docs/publish/hosted-sites)

---

# WhatsApp

Source: /ar/docs/tutorials/whatsapp.md

<TutorialEpisode
  episode="ep04"
  chapters="[
[0, &#x22;مقدمة&#x22;],
[15, &#x22;ما الذي تحتاج إليه&#x22;],
[31, &#x22;إعداد الرقم والربط عبر Meta&#x22;],
[49, &#x22;التسجيل في Meta&#x22;],
[65, &#x22;اختيار رقمك&#x22;],
[78, &#x22;اختبار القناة وتفعيل ردود الذكاء الاصطناعي&#x22;],
[106, &#x22;وكيلك على WhatsApp&#x22;],
[124, &#x22;نافذة الـ 24 ساعة&#x22;],
[140, &#x22;محادثات WhatsApp في المحادثات&#x22;],
[153, &#x22;سنتولى ربطه نيابةً عنك&#x22;],
[165, &#x22;ملخص&#x22;]
]"
/>

## أدلة ذات صلة [#أدلة-ذات-صلة]

* [WhatsApp](/ar/docs/connectors/whatsapp)
* [المحادثات والعملاء المحتملون](/ar/docs/operate/conversations)