# واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي (AI Agents API)

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

- **عنوان URL الأساسي** — `https://api.youraiconnector.com/v1`
- **المصادقة** — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع [المصادقة](authentication.md))
- **الأخطاء والترقيم** — راجع [الأخطاء والترقيم](errors-and-pagination.md)

توضح جميع الأمثلة أدناه نموذج الاستعلام `?apiKey=` في cURL ورأس `X-API-Key` في JavaScript وPython — كلاهما يعمل على كل نقطة نهاية.

إذا كنت جديداً على مفهوم الوكلاء، فاقرأ [وكلاء الذكاء الاصطناعي](../ai-agents/ai-agents.md) أولاً.


---

## كيف يتكامل الوكيل

تتم إدارة أربعة عناصر بشكل منفصل، ومن المفيد معرفة ماهية كل منها قبل البدء:

| العنصر | ماهيته | أين يتم إعداده |
|---|---|---|
| **التكوين** | التعليمات، والقواعد، والهدف، والشخصية، واللغة، ومستوى الذكاء الاصطناعي، وسلوك الحجز والمتابعة | `PUT /agents/{agentId}` أو `PUT /agents/{agentId}/bot-config` الأكثر تحديداً |
| **المعرفة** | الأسئلة الشائعة ومصادر المعرفة (الصفحات والمستندات التي قرأتها المنصة نيابة عنك) | [واجهة برمجة تطبيقات الأسئلة الشائعة](faqs.md) و `POST /agents/{agentId}/kb-sources` |
| **الأدوات** | الوظائف المخصصة وخوادم MCP التي قد يستدعيها الوكيل أثناء المحادثة | `POST /agents/{agentId}/custom-functions` و `POST /agents/{agentId}/mcp-servers` |
| **التوجيه** | القنوات والمحادثات التي تصل فعلياً إلى هذا الوكيل | نقاط الدخول — `PUT /entry-points/channel-defaults` و `POST /agents/{agentId}/entry-points` |

> **الوكيل الجديد لا يجيب على أحد حتى تقوم بتوجيه المحادثات إليه.** إن إنشاء وكيل لا يضعه على أي قناة. هذه هي الخطوة التي تفوت معظم عمليات التكامل — راجع [توجيه المحادثات إلى وكيل](#routing-conversations-to-an-agent) في نهاية هذه الصفحة.

---

## كائن الوكيل (Agent object)

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

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| الحقل | النوع | الوصف |
|---|---|---|
| `id` | string | المعرف الفريد للوكيل. |
| `name` | string \| null | اسم الوكيل، كما يظهر في لوحة التحكم. |
| `active` | boolean \| null | ما إذا كان مسموحاً للوكيل بالرد حالياً. |
| `language` | string \| null | اللغة التي يرد بها الوكيل. |
| `goal` | string \| null | ما يعمل الوكيل على تحقيقه، مختصر إلى أول 200 حرف (تشير علامة الحذف في النهاية إلى أنه تم اختصاره). |
| `tags` | array \| null | قواعد تصنيف الوكيل. |
| `anthropic_model` | string \| null | مستوى جودة الذكاء الاصطناعي: `standard`، أو `economy`، أو `max`، أو `mini`. |
| `ai_speed` | string \| null | مقدار التفكير الذي يطبقه الوكيل قبل الرد: `fast`، أو `fast_thinker`، أو `balanced`، أو `thorough`. |
| `enable_bookings` | boolean \| null | ما إذا كان بإمكان الوكيل حجز المواعيد. |
| `enable_follow_ups` | boolean \| null | ما إذا كان الوكيل يرسل رسائل متابعة. |
| `faq_refs_count` | integer | عدد الأسئلة الشائعة في قاعدة معرفة هذا الوكيل. |
| `kb_source_refs_count` | integer | عدد مصادر المعرفة المرتبطة به. |
| `created_at` | integer \| null | وقت الإنشاء، بالمللي ثانية منذ بداية العصر (epoch). |
| `last_modified_at` | integer \| null | آخر تغيير، بالمللي ثانية منذ بداية العصر (epoch). |

يضيف المستند الكامل كل شيء آخر: `instructions`، و`rules`، و`personality`، و`availability`، و`follow_up_config`، وقوائم الأسئلة الشائعة ومصادر المعرفة المرتبطة، وكتل النصوص التي تم إنشاؤها، وأي حالة تشغيل (`tag_generation`، `optimize_run`).

> تحمل بعض الردود أيضاً `substrate_campaign_id`. إنه سجل داخلي يتم الاحتفاظ به في الحسابات القديمة؛ لا تحتاج أبداً إلى اتخاذ إجراء بشأنه، وفي الحسابات الأحدث يكون `null` أو غير موجود.

---

## إدراج الوكلاء

`GET /agents` — كل وكيل في الحساب، الأحدث أولاً.

هذه نقطة النهاية **غير مقسمة إلى صفحات**. افتراضياً، يتم إرجاع كل وكيل (Agent) مع تكوينه الكامل، وهو حجم كبير: يمكن أن يصل حجم الوكيل الواحد إلى 580 كيلوبايت، وحساب يحتوي على 64 وكيلاً قد يتجاوز 3 ميجابايت. مرر `view=summary` للحصول على صف قصير لكل وكيل بدلاً من ذلك، ثم اقرأ الوكيل الذي تريده باستخدام [الحصول على وكيل](#get-an-agent).

**معلمات الاستعلام**

| المعلمة | الوصف |
|---|---|
| `view` | اضبطها على `summary` للحصول على صفوف قصيرة. أي قيمة أخرى تُرجع `400`. احذفها للحصول على المستندات الكاملة. |
| `fields` | تنطبق فقط مع `view=summary`. مفاتيح ملخصة مفصولة بفواصل للاحتفاظ بها، على سبيل المثال `id,name,active`. يتم تضمين `id` دائماً؛ ويتم تجاهل الأسماء غير المعروفة. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**الاستجابة** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## إنشاء وكيل

`POST /agents` — فقط `name` مطلوب فعلياً؛ أرسل أي تكوين تعرفه بالفعل بجانبه. يكون الوكيل الجديد نشطاً افتراضياً.

**حقول الطلب** (جميعها اختيارية باستثناء `name`)

| الحقل | النوع | الوصف |
|---|---|---|
| `name` | string | اسم الوكيل. |
| `active` | boolean | ما إذا كان بإمكانه الرد فوراً. القيمة الافتراضية هي `true`. |
| `language` | string | اللغة التي يرد بها الوكيل. |
| `instructions` | string | التعليمات الأساسية التي توجه كيفية تحدثه مع جهات الاتصال. |
| `rules` | string | القواعد الصارمة التي يجب عليه اتباعها دائماً. |
| `goal` | string | النتيجة التي يجب أن يعمل من أجل تحقيقها. |
| `personality` | string | نبرة الصوت والشخصية. |
| `availability` | object | ساعات العمل النشطة لكل يوم من أيام الأسبوع — راجع [تعيين ساعات العمل النشطة](#set-active-hours). |
| `ai_speed` | string | `fast` أو `fast_thinker` أو `balanced` أو `thorough`. |
| `anthropic_model` | string | `standard` أو `economy` أو `max` أو `mini`. |
| `scrape_urls` | string[] | الصفحات التي يجب قراءتها وبناء تعليمات الوكيل منها. |

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

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**الاستجابة** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` تكون `true` عندما تبدأ المنصة في كتابة التعليمات من الصفحات التي قدمتها.

يعني `400` أن النص الأساسي لم يكن كائن JSON، أو تم رفض حقل ما، أو أن الوكيل يتجاوز حجم التكوين الذي تسمح به خطتك. يعني `403` أن الحساب غير مسموح له باستخدام أحد الإعدادات التي أرسلتها — على سبيل المثال، مستوى ذكاء اصطناعي (AI tier) لم يمنحه مزود الحساب الخاص به.

---

## الحصول على وكيل

`GET /agents/{agentId}`

مرر `fields` مع قائمة مفصولة بفواصل للحصول فقط على ما تحتاجه، على سبيل المثال `fields=name,active,goal`. يتم تضمين `id` دائماً، ويتم تجاهل الأسماء غير الموجودة في الوكيل بدلاً من رفضها. احذفها للحصول على المستند بالكامل.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

الوكيل غير الموجود في حسابك يُرجع `404`.

---

## تحديث وكيل

`PUT /agents/{agentId}` — أرسل فقط الحقول التي تريد تغييرها؛ أما كل شيء آخر فيبقى كما هو دون تغيير.

يمكن التعامل مع الإعدادات المتداخلة كل على حدة باستخدام مفتاح منقط، لذا فإن `"availability.monday"` يغير يوم الاثنين فقط ويترك بقية أيام الأسبوع كما هي.

**ملاحظات**

- لتغيير نوع الحدث القابل للحجز الذي يقوم الوكيل (Agent) بالحجز فيه، أرسل `event_id` (معرف الحدث، أو `null` لمسحه). أرسل `event_ids` مع مصفوفة لربط عدة أحداث في وقت واحد — يصبح الأول هو الأساسي، و`[]` يقوم بإلغاء ربط كل شيء. `event_id` و`event_ids` متنافيان، ولا يمكن كتابة الحقل `event` مباشرة.
- يجب أن يكون `enable_bookings` قيمة منطقية (boolean) حقيقية، ويجب أن يكون `booking_provider` واحداً من `default`، أو `zenchef`، أو `formitable`.
- يتم تجاهل حقول الملكية والهوية، وكذلك حالة التشغيل الداخلية (تقدم التوليد والتحسين).
- **التوجيه لا يتم ضبطه هنا.** استخدم `PUT /entry-points/channel-defaults` لجعل الوكيل هو المسؤول عن الرد على قناة ما، و`POST /agents/{agentId}/entry-points` لقواعد الكلمات المفتاحية والتعليقات، و`PATCH /agents/{agentId}/active` لإيقافه مؤقتاً أو استئنافه.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

جسم الطلب الفارغ يعيد `400` مع `"No fields to update"`.

---

## تحديث إعدادات البوت

`PUT /agents/{agentId}/bot-config` — الطريقة المحددة لتغيير إعدادات المحادثة فقط.

لا يمتلك الوكيل قسماً منفصلاً للبوت: فإعداداته موجودة مباشرة على الوكيل، لذا فإن أسماء الحقول هنا هي نفس الأسماء التي ترسلها إلى `PUT /agents/{agentId}`. توجد نقطة النهاية هذه كطريقة آمنة ومركزة لتغيير عدد قليل منها. مطلوب حقل واحد على الأقل.

| الحقل | الوصف |
|---|---|
| `instructions` | التعليمات الأساسية التي توجه كيفية تحدث الوكيل مع جهات الاتصال. |
| `rules` | القواعد الصارمة التي يجب عليه اتباعها دائماً. |
| `goal` | النتيجة التي يجب أن يعمل من أجلها في كل محادثة. |
| `personality` | وصف نبرة الصوت والشخصية. |
| `language` | اللغة التي يرد بها الوكيل. |
| `ai_speed` | `fast`، أو `fast_thinker`، أو `balanced`، أو `thorough`. |
| `anthropic_model` | `standard`، أو `economy`، أو `max`، أو `mini`. |
| `max_messages` | الحد الأقصى لعدد رسائل الوكيل في كل محادثة. |
| `alert_human_when` | متى يجب على الوكيل تنبيه زميل بشري. |
| `ai_transparency` | ما إذا كان الوكيل يفصح عن كونه ذكاءً اصطناعياً. |

> **يجب أن تكون أسماء الحقول هنا أسماء بسيطة** — أحرف، أرقام، شرطات سفلية، وشرطات. المسارات المنقطة غير مقبولة في نقطة النهاية هذه (على عكس `PUT /agents/{agentId}`)، لذا يتم رفض `bot.goal` مع `400`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

يتم احتساب النصوص الطويلة ضمن حجم التكوين الذي تسمح به خطتك، لذا قد يتم رفض مجموعة تعليمات كبيرة جداً مع `400`.

---

## ضبط ساعات العمل

`PUT /agents/{agentId}/active-hours` — الساعات التي يرد خلالها الوكيل تلقائياً. خارج هذه النوافذ يظل صامتاً.

أرسل كائن `availability` مفهرساً حسب يوم الأسبوع (`monday` إلى `sunday`). يأخذ كل يوم نافذة زمنية واحدة أو قائمة من النوافذ، بتنسيق `HH:MM` لمدة 24 ساعة. الأيام التي تتركها ستحتفظ بما كانت عليه، وأي مفتاح ليس يوم عمل سيتم رفضه — لذا فإن الخطأ المطبعي لا يمكن أن يمر دون تأثير.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

مفتاح يوم أسبوع خاطئ يعيد `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## إيقاف وكيل مؤقتاً أو استئنافه

`PATCH /agents/{agentId}/active` — لتشغيل الوكيل (Agent) أو إيقافه. يحتفظ الوكيل المتوقف مؤقتاً بجميع إعداداته ولكنه يتوقف عن الرد فوراً؛ ويسري استئناف العمل على الفور.

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

يجب أن تكون قيمة `active` قيمة منطقية (boolean) حقيقية — أي قيمة أخرى ستؤدي إلى إرجاع `400` مع `"active (boolean) is required"`.

---

## تكرار وكيل

`POST /agents/{agentId}/duplicate` — ينشئ نسخة مع الاحتفاظ بإعداداتها. لا ترسل النسخة أي شيء حتى تقوم بتوجيه قناة أو نقطة دخول (Entry Point) إليها.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**الاستجابة** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

يُحتسب تكرار الوكيل ضمن حصة الوكلاء المسموح بها في خطتك تماماً مثل إنشائه من الصفر، لذا سيتم رفض الطلب بـ `403` عندما يصل الحساب إلى حده الأقصى.

---

## حذف وكيل

`DELETE /agents/{agentId}`

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

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**محظور** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## المسودات: مراجعة التغييرات قبل نشرها

يتم الاحتفاظ بالتعديلات التي يتم إجراؤها في المحرر، وأي إعادة صياغة يتم إنتاجها بواسطة [التحسين باستخدام الذكاء الاصطناعي](#optimize-an-agent-with-ai)، كـ **مسودة غير منشورة** حتى تقوم بنشرها. يستمر الوكيل المباشر (Live Agent) في الرد بإعداداته الحالية حتى ذلك الحين.

### نشر المسودة

`POST /agents/{agentId}/publish-draft` — ينقل المسودة إلى الإعدادات المباشرة ويمسح المسودة في نفس الخطوة.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` تسرد الإعدادات التي تم نقلها من المسودة إلى الوكيل المباشر، حتى تتمكن من عرض ما تم تغييره.

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

### تجاهل المسودة

`POST /agents/{agentId}/discard-draft` — يتجاهل المسودة ويترك التكوين المباشر كما هو تماماً. من الآمن استدعاؤه عندما لا توجد مسودة؛ لن يحدث شيء.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## تحسين الوكيل باستخدام الذكاء الاصطناعي

`POST /agents/{agentId}/optimize` — يعيد كتابة تكوين الوكيل بناءً على ملاحظاتك ("يستمر في تقديم خصومات"، "الإجابات طويلة جداً") ويحفظ إعادة الكتابة **كمسودة** بدلاً من جعلها مباشرة.

أرسل إما `user_feedback` (تعليمات بسيطة) أو، عند الرد على رد سيء محدد، `thumbs_down_feedback` مع `thumbs_down_message` المسيء. يجب أن يحتوي واحد منهما على الأقل على نص.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**الاستجابة** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

يتم العمل في الخلفية ويعود الاستدعاء على الفور. اقرأ الوكيل باستخدام `GET /agents/{agentId}` وراقب `optimize_run.status`؛ بمجرد عودته إلى `Draft`، تكون إعادة الكتابة في انتظارك كمسودة للوكيل. راجعها، ثم انشرها أو تجاهلها.

يُسمح بتشغيل واحد فقط في كل مرة لكل وكيل — سيؤدي استدعاء ثانٍ أثناء تشغيل الأول إلى إرجاع `409`. هذا يستخدم أرصدة الذكاء الاصطناعي.

---

## قواعد الوسم

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

**كائن القاعدة**

| الحقل | مطلوب | الوصف |
|---|---|---|
| `name` | نعم | الوسم المراد تطبيقه، على سبيل المثال `hot-lead`. |
| `description` | لا | متى يجب على الوكيل تطبيقه، مكتوب كتعليمات يتبعها. |
| `webhook` | لا | عنوان URL الذي يتم استدعاؤه عندما يطبق الوكيل هذا الوسم. |
| `ai_can_remove` | لا | ما إذا كان بإمكان الوكيل إزالة الوسم أيضاً. القيمة الافتراضية هي `false`. |
| `tag_id` | لا | معرف وسم موجود في حسابك لربط القاعدة به. بدونه، ترتبط القاعدة بالوسم الذي يحمل نفس الاسم، ويتم إنشاؤه إذا لم يكن موجوداً — بحيث يمكن معالجة كل قاعدة بواسطة معرف الوسم لاحقاً. |

### إضافة قاعدة وسم

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### استبدال قاعدة وسم

`PUT /agents/{agentId}/tags/{tagId}` — يتم العثور على القاعدة بواسطة معرف الوسم (tag id) في المسار و**يتم استبدالها بالكامل**، لا دمجها، لذا أرسل القاعدة كاملة بدلاً من الجزء الذي تقوم بتغييره فقط. يتم الاحتفاظ بالوسم الذي تشير إليه حتى إذا تركت `tag_id` فارغاً، لذا لا يمكن لأي تعديل فصل القاعدة عن وسمها.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### إزالة قاعدة وسم

`DELETE /agents/{agentId}/tags/{tagId}` — يتوقف الوكيل (Agent) عن تطبيق ذلك الوسم. يظل الوسم نفسه، وأي جهات اتصال تحمل هذا الوسم بالفعل، دون تغيير.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

كلا نقطتي النهاية تُرجعان `404` عندما لا يكون الوكيل موجوداً **أو** عندما لا تكون لديه قاعدة لهذا الوسم.

### إنشاء مجموعة وسوم باستخدام الذكاء الاصطناعي

`POST /agents/{agentId}/tags/generate` — يصمم مجموعة كاملة من القواعد (أسماء الوسوم وصياغة "التطبيق عند..." خلف كل منها) من خلال قراءة تعليمات الوكيل وهدفه.

| الحقل | الوصف |
|---|---|
| `mode` | `merge` (الخيار الافتراضي) يحتفظ بالقواعد الموجودة بالفعل على الوكيل ويضيف إليها. `replace` يصمم المجموعة من الصفر. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**الاستجابة** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

يتم العمل في الخلفية. اقرأ الوكيل وراقب `tag_generation.status`؛ حيث تظهر القواعد نفسها في `tags` الخاص بالوكيل. يُسمح بتشغيل واحد فقط في كل مرة لكل وكيل (`409` بخلاف ذلك)، ويستخدم هذا رصيد الذكاء الاصطناعي.

---

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

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

**من أين تأتي معرفات المصدر.** أضف محتوى باستخدام نقاط نهاية قاعدة المعرفة — `POST /kb-sources/url` لصفحة، `POST /kb-sources/file` لمستند، `POST /kb-sources/bulk-import` لموقع كامل. تُرجع هذه المعرفات `source_id` الذي تقوم باستطلاع حالته باستخدام `GET /kb-sources/{sourceId}` حتى يصبح جاهزاً. يقبل `POST /kb-sources/url` أيضاً `autoLinkToAgentId`، الذي يرفق المصدر بوكيل بمجرد انتهاء الاستيراد، لذا يمكنك تخطي استدعاء الإرفاق أدناه.

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

`POST /agents/{agentId}/kb-sources` — أرسل `kb_source_ids` مع قائمة لإرفاق مجموعة كاملة في استدعاء واحد (ما تريده بعد زحف موقع ما)، أو `kb_source_id` لمصدر واحد. أرسل أياً منهما. إرفاق شيء مرفق بالفعل لا يغير شيئاً.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**الاستجابة** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

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

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` لواحد، أو `POST /agents/{agentId}/kb-sources/bulk-remove` مع `kb_source_ids` للعديد. الإزالة الجماعية هي `POST` لأن قائمة المعرفات تنتقل في المتن (body).

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

لا يتم حذف المصادر نفسها وتظل متاحة لوكلائك الآخرين. فصل شيء غير متصل لا يغير شيئاً.

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

تتم إدارة الأسئلة الشائعة (FAQs) عبر نقاط النهاية الخاصة بها ويتم ربطها بوكيل من هناك: `POST /faqs/{faqId}/link` مع `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`، و `POST /faqs/{faqId}/unlink` لإزالتها مرة أخرى. يمكن مشاركة الأسئلة الشائعة بواسطة أي عدد من الوكلاء. راجع [واجهة برمجة تطبيقات الأسئلة الشائعة](faqs.md).

> لا يتم استخدام الأسئلة الشائعة إلا من قبل الوكلاء المرتبطين بها — إنشاؤها وحدها لا يكفي.

---

## الأدوات

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

تسمح `POST /agents/{agentId}/custom-functions` للوكيل باستدعاء إحدى وظائفك المخصصة أثناء المحادثات. لا يمكن إرفاق سوى الوظائف التي تنتمي إلى نفس الحساب، وإرفاق وظيفة مرفقة بالفعل لا يغير شيئاً.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` تقوم بفصلها. لا يتم حذف الوظيفة نفسها وتظل متاحة لوكلائك الآخرين.

قم بإدارة الوظائف نفسها على `/custom-functions` — راجع [الوظائف المخصصة](../ai-automation/custom-functions.md) لمعرفة ماهيتها.

### خوادم MCP

خادم MCP هو حزمة جاهزة من الأدوات التي يمكن لوكيلك اكتشافها واستدعاؤها بنفسه — راجع [ربط خوادم MCP بالبوت الخاص بك](../ai-automation/mcp-servers.md). يتم تسجيل الخوادم مرة واحدة في الحساب، ثم يتم إرفاقها بأي وكلاء يجب أن يستخدموها.

> تتطلب خوادم MCP ميزة **الوظائف المخصصة** في خطتك. بدونها، ستعيد نقاط نهاية `/mcp-servers` على مستوى الحساب `403`. إرفاق خادم مسجل بالفعل بوكيل غير مقيد.

#### تسجيل خادم

`POST /mcp-servers`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `name` | نعم | تسمية للخادم. |
| `url` | نعم | عنوان الخادم. يجب أن يكون قابلاً للوصول عبر الإنترنت العام. |
| `auth_type` | لا | `header` (الافتراضي) لرأس مصادقة ثابت، أو `oauth2`. |
| `auth_header_name` | لا | الرأس الذي يتم إرسال بيانات الاعتماد فيه. الافتراضي هو `Authorization`. |
| `auth_header_value` | لا | بيانات الاعتماد نفسها. لا يتم إرجاعها أبداً في أي استجابة. |
| `enabled` | لا | ما إذا كان الخادم متاحاً للوكلاء (Agents). الافتراضي هو `true`. |
| `enabled_tools` | لا | قائمة السماح بأسماء الأدوات. `null` تعني أن كل أداة يقدمها الخادم مفعلة. |
| `tool_policies` | لا | حدود لكل أداة، مفهرسة باسم الأداة — عدد مرات تشغيل الأداة، التخزين المؤقت للنتائج، وتجاوز للقراءة فقط. مرر `null` لمسحها جميعاً. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**الاستجابة** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

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

يؤدي `auth_type` من نوع `oauth2` إلى حفظ التسجيل مع `oauth_connected: false` وبدون أدوات: لا يوجد رمز مميز (token) بعد. تتطلب مصادقة خادم OAuth تسجيل دخول عبر المتصفح ويتم ذلك من لوحة التحكم، وليس عبر واجهة برمجة التطبيقات (API).

#### سرد الخوادم وتحديثها وحذفها

- `GET /mcp-servers` — كل خادم مسجل، الأحدث أولاً، تحت `servers`.
- `PUT /mcp-servers/{serverId}` — أرسل فقط ما تريد تغييره. تغيير عنوان URL أو حقول المصادقة يعيد اختبار الاتصال ويحدث قائمة الأدوات المخزنة مؤقتاً.
- `DELETE /mcp-servers/{serverId}` — يزيل التسجيل ويفك ارتباطه بكل وكيل (Agent) وحملة كانت تستخدمه.

```bash
curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**الأسرار لا تظهر أبداً.** تحمل الاستجابات `auth_header_value_set` (علامة `true`/`false` تشير إلى أن القيمة مخزنة) بدلاً من بيانات الاعتماد، وتبقى رموز OAuth وأسرار العميل على جانب الخادم. يتم إرجاع كل شيء آخر: `name`، `url`، `enabled`، `auth_type`، `auth_header_name`، `tools`، `enabled_tools`، `tool_policies`، `oauth_connected`، `tools_cached_at`، `last_connected_at`، `last_error`، `created_at`، `updated_at`.

#### اختبار الاتصال

`POST /mcp-servers/test-connection` — يتصل بخادم ويسرد أدواته. هناك طريقتان لاستدعائه:

- مع `server_id` — يختبر التكوين **المحفوظ** ويحدث قائمة الأدوات المخزنة مؤقتاً الخاصة به؛
- مع `url` مضمن (بالإضافة إلى `auth_header_name` / `auth_header_value`) — اختبار قبل الحفظ لا يخزن أي شيء.

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**الاستجابة** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

فشل الاتصال **ليس** خطأ HTTP — ستحصل على `200` مع `success: false` و `error` يصف ما حدث من خطأ، حتى تتمكن من عرضه بجوار الحقل الذي يقوم المشغل بتحريره.

#### إرفاق خادم بوكيل (Agent)

تسجيل خادم لا يمنح أي وكيل (Agent) حق الوصول إليه. قم بإرفاقه:

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**الاستجابة** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` يقوم بفصله مرة أخرى. لا يتم حذف الخادم نفسه ويبقى متاحاً لوكلائك الآخرين. إرفاق أو فصل شيء موجود بالفعل في تلك الحالة لا يغير شيئاً.

---

## مكتبة الوسائط

تحتوي مكتبة الوسائط على الملفات التي قد يرسلها الوكيل (Agent) أثناء المحادثة — قائمة طعام، قائمة أسعار، صورة منتج. يمكن للوكيل الاحتفاظ بـ **50 عنصراً** كحد أقصى.

### سرد الوسائط

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**الاستجابة** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

تظهر العناصر المخزنة على الوكيل (Agent) أولاً، تليها أي عناصر أقدم لا تزال مخزنة في الحملة التي تم إنشاء الوكيل منها؛ يوضح `media_home` (`agent` أو `campaign`) أيها يتبع لأي مجموعة. ضمن كل مجموعة، تظهر العناصر الأحدث أولاً.

> **تنتهي صلاحية `media_url` بعد 7 أيام.** إنه رابط التنزيل الذي تم إنشاؤه عند تحميل الملف — تعامل مع الرابط القديم على أنه غير صالح بدلاً من كونه معطلاً، وأعد قراءة القائمة للحصول على رابط جديد.

### تحميل الوسائط

`POST /agents/{agentId}/media-library` — يتم تحميل الملف مضمناً بتنسيق base64، بحد أقصى **10 ميجابايت**. يعود الاستدعاء بمجرد تخزين الملف، لذا اسمح بوقت أطول قليلاً من الطلب العادي. لاحظ أن نص الطلب هذا يستخدم أسماء حقول بتنسيق camelCase.

| الحقل | مطلوب | الوصف |
|---|---|---|
| `base64Data` | نعم | محتويات الملف، مشفرة بتنسيق base64، بدون بادئة data-URL. |
| `mimeType` | نعم | نوع MIME الخاص بالملف. |
| `fileName` | نعم | اسم الملف الأصلي، المستخدم لتسمية الملف المخزن. |
| `title` | لا | تسمية قصيرة تظهر في المكتبة. |
| `description` | لا | تعليمات "متى يجب على الوكيل إرسال هذا". |
| `sendMessage` | لا | الصياغة المفضلة التي يقولها الوكيل عند إرسال العنصر. يتم تقصيرها إلى 500 حرف. |
| `maxSendsPerConversation` | لا | عدد المرات التي يمكن إرسالها فيها إلى نفس جهة الاتصال في محادثة واحدة. القيمة الافتراضية هي `1`. |
| `sendAsVoiceNote` | لا | تحميلات الصوت فقط — تخزين الملف كملاحظة صوتية على واتساب. يتم تجاهله لأنواع الملفات الأخرى. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

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

يغطي `400` الحقول المفقودة، أو نوع الملف غير المدعوم، أو الملف الفارغ أو كبير الحجم، أو تجاوز حد الـ 50 عنصراً. يعني `403` أن مكتبة الوسائط معطلة للحساب.

### تحديث عنصر وسائط

`PATCH /agents/{agentId}/media-library/{itemId}` — البيانات الوصفية فقط. لا يمكن استبدال الملف نفسه؛ قم بتحميل عنصر جديد واحذف القديم. يستخدم نص الطلب هذا تنسيق snake_case: `title`، `description`، `send_message`، `max_sends_per_conversation` (رقم صحيح غير سالب، أو `null` لمسح الحد).

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**الاستجابة** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### حذف عنصر وسائط

`DELETE /agents/{agentId}/media-library/{itemId}` — يزيل العنصر وملفه المخزن. حذف عنصر تم حذفه بالفعل ينجح ويبلغ عن `deleted: false`، لذا فإن الاستدعاء آمن لإعادة المحاولة.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## إنشاء رسائل المتابعة

`POST /agents/{agentId}/template-generation` — يكتب رسائل متابعة الوكيل نيابة عنك (التنبيهات التي يرسلها عندما تصبح المحادثة هادئة)، بناءً على الغرض من الوكيل.

| الحقل | الوصف |
|---|---|
| `type` | يكتب `all` (الخيار الافتراضي) المجموعة بأكملها. بينما يكتب `cold_only` الرسائل الخاصة بجهات الاتصال التي لم ترد مطلقاً فقط. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

هناك طريقتان لعودة هذه النتيجة، ويخبرك الحقل `target` بأيهما:

- **`target: "agent"` مع `200`** — تمت كتابة الرسائل أثناء المكالمة والنتيجة موجودة في `data`. اقرأها من `follow_up_config` الخاص بالوكيل. هذه هي الحالة المعتادة.
- **`target: "campaign"` مع `202`** — تم وضع العمل في قائمة الانتظار مقابل الحملة المسماة في `campaign_id`. راقب `template_generation_status` الخاصة بتلك الحملة حتى تنتهي.

يحتاج `cold_only` إلى حملة صادرة ويتم رفضه بـ `409` (`reason: "cold_only_requires_campaign"`) على وكيل لا يملك أياً منها. يعني `403` أن المتابعات التلقائية غير مفعلة للحساب. يستخدم هذا رصيد الذكاء الاصطناعي، ويعني `400` مع `"Insufficient credits."` أن الحساب قد نفد رصيده.

---

## توجيه المحادثات إلى وكيل

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

| ما تريد القيام به | الاستدعاء |
|---|---|
| جعل الوكيل مجيباً لقناة كاملة | `PUT /entry-points/channel-defaults` مع `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| إضافة قاعدة أضيق (كلمات رئيسية، تعليقات، متابعون جدد) | `POST /agents/{agentId}/entry-points` |
| رؤية القواعد التي تشير إلى وكيل واحد | `GET /agents/{agentId}/entry-points` |
| ترك قناة بدون مجيب | `DELETE /entry-points/channel-defaults?channel=instagram` |

### سرد نقاط دخول الوكيل

`GET /agents/{agentId}/entry-points` — قواعد التوجيه التي ترسل المحادثات إلى هذا الوكيل، مرتبة من الأحدث إلى الأقدم. يتم إرجاع كل من القواعد الحالية والمتقاعدة؛ القاعدة المتقاعدة تحتوي على `enabled: false`.

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

بالنسبة للإعدادات الافتراضية لقناة الحساب بالكامل، بما في ذلك القناة التي تم تعيينها عمداً لعدم وجود مجيب، اقرأ `GET /entry-points/channel-defaults` بدلاً من ذلك.

### إنشاء نقطة دخول

`POST /agents/{agentId}/entry-points` — الوكيل الموجود في المسار هو الفائز دائماً، لذا لا يمكن أبداً إنشاء قاعدة لوكيل مختلف عن ذلك الموجود في الرابط (URL).

| `type` | ماذا يفعل |
|---|---|
| `channel_default` | يجيب الوكيل على كل جهة اتصال جديدة على القنوات المدرجة. يفضل استخدام `PUT /entry-points/channel-defaults` لهذا الغرض — فهو يقوم بإيقاف المجيب السابق نيابة عنك، وهو ما لا يفعله إنشاء قاعدة افتراضية ثانية هنا. |
| `keyword` | يتولى الوكيل المهمة عندما تحتوي الرسالة الأولى على إحدى `match_config.keywords`. مطلوب كلمة رئيسية واحدة على الأقل. |
| `instagram_comment` / `facebook_comment` | يرد الوكيل على التعليقات على منشوراتك. يجب إدراج القناة المطابقة في `channels`. |
| `instagram_follower` | يرحب الوكيل بالمتابعين الجدد. |

`channels` مطلوب ويحدد القنوات التي تغطيها القاعدة — على سبيل المثال `whatsapp`، أو `whatsapp_web`، أو `instagram`، أو `messenger`، أو `telegram`، أو `sms`، أو `email`، أو `chat_widget`، أو `custom_channel`. يتم تفعيل القواعد الجديدة ما لم تحدد خلاف ذلك.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**الاستجابة** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**أي قاعدة تفوز عندما يمكن تطبيق عدة قواعد:** المحادثة الجارية أو التعيين اليدوي يبقيان الوكيل الذي لديه بالفعل؛ بخلاف ذلك، تتفوق قواعد الكلمات الرئيسية على قواعد التعليقات، والتي تتفوق بدورها على قواعد المتابعين، وتكون القناة الافتراضية هي الملاذ الأخير. يتم الإبلاغ عما إذا كانت هذه القواعد تقرر أي شيء في الحساب بواسطة `GET /entry-points/routing-status`.

هذه نسخة مختصرة. يغطي دليل [Entry Points API](entry-points.md) القواعد الكاملة للترتيب والتعليقات والمتابعين، ووكيل واحد لكل رقم WhatsApp، وتغيير القاعدة أو حذفها. راجع [Entry Points](../ai-agents/entry-points.md) لمعرفة المفهوم، و[Channels API](channels.md) لربط القناة نفسها.

---

## أخطاء واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي

تُرجع نقاط نهاية الوكيل غلاف الخطأ القياسي:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| الحالة | متى يحدث ذلك في نقطة نهاية الوكيل |
|---|---|
| `400` | حقل مطلوب مفقود أو غير صالح — نص تحديث فارغ، قيمة خارج قائمة مسموح بها (`ai_speed`، `anthropic_model`، `booking_provider`، `mode`، `type`)، مفتاح ليس من أيام الأسبوع في `availability`، اسم حقل منقط في `bot-config`، أو معرف بتنسيق خاطئ في المسار. |
| `403` | الحساب غير مسموح له باستخدام إعداد أرسلته، أو أنك وصلت إلى حد الوكلاء في خطتك، أو أن ميزة تحتاجها نقطة النهاية هذه (مكتبة الوسائط، المتابعات، الوظائف المخصصة لخوادم MCP) معطلة. يتم رفض أي تغيير يتجاوز حجم التكوين الذي تسمح به خطتك باستخدام `400`. |
| `404` | لم يتم العثور على الوكيل، أو قاعدة العلامات، أو عنصر الوسائط، أو خادم MCP — إما أنه غير موجود أو أنه ينتمي إلى حساب آخر. |
| `409` | هناك شيء قيد التنفيذ أو يعيق العملية: عملية تحسين أو إنشاء علامات قيد التشغيل، أو لا يزال الوكيل مرتبطاً ببث أو نقطة دخول أو حملة، أو تم طلب `cold_only` دون وجود حملة صادرة. |

الرموز المشتركة التي يمكن أن تُرجعها كل نقطة نهاية — `401`، و `403` (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، و `429` (حد المعدل)، و `500` — مدرجة مع إرشادات إعادة المحاولة في [الأخطاء والترقيم](errors-and-pagination.md).

> **ملاحظة حول المستكشف.** توجد نقاط نهاية `/agents` في مواصفات OpenAPI المنشورة، لذا يمكنك تصفح حقولها الدقيقة وتشغيل طلبات مباشرة في [مرجع واجهة برمجة التطبيقات](reference.md). كما توجد نقاط نهاية `/mcp-servers` على مستوى الحساب في المواصفات أيضاً، لذا يمكنك استكشافها هناك أيضاً.


---

## ذات صلة

- [وكلاء الذكاء الاصطناعي](../ai-agents/ai-agents.md) — ما هو الوكيل، بلغة بسيطة.
- [نقاط الدخول](../ai-agents/entry-points.md) — كيفية توجيه المحادثات إلى وكيل.
- [واجهة برمجة تطبيقات الأسئلة الشائعة](faqs.md) — بناء وربط المعرفة التي يجيب منها وكيلك.
- [واجهة برمجة تطبيقات القنوات](channels.md) — ربط القنوات التي يجيب عليها الوكيل.
- [ربط خوادم MCP بالبوت الخاص بك](../ai-automation/mcp-servers.md) · [الوظائف المخصصة](../ai-automation/custom-functions.md)
- [مرجع واجهة برمجة التطبيقات](reference.md) — مستكشف نقاط النهاية التفاعلي الكامل.