# الدوال المخصصة

تسمح الوظائف المخصصة لروبوت الذكاء الاصطناعي الخاص بك بالاتصال بأنظمة أخرى أثناء المحادثات المباشرة. فبدلاً من قول "سأتحقق من الأمر وأعود إليك"، يمكن للروبوت البحث عن حالة طلب، أو التحقق من المخزون، أو إنشاء سجل في نظام إدارة علاقات العملاء (CRM) الخاص بك (وهو البرنامج الذي تستخدمه لتتبع العملاء المحتملين والعملاء، مثل HubSpot أو Salesforce) - كل ذلك في الوقت الفعلي، بينما ينتظر العميل.


---

## الدوال المخصصة مقابل خطافات الويب (Webhooks)

هذه هي نقطة الالتباس الأكثر شيوعاً، لذا يجدر بنا توضيحها قبل البدء في بناء أي شيء.

| | خطافات الويب (Webhooks) | الدوال المخصصة |
|---|----------|------------------|
| **الاتجاه** | أحادي الاتجاه (إرسال فقط) | ثنائي الاتجاه (استدعاء وانتظار) |
| **ما يفعله الروبوت** | يرسل إشعاراً عند وقوع حدث ما، ثم يواصل عمله. | يستدعي نظاماً خارجياً، **ويتوقف مؤقتاً بانتظار الرد**، ويستخدم النتيجة التي تصله لمواصلة المحادثة. |
| **الرؤية للمحادثة** | النتيجة النهائية غير مرئية للروبوت — فهو لا يرى ما حدث أبداً. | يتم تغذية الرد مباشرة إلى الذكاء الاصطناعي، بحيث يمكن للروبوت اقتباسه، وتحليله، والرد به على العميل. |
| **الأفضل لـ** | تسجيل الأحداث، ومزامنة البيانات مع نظام CRM، وتفعيل الأتمتة الخارجية (مثل Zapier، وMake، وn8n). | أي شيء يحتاج فيه الروبوت إلى **إجابة** قبل أن يتمكن من الرد — مثل عمليات البحث المباشرة، والأسعار الفورية، وتوليد المحتوى أثناء المحادثة. |

**متى تختار أياً منهما:** إذا كنت تحتاج فقط إلى *إخبار* نظام آخر بوقوع شيء ما، فاستخدم خطاف الويب (webhook) - وهو رسالة آلية أحادية الاتجاه تُرسل إلى نظام آخر (راجع **الإعدادات ← عمليات التكامل ← خطافات الويب**). أما إذا كان الروبوت بحاجة إلى *تعلم* شيء ما من نظام آخر قبل متابعة المحادثة، فاستخدم وظيفة مخصصة.

---

## أمثلة على ما تفتحه الدوال المخصصة من إمكانيات

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

- **التحقق المباشر من مخزون Shopify أو WooCommerce** — قبل تقديم عرض سعر للعميل، يتحقق الروبوت من المخزون في الوقت الفعلي ويجيب "نعم، لدينا 12 قطعة بمقاس M" بدلاً من "دعني أتحقق وأعود إليك".
- **التسعير الديناميكي من جداول بيانات Google** — يقوم فريق المبيعات بتحديث الأسعار في جدول بيانات؛ فيقرأ الروبوت أحدث صف أثناء المحادثة ويقدم السعر الحالي دون أن يضطر أحد لتعديل إعدادات الذكاء الاصطناعي.
- **وكيل الاتصال الصوتي بالذكاء الاصطناعي** — عندما يؤهل الروبوت عميلاً محتملاً، فإنه يطلق وكيل اتصال صوتي (على سبيل المثال، باستخدام تقنية ElevenLabs) للاتصال بالعميل مرة أخرى في غضون دقائق، ويؤكد للعميل "رائع، توقع مكالمة خلال الدقائق الخمس القادمة".
- **توليد ملف PDF لعرض السعر وإرساله بالبريد الإلكتروني أثناء المحادثة** — يجمع الروبوت المتطلبات، ويستدعي أداة بناء عروض الأسعار الخاصة بك، ويحصل على رابط ملف PDF، ثم يخبر العميل "لقد أرسلت عرض السعر للتو إلى بريدك الإلكتروني — تحقق من صندوق الوارد".

---

## ماذا يمكن للدوال المخصصة أن تفعل؟

فكر في الدوال المخصصة كأداة تمنح الروبوت الخاص بك قدرات خارقة تتجاوز مجرد الدردشة. إليك أمثلة من الواقع:

- **تتبع الطلبات** - يسأل العميل "أين طلبي؟" فيتحقق الروبوت من نظام التجارة الإلكترونية الخاص بك ويرد بحالة الشحن ورابط التتبع.
- **التحقق من المخزون** - "هل يتوفر هذا بمقاس 10؟" يتحقق الروبوت من نظام المخزون لديك ويقدم إجابة فورية.
- **تحديثات نظام CRM** - عندما يؤهل الروبوت عميلاً محتملاً، فإنه يقوم تلقائياً بإنشاء أو تحديث سجل في HubSpot أو Salesforce أو أي نظام CRM آخر.
- **توليد عروض الأسعار** - يجمع الروبوت متطلبات العميل ويولد عرض سعر مخصصاً من نظام التسعير الخاص بك.
- **الحجز** - يقوم الروبوت بإنشاء موعد في نظام الحجز الخارجي الخاص بك.
- **التحقق من الخصومات** - "هل رمز القسيمة هذا صالح؟" يتحقق الروبوت ويؤكد ذلك.
- **البحث عن الحسابات** - يتم التعرف تلقائياً على العميل العائد ويتم استرجاع تفاصيل حسابه.

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

---

## كيف تعمل الدوال المخصصة (النسخة المبسطة)

إليك ما يحدث عند تفعيل دالة مخصصة أثناء المحادثة:

1. **يسأل العميل شيئاً** يتطلب بيانات فورية (على سبيل المثال: "أين طلبي؟")
2. **يتعرف البوت** على حاجته لاستخدام دالة مخصصة للإجابة
3. **يجمع البوت** أي معلومات مفقودة من العميل (على سبيل المثال: "ما هو رقم طلبك؟")
4. **ترسل المنصة طلباً** إلى نظامك (موقعك الإلكتروني، أو نظام إدارة علاقات العملاء CRM، أو أي أداة أخرى) مع التفاصيل ذات الصلة
5. **يستجيب نظامك** بالبيانات (على سبيل المثال: حالة الطلب، رقم التتبع، تاريخ التسليم)
6. **يقرأ البوت الاستجابة** ويصيغ رداً طبيعياً: "تم شحن طلبك ORD-4582 ومن المتوقع وصوله بحلول يوم الجمعة!"

### تكلفة استدعاء الدالة المخصصة

تتم محاسبة كل استدعاء لدالة مخصصة وفقاً لمستوى جودة الذكاء الاصطناعي (AI Quality) الخاص بالوكيل (Agent) لديك:

| مستوى جودة الذكاء الاصطناعي | الرصيد لكل استدعاء دالة مخصصة | مع ربط مفتاح Anthropic الخاص بك (BYOK) |
|---|---|---|
| Pro | 1 رصيد | 0 رصيد — يعمل باستخدام مفتاحك |
| Economy (مهمل) | 0.5 رصيد | 0 رصيد — يعمل باستخدام مفتاحك |
| Max | 0.25 رصيد | لا يزال 0.25 رصيد، تُحتسب حتى مع ربط مفتاحك الخاص، لأن Max يعمل على نموذجنا الخاص |
| Mini | 0.15 رصيد | لا يزال 0.15 رصيد، تُحتسب حتى مع ربط مفتاحك الخاص، لأن Mini يعمل على نموذجنا الخاص |

---

## إعداد دالة مخصصة (خطوة بخطوة)

1. في الشريط الجانبي الرئيسي، تحت **AI Studio**، انقر على **Custom Functions**.


2. انقر على الزر الأخضر **+ Add Function** (أو **New function**) في أعلى اليمين.


تعرض قائمة الدوال المخصصة جدولاً بالأعمدة التالية:

| العمود | ما يعرضه |
|--------|--------------|
| **الاسم** | اسم الدالة (على سبيل المثال: `check_order_status`) |
| **الوصف** | ملخص قصير لما تقوم به الدالة (يتم اقتطاعه إلى 50 حرفاً في الجدول) |
| **الطريقة** | طريقة HTTP المستخدمة، وتظهر كشارة ملونة: GET (أزرق)، POST (أخضر)، PUT (برتقالي)، DELETE (أحمر) |
| **تاريخ الإنشاء** | التاريخ الذي تم فيه إنشاء الدالة |

هذا يسهل عليك تصفح دوالك بلمحة سريعة والعثور على الدالة التي تحتاجها.

### الخطوة 1: امنحها اسماً ووصفاً


| الحقل | ما يجب إدخاله | مثال |
|-------|--------------|---------|
| **الاسم** | اسم قصير باستخدام الحروف والأرقام والشرطات السفلية | `check_order_status` |
| **الوصف** | اشرح ما تفعله هذه الدالة (يقرأ الذكاء الاصطناعي هذا ليقرر متى يستخدمها) | "يبحث عن الحالة الحالية لطلب العميل باستخدام رقم الطلب" |
| **الغرض (إجراء الذكاء الاصطناعي)** | أخبر الذكاء الاصطناعي بالضبط متى وكيف يستخدم هذه الدالة | "استخدم هذا عندما يسأل العميل عن حالة طلبه، أو الشحن، أو التسليم. اطلب رقم الطلب أولاً." |

**نصيحة:** كن دقيقاً جداً في الوصف والغرض. كلما كنت أكثر وضوحاً بشأن متى يجب استخدام الدالة، زادت موثوقية البوت في استخدامها في الوقت المناسب.

### الخطوة 2: إعداد الاتصال

تحتاج إلى إخبار التطبيق بمكان إرسال الطلب:

| الحقل | ما يجب إدخاله | مثال |
|-------|--------------|---------|
| **URL** | عنوان الويب لنقطة نهاية نظامك (العنوان المحدد في نظامك الذي يستقبل الطلب ويرسل البيانات مرة أخرى) | `https://api.yourstore.com/v1/orders/status` |
| **الطريقة (Method)** | نوع الطلب المراد إرساله | راجع الخيارات أدناه |

**أي طريقة تختار:**

| الطريقة | متى تستخدمها |
|--------|---------------|
| **GET** | البحث عن معلومات (حالة الطلب، المخزون، تفاصيل الحساب) |
| **POST** | إنشاء سجلات جديدة (تذاكر الدعم، العملاء المحتملين، الحجوزات) أو عمليات بحث معقدة |
| **PUT** | تحديث سجل موجود بالكامل |
| **PATCH** | تحديث جزء من سجل موجود |
| **DELETE** | حذف سجل |

إذا لم تكن متأكداً من الخيار الذي يجب استخدامه، فراجع مطور البرامج الخاص بك أو وثائق النظام الذي تتصل به. يُعد **GET** (لعمليات البحث) و **POST** (لإنشاء السجلات) هما الأكثر شيوعاً.

### الخطوة 3: إضافة ترويسات المصادقة (Authentication Headers)

تتطلب معظم الأنظمة مصادقة لقبول الطلبات. أضف أي ترويسات مطلوبة:

| الترويسة | قيمة المثال |
|--------|--------------|
| `Authorization` | `Bearer your-api-key-here` |
| `Content-Type` | `application/json` |

**نصيحة أمنية:** استخدم مفتاح API مخصصاً بصلاحيات محدودة. لا تستخدم بيانات اعتماد بمستوى المسؤول (admin).

**أين تجد مفاتيح API:** تحقق من الإعدادات أو قسم المطورين في النظام الذي تتصل به (على سبيل المثال، نظام إدارة علاقات العملاء CRM، أو منصة التجارة الإلكترونية، أو أداة الحجز).

### الخطوة 4: تحديد المدخلات (ما يرسله البوت)

معلمات الإدخال هي أجزاء المعلومات التي يجمعها البوت من المحادثة ويرسلها إلى نظامك.

لكل معلمة، يجب عليك تحديد:

| الخاصية | ماذا تعني |
|----------|--------------|
| **الاسم** | اسم المعلمة (يجب أن يطابق ما يتوقعه نظامك) |
| **النوع** | نوع البيانات (نص، رقم، صواب/خطأ، إلخ) |
| **الوصف** | أخبر الذكاء الاصطناعي بماهية هذه المعلومات ومكان العثور عليها في المحادثة |
| **مطلوب** | إذا تم ضبطه على "نعم"، سيطلب البوت من العميل هذه المعلومات قبل المتابعة |

**أنواع المعلمات المتاحة:**

| النوع | ماذا يعني |
|------|--------------|
| **string** | نص (أسماء، أرقام طلبات، عناوين) |
| **number** | قيمة رقمية (كمية، سعر) |
| **boolean** | صواب أو خطأ (قيم نعم/لا) |
| **array** | قائمة من العناصر. تُرسل كقائمة JSON حقيقية — في **Run Test** يمكنك كتابتها كـ `[8624]` أو `["a", "b"]` أو ببساطة مفصولة بفواصل (`8624, 8625`) وسيتم تحويلها لك. إذا كانت واجهة برمجة التطبيقات (API) الخاصة بك صارمة بشأن ما تحتويه القائمة — على سبيل المثال أرقام فقط — قم بتعيين **نوع العنصر** الاختياري بجوار النوع وسيتم تحويل كل قيمة في القائمة إليه. |
| **query_param** | نص يتم إرساله كمعامل URL بدلاً من إرساله في نص الطلب. استخدم هذا عندما تتوقع واجهة برمجة التطبيقات (API) الخاصة بك بيانات في الرابط (على سبيل المثال، `?order_id=123`). |

يحتوي كل معامل أيضًا على حقل اختياري لـ **مسار نص الطلب (Request body path)**. عادةً ما يتم إرسال المعامل كحقل من المستوى الأعلى في نص الطلب (أو كقيمة في سلسلة الاستعلام، بالنسبة للنوع `query_param`). إذا كانت نقطة النهاية (endpoint) الخاصة بك تتوقع أن يكون المعامل متداخلًا — على سبيل المثال `{"order": {"id": "ORD-123"}}` — فقم بتعيين المسار إلى `order.id` وسيقوم النظام بتداخل القيمة هناك نيابةً عنك.


**مثال: للبحث عن حالة الطلب، قد تقوم بتعريف ما يلي:**

- **order_number** (نص، مطلوب): "رقم طلب العميل. يبدأ عادةً بـ ORD- متبوعاً بأرقام. اطلب هذا من العميل إذا لم يذكره."
- **email** (نص، اختياري): "عنوان البريد الإلكتروني للعميل للتحقق الإضافي. مطلوب فقط إذا لم يتم العثور على تطابق باستخدام رقم الطلب وحده."

### ما يتلقاه نظامك تلقائياً

بالإضافة إلى معلمات الإدخال التي تحددها، تقوم المنصة تلقائياً بتضمين بيانات النظام مع كل طلب. تتلقى نقطة النهاية الخاصة بك هذه البيانات في حقل `system`:

| حقل النظام | ما يحتويه |
|-------------|----------------|
| `system.contactId` | معرف المنصة الخاص بجهة الاتصال في المحادثة |
| `system.campaignId` | معرف الحملة التي تنتمي إليها المحادثة |
| `system.userId` | معرف المستخدم الخاص بك |
| `system.channel` | قناة المراسلة (على سبيل المثال، `"whatsapp"`، `"instagram"`) |
| `system.contact` | سجل جهة الاتصال الكامل (الاسم، الهاتف، البريد الإلكتروني، العلامات، إلخ) |
| `system.campaign` | إعدادات الحملة |
| `system.test` | `true` إذا كان هذا اختباراً تجريبياً، و`false` للمحادثات المباشرة |

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

> **ألا تحتاج إلى بيانات النظام؟** قم بتفعيل مفتاح **تخطي بيانات النظام (Skip System Data)** في أداة إنشاء الوظائف. سيقوم البوت حينها بإرسال معلمات الإدخال التي حددتها فقط — بدون بيانات جهة الاتصال أو الحملة. استخدم هذا الخيار إذا كانت نقطة النهاية الخاصة بك ترفض الحقول غير المتوقعة أو إذا كنت ترغب ببساطة في الحصول على حمولة بيانات أخف.

### الخطوة 5: اختبرها، ثم دع البوت يقرأ الاستجابة

عادةً لا تحتاج إلى تعيين حقول الاستجابة على الإطلاق. بمجرد استجابة نقطة النهاية الخاصة بك، يقرأ البوت استجابة JSON بالكامل ويستخدم **الوصف (Description)** و **الغرض (Purpose (AI Action))** الخاصين بدالتك — بالإضافة إلى وصف كل معامل — لمعرفة ما هو مهم وتقديمه بشكل طبيعي. إن كتابة وصف واضح للدالة نفسها ("يسترجع الحالة الحالية لطلب العميل بما في ذلك معلومات الشحن والتتبع") يؤدي المهمة بشكل أفضل مما يفعله التعيين حقلًا بحقل.

إذا كانت نقطة النهاية الخاصة بك تُرجع استجابة كبيرة وكنت تريد فقط أن يرى البوت بضع قيم محددة، فافتح قسم **تعيين الاستجابة (Response mapping)** (يكون مطويًا افتراضيًا، فوق زر الاختبار مباشرةً). يختار كل صف حقلًا واحدًا من المستوى الأعلى من الاستجابة: **حقل الاستجابة (Response field)** هو اسم الحقل في رد JSON الخاص بـ API الخاص بك، و **حقل المخرجات (Output field)** هو الاسم الذي يتلقى البوت القيمة تحته. عند ملء صف واحد على الأقل، يحصل البوت فقط على القيم التي قمت بتعيينها بدلاً من نص الاستجابة الكامل. اترك القسم فارغًا للحفاظ على سلوك الاستجابة الكاملة الافتراضي.


قبل الحفظ، استخدم قسم **الاختبار (Test)** في أسفل المنشئ لإرسال الطلب تمامًا كما تم تكوينه ورؤية الاستجابة الحقيقية، دون مغادرة التطبيق:


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

---

## تعيين الوظائف لوكيل

بعد إنشاء وظيفة مخصصة، تحتاج إلى إخبار كل وكيل بالوظائف التي يمكنه استخدامها:

1. افتح [الوكيل](../ai-agents/ai-agents.md) ضمن **استوديو الذكاء الاصطناعي (AI Studio) ← وكلاء الذكاء الاصطناعي (AI Agents)**.
2. انتقل إلى علامة التبويب **قدرات الذكاء الاصطناعي (AI Abilities)**. (بالنسبة لحملة لا تزال تحتفظ بإعدادات الذكاء الاصطناعي الخاصة بها مباشرة بدلاً من وكيل منفصل، تظهر نفس القائمة في خطوة **قدرات الذكاء الاصطناعي** الخاصة بتلك الحملة بدلاً من ذلك.)
3. سترى قائمة بكل وظيفة مخصصة قمت بإنشائها. قم بتفعيل كل وظيفة تريد أن يتمكن بوت هذا الوكيل من استدعائها.
4. انقر فوق **حفظ التغييرات** في الأسفل. لا يتم تطبيق التحديدات إلا بعد حفظها.


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

---

## اختبار وظائفك المخصصة

قبل الإطلاق المباشر، اختبر الوظائف بدقة:

1. **تشغيل الاختبار المدمج** - استخدم قسم **الاختبار** داخل منشئ الوظائف (انظر أعلاه) لإجراء فحص سريع دون مغادرة التطبيق — أدخل قيمًا واقعية وانقر فوق تشغيل الاختبار.
2. **اختبار نقطة نهاية نظامك مباشرة** - بالنسبة لقائمة التحقق الكاملة أدناه، تقوم أداة مخصصة مثل Postman (أو المطور الخاص بك) بالتعمق أكثر من مجرد تشغيل اختبار واحد.
3. **الاختبار في وضع التجربة (Try Out)** - محاكاة محادثة يطلب فيها العميل شيئًا يجب أن يؤدي إلى تشغيل الوظيفة.
4. **التحقق من الاستجابة** - تأكد من أن البوت يقرأ البيانات ويعرضها بشكل صحيح.
5. **اختبار سيناريوهات الخطأ** - ماذا يحدث إذا قدم العميل رقم طلب غير صالح؟ ماذا لو كان نظامك معطلاً مؤقتًا؟

### عندما يعود الاختبار بالرمز 401 أو 403

يعني الرمز 401 أو 403 أن نقطة النهاية (endpoint) الخاصة بك قد تلقت الطلب ورفضته. العلامة الدالة على ذلك هي **عدم ظهور أي شيء في سجلاتك الخاصة** — فمعظم الأدوات ترفض المكالمات غير المصرح بها قبل أن تبدأ سير العمل، لذا لا يوجد شيء يمكنك رؤيته من جانبك ويبدو الأمر وكأن الطلب لم يصل أبداً.

غالباً ما يكون هذا بسبب عدم تطابق في المصادقة: نقطة النهاية الخاصة بك تتطلب نوعاً معيناً من بيانات الاعتماد بينما ترسل الدالة نوعاً مختلفاً. تأكد من أن الترويسة (header) التي أضفتها في [الخطوة 3](#step-3-add-authentication-headers) هي بالضبط ما يتوقعه نظامك.

النسخة الأكثر شيوعاً من هذه المشكلة هي وجود خطاف ويب (webhook) محمي بـ **المصادقة الأساسية (Basic Auth)** (توفر أدوات مثل n8n وMake ومعظم الأدوات ذاتية الاستضافة هذا الخيار كمربع اختيار على خطاف الويب نفسه) بينما ترسل الدالة ترويسة سرية مخصصة مثل `X-My-Secret`. تقبل المصادقة الأساسية ترويسة `Authorization` فقط، لذا يتم تجاهل الترويسة المخصصة ويتم رفض المكالمة. لديك خياران:

- **أوقف تشغيل المصادقة الأساسية (Basic Auth)** على خطاف الويب، وتحقق من ترويستك المخصصة داخل سير العمل بدلاً من ذلك.
- **أبقِ المصادقة الأساسية مفعلة**، وأضف ترويسة `Authorization` إلى الدالة تكون قيمتها كلمة `Basic` متبوعة بـ `username:password` المشفر بترميز base64 الخاص بك.

كلا الخيارين يعملان — فقط تأكد من توافق الطرفين.

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

رابط نقطة النهاية (URL) غير صحيح، أو أن سير العمل لم يتم نشره. في n8n تحديداً، لكل خطاف ويب رابط **اختبار (Test)** ورابط **إنتاج (Production)** منفصلان، ورابط الاختبار يعمل فقط أثناء فتحك للمحرر. انسخ رابط الإنتاج وتأكد من أن سير العمل نشط.

### رؤية حالات الفشل في "التجربة" (Try Out) والمحادثات

عندما يستدعي الذكاء الاصطناعي دالة مخصصة أثناء محادثة ويفشل الاستدعاء — بسبب بيانات اعتماد خاطئة، أو تعطل نقطة النهاية، أو انتهاء المهلة — تظهر المحادثة الآن ذلك: يظهر مؤشر أحمر مكتوب عليه **"(function name) failed"** في سلسلة المحادثة، سواء في علامة تبويب **التجربة** (Try Out) الخاصة بالوكيل أو في المحادثات الحقيقية ضمن **المحادثات** (Chats). انقر فوق المؤشر لتوسيع التفاصيل: رمز الحالة الذي أعادته نقطة النهاية الخاصة بك ونص الاستجابة، وهو ما يكفي عادةً لإخبارك بالضبط بما يجب إصلاحه (على سبيل المثال، `401` مع رسالة "unauthorized" يعني وجود مشكلة في ترويسة المصادقة، بينما يعني انتهاء المهلة أن نقطة النهاية استغرقت أكثر من 30 ثانية).

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

---

## مثال كامل: البحث عن حالة الطلب

إليك مثال مهيأ بالكامل يمكنك استخدامه كقالب:

**معلومات أساسية:**
- **الاسم:** `check_order_status`
- **الوصف:** "يسترجع الحالة الحالية لطلب العميل بما في ذلك معلومات الشحن والتتبع"
- **إجراء الذكاء الاصطناعي:** "استدعِ هذا الإجراء عندما يسأل العميل عن حالة طلبه، أو مكان وجود طرده، أو موعد وصوله. اطلب دائماً رقم الطلب أولاً."

**الاتصال:**
- **URL:** `https://api.mystore.com/orders/lookup`
- **الطريقة:** POST

**الترويسات (Headers):**
- `Authorization`: `Bearer sk_live_abc123`
- `Content-Type`: `application/json`

**معلمات الإدخال:**
- `order_number` (نص، مطلوب): "رقم الطلب المقدم من العميل"
- `customer_email` (نص، اختياري): "البريد الإلكتروني للعميل للتحقق الإضافي"

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

**كيف تبدو المحادثة:**

> **العميل:** مرحباً، أين طلبي؟
>
> **البوت:** أهلاً! يسعدني التحقق من طلبك. هل يمكنك تزويدي برقم الطلب؟
>
> **العميل:** إنه ORD-78234
>
> **البوت:** دعني أبحث عن ذلك من أجلك...
>
> تم شحن طلبك ORD-78234 وهو في الطريق إليك! تاريخ التسليم المتوقع هو 10 مارس. يمكنك تتبع طردك من هنا: https://tracking.example.com/1Z999AA1
>
> هل هناك أي شيء آخر يمكنني مساعدتك به؟

---

## مثال كامل: حالة طلب Shopify

إذا كان المتجر يعمل على Shopify، فلن تحتاج إلى مطور لبناء نقطة نهاية للبحث — يمكن لنظام Shopify نفسه الإجابة على أسئلة الطلبات مباشرة. (بالنسبة لأسئلة المنتجات والمخزون في متجر Shopify، لا تحتاج إلى وظيفة مخصصة على الإطلاق: قم بتوصيل الخادم المدمج للمتجر بدلاً من ذلك — راجع [توصيل متجر Shopify](mcp-servers.md#ready-made-example-connect-a-shopify-store).)

**أولاً، قم بإنشاء رمز وصول (access token) في Shopify.** لقد غيرت Shopify هذا الإجراء خلال عام 2026: لم يعد بالإمكان إنشاء التطبيقات داخل لوحة تحكم Shopify، وتمنحك شاشة التطبيق الجديدة **معرف عميل (Client ID)** و **سر عميل (Client secret)** بدلاً من رمز جاهز. الخطوات أدناه تحول هذه البيانات إلى رمز دائم. خصص حوالي عشر دقائق، مرة واحدة لكل متجر. (إذا كان المتجر يحتوي بالفعل على تطبيق قديم تم إنشاؤه بالطريقة القديمة، فسيستمر رمزه الحالي في العمل — انتقل مباشرة إلى الوظيفة المخصصة أدناه.)

1. انتقل إلى لوحة تحكم مطوري Shopify على [dev.shopify.com](https://dev.shopify.com)، وافتح مؤسستك، وانقر فوق **Apps → Create app**. امنحها اسماً مثل `Order lookup`.
2. امنح التطبيق إذن **read_orders**، وأصدر نسخة، وقم بتثبيت التطبيق على المتجر.
3. افتح **إعدادات** التطبيق وأضف عنوان الويب الخاص بالمتجر (على سبيل المثال `https://www.yourstore.com/`) إلى عناوين URL المسموح بإعادة التوجيه. احفظ التغييرات.
4. لا تزال في **الإعدادات**، انسخ **معرف العميل (Client ID)** و **سر العميل (Client secret)**.
5. في متصفح قمت فيه بتسجيل الدخول إلى مسؤول Shopify الخاص بذلك المتجر، افتح العنوان أدناه، مع استبدال اسم المتجر، ومعرف العميل، وعنوان إعادة التوجيه بعنوانك الخاص:
   `https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345`
   وافق على الشاشة التي تظهر. سينتقل المتصفح إلى عنوان إعادة التوجيه الخاص بك ويحتوي شريط العنوان الآن على `code=` متبوعاً بقيمة طويلة — انسخ تلك القيمة. إنها صالحة لبضع دقائق فقط، لذا انتقل مباشرة إلى الخطوة التالية.
6. استبدل ذلك الرمز بالرمز المميز (token)، وهو ما يمكنك القيام به داخل <span data-t="appName">Your AI Connector</span>. في منشئ الوظائف المخصصة، اضبط **Method** على POST و **URL** على `https://YOUR-STORE.myshopify.com/admin/oauth/access_token`، وأضف ثلاث معلمات إدخال نصية مسماة `client_id` و `client_secret` و `code`، ثم انقر فوق **Test**، واملأ القيم الثلاث، وقم بتشغيلها. تحتوي الاستجابة على `access_token` — هذا هو رمزك المميز الدائم. انسخه في مكان آمن، ثم امسح المنشئ وقم بإعداد الوظيفة الحقيقية أدناه.

**ثم قم بإعداد الوظيفة المخصصة:**

**معلومات أساسية:**
- **الاسم:** `check_shopify_order`
- **الوصف:** "يبحث عن طلب في نظام Shopify الخاص بالمتجر ويعيد حالته وتتبعه وعناصره"
- **إجراء الذكاء الاصطناعي:** "استدعِ هذا عندما يسأل العميل عن حالة طلبه أو توصيله. اطلب دائماً رقم الطلب أولاً."

**الاتصال:**
- **URL:** `https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any` — استبدل `YOUR-STORE` باسم `.myshopify.com` الخاص بالمتجر (يستخدم هذا العنوان نطاق Shopify التقني، وليس النطاق المخصص للمتجر)
- **الطريقة:** GET

**الترويسات (Headers):**
- `X-Shopify-Access-Token`: `shpat_...` (الرمز الذي حصلت عليه أعلاه)

**معلمات الإدخال (Input Parameters):**
- `name` (query_param، مطلوب): "رقم طلب العميل تماماً كما يظهر في تأكيد طلبه، بما في ذلك علامة # — على سبيل المثال #1001. اطلب من العميل تزويدك به إذا لم يذكره."

**لا حاجة لتعيين الاستجابة** — يقرأ الروبوت الطلب الذي تم إرجاعه (حالة الدفع، حالة التنفيذ، التتبع، العناصر) ويجيب بشكل طبيعي.

**من الجيد معرفة:** يمكن للرمز الذي تم إنشاؤه بهذه الطريقة رؤية الطلبات من **آخر 60 يوماً** — وهو ما يكفي لأسئلة الدعم اليومية، ولكنه لا يغطي سجل الطلبات بالكامل.

---

## مثال كامل: حجز موعد

**معلومات أساسية:**
- **الاسم:** `create_booking`
- **الوصف:** "ينشئ موعداً جديداً في نظام الحجز الخاص بنا"
- **إجراء الذكاء الاصطناعي:** "استخدم هذا بعد تأكيد التاريخ والوقت وتفاصيل الاتصال مع العميل. لا تقم بالاستدعاء حتى يؤكد العميل صراحةً رغبته في الحجز."

**الاتصال:**
- **URL:** `https://booking.mycompany.com/api/appointments`
- **الطريقة:** POST

**معلمات الإدخال:**
- `date` (نص، مطلوب): "تاريخ الموعد بتنسيق YYYY-MM-DD"
- `time` (نص، مطلوب): "وقت الموعد بتنسيق HH:MM"
- `name` (نص، مطلوب): "الاسم الكامل للعميل"
- `phone` (نص، مطلوب): "رقم هاتف العميل"
- `service_type` (نص، مطلوب): "نوع الخدمة التي يتم حجزها"

---

## مثال كامل: إضافة مشترك في النشرة الإخبارية إلى نظام إدارة علاقات العملاء (CRM) الخاص بك

نمط شائع جداً: ينتهي البوت من الإجابة، ويعرض نشرتك الإخبارية، ويرد جهة الاتصال بعنوان بريدهم الإلكتروني، ويجب أن يصل هذا العنوان إلى أداة البريد الإلكتروني الخاصة بك مباشرة. تقبل معظم أنظمة إدارة علاقات العملاء (FluentCRM، وActiveCampaign، وMailerLite، وBrevo، وغيرها) طلب POST بسيطاً لهذا الغرض تحديداً، لذا لا حاجة إلى منصة أتمتة وسيطة.

يستخدم هذا المثال **FluentCRM** على ووردبريس. الهيكل هو نفسه لأي أداة أخرى توفر لك "خطاف ويب وارد" (incoming webhook) أو نقطة نهاية "إنشاء مشترك" (create subscriber).

**أولاً، احصل على الرابط (URL) من نظام إدارة علاقات العملاء الخاص بك.** في ووردبريس، افتح **FluentCRM → Settings → Incoming Webhooks** وأنشئ خطاف ويب. اختر القائمة، والوسوم، وحالة الاشتراك التي يجب أن يحصل عليها جهات الاتصال الجديدة، ثم انسخ رابط خطاف الويب الذي يتم إنشاؤه. أي شيء تضبطه هنا يتم تطبيقه تلقائياً، لذا لا يحتاج البوت إلا إلى إرسال عنوان البريد الإلكتروني.

**ثم قم بإعداد الوظيفة المخصصة:**

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

**الاتصال:**
- **الرابط (URL):** رابط خطاف الويب الذي نسخته من نظام إدارة علاقات العملاء الخاص بك
- **الطريقة:** POST

**معلمات الإدخال:**
- `email` (سلسلة نصية، مطلوب): "عنوان البريد الإلكتروني الذي قدمه جهة الاتصال في المحادثة"
- `first_name` (سلسلة نصية، اختياري): "الاسم الأول لجهة الاتصال، إذا ذكروه"

**تخطي بيانات النظام:** قم بتشغيل هذا الخيار (**on**). يحتاج نظام إدارة علاقات العملاء الخاص بك فقط إلى الحقول المذكورة أعلاه، كما أن الحمولة (payload) الأكثر بساطة تتجنب الأخطاء الناتجة عن الأدوات التي ترفض الحقول غير المتوقعة.

**تعيين الاستجابة:** غير مطلوب هنا. لا يلزم عودة أي شيء ليتمكن البوت من المتابعة.

**لا تنسَ تشغيل الوظيفة للوكيل الذي يدير المحادثة** (راجع [تعيين الوظائف لوكيل](#assigning-functions-to-an-agent)). هذا هو السبب الأكثر شيوعاً لعدم عمل وظيفة تم إنشاؤها بشكل صحيح.

::: tip
**نصيحة:** يحتوي البوت أيضاً على أداة مدمجة **لتحديث بريد جهة الاتصال الإلكتروني** (Update Contact Email)، والتي تحفظ العنوان في سجل جهة الاتصال داخل المنصة. هذا منفصل عن هذه الوظيفة، ومفيد بجانبها — الأداة المدمجة تحافظ على اكتمال سجل جهة الاتصال الخاص بك، بينما تقوم الوظيفة المخصصة بدفع العنوان إلى نظام إدارة علاقات العملاء الخاص بك.
:::


---

## نصائح للوظائف المخصصة الموثوقة

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

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

3. **حافظ على أوقات الاستجابة أقل من 10 ثوانٍ.** إذا استغرق نظامك وقتًا أطول، ففكر في إرجاع إقرار سريع أولاً.

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

5. **اكتب أوصافاً تفصيلية.** يستخدم الذكاء الاصطناعي أوصافك لمعرفة متى يجب استدعاء الوظيفة وكيفية استخراج المعلومات الصحيحة من المحادثة. الأوصاف الغامضة تؤدي إلى أخطاء.

6. **الاختبار من خلال محادثات حقيقية.** وضع التجربة (Try Out) رائع للاختبار الأولي، ولكن راقب محادثاتك المباشرة القليلة الأولى للتأكد من أن كل شيء يعمل مع استفسارات العملاء الحقيقية.

7. **احتفظ بالسجلات من جانبك.** اطلب من مطورك تسجيل الطلبات القادمة من التطبيق حتى تتمكن من تصحيح أي مشكلات بسرعة.

8. **استخدم رابطاً نهائياً عاماً.** يجب أن يكون رابط وظيفتك عنوان ويب عاماً (HTTP/HTTPS). يتم رفض عناوين localhost وعناوين الشبكات الخاصة لأسباب أمنية، كما أن المنصة لا تتبع عمليات إعادة التوجيه — وجه الوظيفة إلى الرابط النهائي مباشرة، وليس إلى رابط يعيد التوجيه إليه.

---

## حدود التنفيذ

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


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

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

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

**الحد الأقصى لمرات التشغيل لكل نافذة زمنية.** حد لمعدل التشغيل عبر الزمن: على سبيل المثال، 5 مرات تشغيل كحد أقصى خلال 60 دقيقة. مفيد للدوال التي تستدعي خدمات خارجية مدفوعة أو تطلق عمليات أتمتة ثقيلة. يجب ملء كلا المربعين معاً (عدد مرات التشغيل ونافذة زمنية بالدقائق، تصل إلى 7 أيام).

بضعة أمور يجب معرفتها:

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

---

## أدوات البوت المدمجة

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

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

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

| مستوى جودة الذكاء الاصطناعي | الرصيد لكل استدعاء أداة | مع ربط مفتاح Anthropic الخاص بك (BYOK) |
|---|---|---|
| Pro | 1 رصيد | 0 رصيد — يعمل باستخدام مفتاحك |
| Economy (مهمل) | 0.5 رصيد | 0 رصيد — يعمل باستخدام مفتاحك |
| Max | 0.25 رصيد | لا يزال 0.25 رصيد، تُحتسب حتى مع ربط مفتاحك الخاص، لأن Max يعمل على نموذجنا الخاص |
| Mini | 0.15 رصيد | لا يزال 0.15 رصيد، تُحتسب حتى مع ربط مفتاحك الخاص، لأن Mini يعمل على نموذجنا الخاص |

### أدوات الفريق والمهام

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

### أدوات جهات الاتصال

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

### أدوات المواعيد والحجز

هذه الأدوات متاحة فقط عند تمكين الحجوزات في الحملة المرتبطة بوكيلك، وعند تكوين نوع حدث تقويم.

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

### أدوات المعرفة والويب

| الأداة | ما الذي تقوم به | متى يستخدمها البوت |
|------|--------------|----------------------|
| **البحث في موقعك الإلكتروني** | يقوم بمسح عناوين URL التي أضفتها إلى قائمة عناوين URL الديناميكية الخاصة بالحملة للعثور على صفحات المنتجات أو المقالات أو أي محتوى آخر يجيب على سؤال العميل. متاحة فقط عند تفعيل **البحث الذكي في الويب (AI Web Search)** وإضافة عنوان URL ديناميكي واحد على الأقل. إذا كان البحث الذكي في الويب معطلاً، فلا يمكن للبوت قراءة الصفحات أو الروابط — حتى تلك التي يلصقها العميل في الدردشة. | عندما يسأل العميل عن شيء من المحتمل وجوده على موقعك الإلكتروني — مثل المنتجات، الأسعار، المواقع، أو السياسات. |
| **التحقق من رابط** | يقرأ محتويات عنوان URL محدد حتى يتمكن البوت من الإجابة على الأسئلة المتعلقة بتلك الصفحة. متاحة فقط عند تفعيل **البحث الذكي في الويب (AI Web Search)** وإضافة عنوان URL ديناميكي واحد على الأقل. إذا كان البحث الذكي في الويب معطلاً، فلا يمكن للبوت قراءة الصفحات أو الروابط — حتى تلك التي يلصقها العميل في الدردشة. | عندما يشارك العميل رابطاً أو يسأل عن صفحة محددة على موقعك. |
| **البحث في الويب** | يجري بحثاً عاماً على Google ويعيد أفضل النتائج، مما يسمح للبوت بالإجابة على أسئلة خارج نطاق محتواك الخاص. | عندما يسأل العميل عن شيء عام (مثل الاتجاهات، معلومات عامة) غير موجود في قاعدة معرفتك. تُستخدم فقط إذا تم تمكين البحث في الويب. |

### أدوات المتابعة

تتطلب هذه الأدوات تفعيل المتابعات (follow-ups) في الحملة المرتبطة بالوكيل (Agent) الخاص بك.

| الأداة | ما الذي تقوم به | متى يستخدمها البوت |
|------|--------------|----------------------|
| **جدولة متابعة ذكية** | يجدول رسالة متابعة ذكية باستخدام تسلسل المتابعة الخاص بك — حيث يختار القالب والتوقيت المناسبين بناءً على المحادثة. | عندما يصمت العميل أو يطلب من البوت "المراجعة لاحقاً". |
| **جدولة متابعة** | يجدول متابعة أساسية في وقت محدد. | عندما يحتاج البوت إلى دفع المحادثة للأمام في لحظة محددة. |

### مشغل الوظائف المخصصة

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

### أدوات حجز المطاعم (Zenchef و Formitable)

تتوفر هذه الأدوات فقط عند ربط تكامل Zenchef أو Formitable. وهي تسمح للبوت بإدارة حجوزات المطاعم من البداية إلى النهاية.

| الأداة | ماذا تفعل | متى يستخدمها البوت |
|------|--------------|----------------------|
| **التحقق من توفر المطعم** | تبحث عن فترات الحجز المتاحة لتاريخ معين، وعدد الأشخاص، و(اختيارياً) منطقة الجلوس. | عندما يطلب الضيف حجز طاولة. |
| **إنشاء حجز مطعم** | تنشئ حجزاً جديداً. | بعد أن يؤكد الضيف فترة زمنية محددة. |
| **تحديث حجز مطعم** | تغير التاريخ، أو الوقت، أو عدد الأشخاص، أو الملاحظات على حجز موجود. | عندما يطلب الضيف تعديل حجزه. |
| **إلغاء أو تغيير حالة الحجز** | تلغي حجزاً أو تحديث حالته (مثلاً: مؤكد، لم يحضر). | عندما يلغي الضيف الحجز، أو عندما يحتاج البوت إلى تسجيل تغيير في الحالة. |
| **البحث عن الحجوزات** | تعثر على الحجوزات الموجودة التي تطابق معايير مثل الاسم، أو البريد الإلكتروني، أو التاريخ. | عندما يسأل ضيف عائد عن حجز موجود. |
| **تحديث ملف تعريف الضيف** | تحدث ملف تعريف الضيف في نظام المطعم (التفضيلات، الملاحظات، معلومات الاتصال). | عندما يشارك الضيف تفضيلات غذائية، أو رقم هاتف جديد، أو معلومات أخرى على مستوى الملف الشخصي. |
| **سرد منتجات المطعم** | تسترجع قائمة القوائم، أو القوائم المحددة، أو الإضافات المتاحة للحجز. | عندما يسأل الضيف "ما هي القوائم المحددة لديكم؟" أو عندما يحتاج البوت إلى إرفاق قائمة بحجز. |

### تشغيل وإيقاف الأدوات

يتم التحكم في معظم الأدوات من علامة تبويب **قدرات الذكاء الاصطناعي (AI Abilities)** الخاصة بالوكيل (أو خطوة **قدرات الذكاء الاصطناعي** في الحملة، إذا كنت تعمل من حملة كلاسيكية):

- **أدوات الحجز** تعمل عند تفعيل الحجوزات وربط التقويم — يظل هذا إعداداً لكل حملة في الوقت الحالي، مع رابط مباشر لخطوة تلك الحملة من علامة تبويب قدرات الذكاء الاصطناعي الخاصة بالوكيل
- **أدوات المتابعة** تعمل عند تفعيل المتابعات
- **أدوات المطاعم** تعمل عند ربط حساب Zenchef أو Formitable
- **البحث في الويب** له مفتاح تبديل خاص به في علامة تبويب **الأسئلة الشائعة والمعرفة (FAQs & Knowledge)**
- **أدوات المهام** يمكن إيقاف تشغيلها لكل وكيل باستخدام مفتاح تبديل **السماح للذكاء الاصطناعي بإنشاء المهام (Allow AI to create tasks)** (تكون مفعلة افتراضياً؛ مفتاح تبديل المهام على مستوى الحساب في **الإعدادات ← الملف الشخصي ← الميزات** يعطل نظام المهام بالكامل في كل مكان)
- **أدوات تحديث جهات الاتصال** يتم التحكم فيها من نفس علامة تبويب **قدرات الذكاء الاصطناعي** — سواء كان يُسمح للذكاء الاصطناعي بإعادة تسمية جهات الاتصال أو حفظ معلومات إضافية تم جمعها عنها
- **أدوات التنبيه** متاحة دائماً؛ **الوسم (tagging)** يعمل تلقائياً بعد كل رد من البوت (ليست أداة يختار البوت استدعاءها)

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

---

## الوظائف التي تتم إدارتها بواسطة أتمتة

قد تحمل بعض الإدخالات في صفحة الوظائف المخصصة (Custom Functions) شارة **تتم إدارتها بواسطة أتمتة** (Managed by automation). لم يتم إنشاء هذه الإدخالات هنا، بل تأتي من أتمتة تحتوي على مشغل **وظيفة وكيل الذكاء الاصطناعي** (AI Agent Function)، والذي يمنح وكيلك قدرة يمكنك بناء خطواتها بصرياً على لوحة الأتمتة بدلاً من توجيهها إلى عنوان ويب خارجي.

تتم إدارة الدالة المُدارة نيابةً عنك: حيث يتبع اسمها ووصفها وحقولها دائمًا ما تم تعيينه في مشغل الأتمتة، لذا لا يمكن تحريرها أو حذفها من هذه الصفحة — استخدم رابط **فتح الأتمتة** (Open automation) وقم بتغيير الأتمتة نفسها. ومع ذلك، لا يزال بإمكانك اختيار الوكلاء الذين يمتلكونها بالطريقة المعتادة: ففي علامة تبويب **قدرات الذكاء الاصطناعي** (AI Abilities) الخاصة بالوكيل، تظهر الدالة بجانب قدرات الوكيل الأخرى مع مفتاح تبديل تشغيل/إيقاف عادي (إذا كانت الأتمتة الخاصة بها متوقفة مؤقتًا، فسيظهر ذلك في الصف — وتصبح القدرة نشطة عند تشغيل الأتمتة). كل شيء آخر يتعلق بها يعمل مثل أي دالة مخصصة أخرى: يقرر الذكاء الاصطناعي متى يستدعيها، ويجمع التفاصيل التي حددتها، ويمكنه استخدام رد الأتمتة في نفس المحادثة.

إذا كنت تفاضل بين الخيارين: وجّه دالة مخصصة عادية إلى نظام لديه بالفعل عنوان للاستدعاء؛ أو ابنِ أتمتة باستخدام مشغل دالة وكيل الذكاء الاصطناعي (AI Agent Function) عندما يكون العمل شيئاً تفضل تجميعه من خطوات — مثل البحث عن شيء في جدول بيانات أو قاعدة بيانات، أو التفرع بناءً على شرط، أو إنشاء سجلات — دون تشغيل خادم خاص بك. راجع [الأتمتة](../automations/automations.md#letting-your-ai-agent-call-an-automation).

---

## متطلبات الخطة

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

---

## الخطوات التالية

- [ربط خوادم MCP بالبوت الخاص بك](mcp-servers.md) — حزمة أدوات جاهزة بدلاً من دالة واحدة في كل مرة.
- [وكلاء الذكاء الاصطناعي](../ai-agents/ai-agents.md) — الصفحة الرئيسية لمجموعة AI Studio التي تندرج تحتها الدوال المخصصة، وحيث يتم تعيين الدوال المخصصة للبوت.