# واجهة برمجة تطبيقات نقاط الدخول (Entry Points API)

تُعد **نقطة الدخول (Entry Point)** قاعدة توجيه: "عند حدوث هذا على هذه القناة، قم بتسليم المحادثة إلى هذا الوكيل (Agent)". يؤدي ربط قناة ما إلى وصول الرسائل إلى الحساب، كما يمنحك إنشاء وكيل شيئاً يمكنه الرد، ولكن لا يقرر أي منهما من يجيب على الرسالة الأولى لشخص غريب. نقاط الدخول هي التي تقرر ذلك. للمنتج نفسه، راجع [دليل نقاط الدخول](../ai-agents/entry-points.md).

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

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

> **في مستكشف واجهة برمجة التطبيقات.** كل نقطة نهاية في هذه الصفحة موجودة في مواصفات OpenAPI المنشورة، لذا يمكنك تصفح حقولها بدقة وتشغيل طلبات مباشرة في [مستكشف واجهة برمجة التطبيقات](reference.md).


---

## الاستدعاء الوحيد الذي تحتاجه معظم عمليات التكامل

قم بربط قناة، وإنشاء وكيل، ثم توجيه القناة إلى الوكيل:

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'
```

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

---

## كيف يتم اتخاذ قرار التوجيه

عند وصول رسالة، تتبع المنصة سلماً ثابتاً وتفوز الخطوة الأولى التي تتخذ القرار:

1. **تولى إنسان زمام الأمور** في المحادثة — لا يوجد ذكاء اصطناعي.
2. **تم تعيين جهة الاتصال بالفعل لوكيل**، يدوياً أو لأن محادثة مع هذا الوكيل جارية — يحتفظ نفس الوكيل بها. لا تقوم نقاط الدخول أبداً بنقل محادثة قائمة؛ لتسليم محادثة إلى وكيل مختلف، قم بتعيينها (في التطبيق، أو باستخدام إجراء [الأتمتة](../automations/automations.md#actions)).
3. **جهة الاتصال ترد على بث** — يجيب وكيل البث، أو لا أحد إذا لم يكن للبث وكيل.
4. **تطابق نقطة دخول محددة.** قواعد الكلمات الرئيسية تتفوق على قواعد التعليقات، والتي تتفوق بدورها على قواعد المتابعين. بين قاعدتين من نفس النوع، تفوز القاعدة التي تم تحديثها مؤخراً.
5. **الإعداد الافتراضي للقناة** التي وصلت عليها الرسالة. الإعداد الافتراضي المخصص لرقم معين كتب إليه جهة الاتصال يتفوق على الإعداد الافتراضي للقناة بأكملها.
6. **لم يتم العثور على تطابق** — تصل الرسالة إلى صندوق الوارد الخاص بفريقك ولا يرد أي مساعد.

هناك أمران يخففان من حدة الخطوة 6. الحساب الذي يحتوي على **وكيل نشط واحد فقط** ولا يوجد إعداد افتراضي للقناة لا يزال يحصل على هذا الوكيل كمسؤول عن الرد، لذا فإن الحساب الجديد الذي يربط واتساب ويرسل رسالة اختبار لا يواجه الصمت. لا ينطبق هذا الحد الأدنى أبداً على قناة تحتوي على قاعدة كلمات رئيسية (هناك، تُترك الرسالة التي لا تطابق أي كلمة رئيسية للإنسان عمداً) ولا يتجاوز أبداً قناة قمت بتعيينها على "لا أحد" (راجع [ترك قناة دون رد من أحد](#leave-a-channel-with-nobody-answering)).

يتم الإبلاغ عما إذا كان السلم مفعلاً لحساب ما بواسطة `GET /entry-points/routing-status`. إنه مفعل لكل حساب اليوم؛ يوجد الاستدعاء حتى يتمكن التكامل من التحقق بدلاً من الافتراض.

---

## كائن نقطة الدخول

```json
{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| الحقل | الوصف |
|---|---|
| `id` | معرف القاعدة. |
| `type` | واحد من `channel_default`، `keyword`، `instagram_comment`، `facebook_comment`، `instagram_follower`. راجع [أنواع القواعد](#rule-types). |
| `channels` | القنوات التي تغطيها القاعدة: `whatsapp`، `whatsapp_web`، `instagram`، `instagram_private`، `messenger`، `telegram`، `sms`، `email`، `chat_widget`، `custom_channel`، `line`، `viber`، `tiktok`، `imessage`، `linkedin`، `skool`. تستخدم قواعد التعليقات `instagram` أو `facebook`. |
| `agent_id` | الوكيل الذي توجه القاعدة إليه. فارغ في حالة الإعداد الافتراضي للقناة الذي تم تعيينه عمداً على "لا أحد". |
| `enabled` | `false` للقاعدة التي تم إيقافها. القواعد الموقوفة هي تاريخ، وليست إعدادات حية، وكلاهما يعود من نقاط نهاية القائمة. |
| `match_config` | إعدادات خاصة بالنوع — راجع [أنواع القواعد](#rule-types). فارغ للإعداد الافتراضي للقناة. |
| `first_response_mode` | `ai` (افتراضي) يسمح للوكيل بكتابة الرد الأول؛ `exact_text` يرسل `first_response_exact_text` حرفياً. يتم الالتزام به في قواعد التعليقات اليوم؛ مقبول ومخزن في قواعد الكلمات الرئيسية ولكنه لم يُستخدم هناك بعد. |
| `first_response_exact_text` | الرسالة المباشرة الأولى الثابتة عندما يكون `first_response_mode` هو `exact_text`. يتم استبدال `{{first_name}}` بالاسم الأول للشخص، أو "هناك" عندما يكون غير معروف. |
| `public_comment_reply_exact_text` | قواعد التعليقات فقط: الرد العام الثابت تحت التعليق. الفراغ يتخطى الرد العام؛ ولا تزال الرسالة المباشرة تُرسل. |
| `created_at`، `last_modified_at` | مللي ثانية منذ عصر يونكس. |

### أنواع القواعد

| `type` | يتم تفعيلها عند | `match_config` |
|---|---|---|
| `channel_default` | جهة اتصال جديدة وغير معروفة تكتب على إحدى `channels`. | `phone_numbers` (اختياري) — تحديد النطاق الافتراضي لرقم متصل واحد بدلاً من القناة بأكملها. راجع [وكيل واحد لكل رقم واتساب](#one-agent-per-whatsapp-number). |
| `keyword` | الرسالة الأولى لجهة اتصال جديدة هي إحدى `keywords`. يتجاهل المطابقة حالة الأحرف والمسافات، ويتم حل الخطأ البسيط ("info pls" مقابل `INFO`) بواسطة الذكاء الاصطناعي ما لم تقم بتعيين `fuzzy_match: false` — افعل ذلك لرموز العروض الترويجية ورموز SKU حيث يجب ألا يتم احتساب الخطأ البسيط. لا يتم تطبيقه على `sms` أو `imessage`. | `keywords` (واحد على الأقل، مطلوب)، `fuzzy_match` (الافتراضي `true`). |
| `instagram_comment` / `facebook_comment` | شخص ما يعلق على أحد منشوراتك. يجب أن يتضمن `channels` `instagram` أو `facebook` على التوالي. | `keywords` (فارغ يعني احتساب كل تعليق على المنشورات المراقبة)، `post_ids` (فارغ يعني كل المنشورات)، `delay_minutes` (انتظر قبل إرسال الرسالة المباشرة)، `reply_instructions` (كيف يجب على الوكيل صياغة رده). |
| `instagram_follower` | شخص جديد يتابع حسابك على إنستغرام. يحتاج إلى اتصال [إنستغرام (شخصي)](../messaging-channels/instagram-personal.md) — اتصال الرسائل المباشرة الرسمي لإنستغرام لا يمكنه رؤية المتابعين. | `reply_instructions` (اختياري). |

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

---

## توجيه قناة إلى وكيل

`PUT /entry-points/channel-defaults` — تجعل وكيلاً واحداً هو المسؤول عن الرد على جهات الاتصال الجديدة على قناة ما. يتم استبعاد أي وكيل آخر تم تعيينه حالياً كافتراضي لتلك القناة في نفس الطلب، بحيث يكون للقناة دائماً وكيل رد واحد فقط. تعيين الوكيل الذي يعد بالفعل افتراضياً لا يغير شيئاً.

| الحقل | مطلوب | الوصف |
|---|---|---|
| `channel` | نعم | القناة، على سبيل المثال `whatsapp`، `whatsapp_web`، `instagram`، `messenger`، `telegram`، `sms`، `email`، `chat_widget` أو `custom_channel`. |
| `agent_id` | نعم | الوكيل الذي يجب أن يقوم بالرد. يجب أن ينتمي إلى حسابك. |
| `phone_number` | لا | تحديد النطاق الافتراضي لأحد أرقامك المتصلة على هذه القناة (بتنسيق E.164 مع البادئة `+`، تماماً كما يظهر تحت الأرقام المتصلة). يترك الإعداد الافتراضي على مستوى القناة دون تغيير. راجع [وكيل واحد لكل رقم WhatsApp](#one-agent-per-whatsapp-number). |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}
```

`entry_point_id` هي القاعدة السارية الآن؛ تسرد `disabled_entry_point_ids` أي قواعد تم استبعادها لإفساح المجال لها (تكون فارغة عندما لا يكون هناك شيء لاستبداله). تتأثر فقط جهات الاتصال التي لم تتحدث معها من قبل — أي شخص في محادثة بالفعل مع وكيل يحتفظ بذلك الوكيل.

يعني `400` أن `channel` أو `agent_id` مفقود، أو أن الوكيل ينتمي إلى حساب آخر، أو أن `phone_number` ليس واحداً من أرقامك المتصلة.

---

## معرفة من يرد على كل قناة

`GET /entry-points/channel-defaults` — كل قناة افتراضية على الحساب، من الأحدث إلى الأقدم، بما في ذلك القنوات المتقاعدة (`enabled: false`) والقناة التي تم تعيينها عمدًا على "لا أحد" (`agent_id: ""`). قم بالتصفية باستخدام `enabled` بنفسك للحصول على الصورة الحالية.

**cURL**

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

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}
```

هذه هي القراءة على مستوى الحساب. لا يمكن لسرد قواعد وكيل واحد باستخدام `GET /agents/{agentId}/entry-points` إظهار قناة تم تعيينها على "لا أحد"، لأن تلك القاعدة لا تنتمي إلى أي وكيل.

---

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

`DELETE /entry-points/channel-defaults?channel=instagram` — يتقاعد الإعداد الافتراضي على مستوى القناة لقناة واحدة. يتم تسمية القناة كمعامل استعلام، وليس في نص الطلب. أضف `&phone_number=%2B31685101091` لمسح الإعداد الافتراضي لهذا الرقم فقط والسماح للرقم بالعودة إلى من يجيب على القناة.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }
```

من الآمن التكرار: مسح قناة ليس لها إعداد افتراضي هو `200` مع قائمة فارغة. المسح يعني **إلغاء التعيين، وليس الصمت** — في حساب به وكيل نشط واحد فقط، لا تزال القناة غير المكونة تعود إلى ذلك الوكيل. لإبقاء الذكاء الاصطناعي بعيدًا عن القناة تمامًا، اختر **لا أحد يجيب** لها في لوحة **من يجيب على المحادثات الجديدة** في التطبيق (التي تكتب إعدادًا افتراضيًا صريحًا بـ "لا أحد" لا يتجاوزه الإعداد الاحتياطي أبدًا)، أو أوقف الوكيل مؤقتًا باستخدام `PATCH /agents/{agentId}/active`.

---

## وكيل واحد لكل رقم WhatsApp

التوجيه يكون لكل قناة افتراضيًا: تشترك جميع أرقام WhatsApp الخاصة بك في مجيب واحد. مع وجود رقمين أو أكثر متصلين على WhatsApp Business أو WhatsApp Web، يمكن تحديد نطاق الإعداد الافتراضي لرقم واحد، بحيث يمكن لنشاط تجاري لديه رقم لكل فرع أو علامة تجارية منح كل منها وكيلًا خاصًا به داخل حساب واحد.

أرسل `phone_number` مع طلب التعيين:

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'
```

- يجب أن يكون الرقم أحد أرقامك المتصلة على تلك القناة، مكتوباً كما يظهر تحت الأرقام المتصلة (بتنسيق E.164 مع `+`)؛ أي شيء آخر يعتبر `400`.
- يتم تخزين القاعدة كإعداد افتراضي للقناة باستخدام `match_config.phone_numbers: ["+31685101091"]`. الرسالة التي تصل على ذلك الرقم تذهب إلى الوكيل الخاص به؛ بينما تستمر كل الأرقام الأخرى في اتباع الإعداد الافتراضي للقناة بالكامل.
- تعيين أو مسح الإعداد الافتراضي للقناة لا يؤثر على القواعد المحددة لكل رقم، والعكس صحيح. يمكنك مسح قاعدة رقم معين باستخدام `DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091`.
- تخرج الردود دائماً من الرقم الذي راسله جهة الاتصال، بحيث يستمر جهة الاتصال في التحدث إلى نفس الرقم ونفس الوكيل.

---

## إضافة قاعدة أكثر تحديداً

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

| الحقل | مطلوب | الوصف |
|---|---|---|
| `type` | نعم | `keyword` أو `instagram_comment` أو `facebook_comment` أو `instagram_follower` أو `channel_default`. |
| `channels` | نعم | قائمة غير فارغة بالقنوات التي تغطيها القاعدة. يجب أن تدرج قاعدة التعليقات قناتها الخاصة (`instagram` أو `facebook`). |
| `match_config` | يعتمد على النوع | راجع [أنواع القواعد](#rule-types). تحتاج قاعدة الكلمات المفتاحية إلى إدخال واحد على الأقل في `keywords`. |
| `enabled` | لا | القيمة الافتراضية هي `true`. |
| `first_response_mode`، `first_response_exact_text`، `public_comment_reply_exact_text` | لا | إعدادات الاستجابة الأولى الموضحة في [كائن نقطة الدخول](#the-entry-point-object). |

**cURL**

```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"] }
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()
```

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

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

قاعدة تحويل التعليقات إلى رسائل مباشرة (DM) تتفاعل فقط مع التعليقات التي تحتوي على "LINK" على منشورين محددين، وتنتظر دقيقتين، ثم ترسل رسالة أولى ثابتة:

```json
{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}
```

اترك `keywords` فارغاً لإرسال رسالة مباشرة إلى كل من يعلق على المنشورات المراقبة، واترك `post_ids` فارغاً لمراقبة كل منشور. يحدد `400` الخطأ الموجود: `type` غير معروف، أو `channels` فارغ، أو قاعدة كلمات مفتاحية بدون كلمات مفتاحية، أو قاعدة تعليقات لا تدرج قناتها الخاصة.

---

## سرد قواعد الوكيل

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

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}
```

---

## تغيير قاعدة

`PUT /entry-points/{entryPointId}` — لتغيير قاعدة واحدة. أرسل فقط الحقول التي تقوم بتغييرها؛ يمكن التعامل مع الإعدادات المتداخلة بشكل فردي باستخدام مفتاح منقط مثل `"match_config.keywords"`. كلما أثر التغيير على `type` أو `channels` أو `match_config`، يتم إعادة فحص القاعدة بالكامل، لذا لا يمكن للتعديل الجزئي أن يترك قاعدة غير قابلة للاستخدام (سيتم رفض تبديل `type` إلى `keyword` دون توفير كلمات مفتاحية). إرسال `agent_id` ينقل القاعدة إلى وكيل آخر من وكلائك؛ سيتم رفض القيمة الفارغة. يتم تجاهل حقول الملكية والهوية.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()
```

**الاستجابة**

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

تعديلات شائعة أخرى: `{ "enabled": false }` تقوم بتقاعد قاعدة دون حذفها، و `{ "agent_id": "agOtherAgent" }` تنقلها إلى وكيل مختلف. إرسال نص فارغ يعيد `400` مع `"No fields to update"`.

---

## حذف قاعدة

`DELETE /entry-points/{entryPointId}` — لإزالة القاعدة بشكل دائم. لا يوجد شيء آخر يشير إلى نقطة الدخول (Entry Point)، لذا لا يوجد شيء يحتاج إلى فصله أولاً.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

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

لإيقاف عمل قاعدة مع الاحتفاظ بها، اضبط `enabled` على `false` بدلاً من ذلك. عادةً ما يتم تقاعد إعدادات القناة الافتراضية بدلاً من حذفها، وهو ما تفعله `DELETE /entry-points/channel-defaults`.

---

## التحقق من تفعيل التوجيه

`GET /entry-points/routing-status` — تُرجع ما إذا كان سلم نقاط الإدخال (Entry Points) يحدد من يجيب على هذا الحساب. قابلة للقراءة بصلاحية العرض، لذا يرى زميل الفريق نفس الإجابة التي يراها المالك.

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

```json
{ "success": true, "cutover_enabled": true }
```

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

---

## المكالمات القديمة ذات الشكل الخاص بالحملات

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

- `PUT /channel-routing/{channel}` مع `{ "campaignId": "cp5NbV8xQrT2wYzA" }` — تسمية حملة، ويصبح وكيل تلك الحملة هو المسؤول عن الإجابة على القناة. `{ "campaignId": null }` يفرغ القناة. يتم رفض الحملة المخصصة للصادر فقط لأنه ليس لديها سلوك وارد لتقدمه.
- `POST /channel-routing/clear` مع `{ "channels": ["whatsapp", "instagram"] }` — يحرر عدة قنوات من أي وكيل يجيب عليها في مكالمة واحدة، عادةً قبل توجيهها إلى مكان آخر. يسرد الرد `released_channels`، وهي القنوات التي كان لديها بالفعل مجيب.

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

---

## أخطاء واجهة برمجة تطبيقات نقاط الإدخال (Entry Points API)

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

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

| الحالة | متى يحدث ذلك في نقطة نهاية نقطة الإدخال |
|---|---|
| `400` | حقل مفقود أو أن القاعدة ستكون غير قابلة للاستخدام: لا يوجد `channel` أو `agent_id` في مكالمة تعيين، أو `type` غير معروف، أو `channels` فارغ، أو قاعدة كلمات رئيسية بدون كلمات رئيسية، أو قاعدة تعليق لا تسرد قناتها الخاصة، أو `agent_id` فارغ عند التحديث، أو نص تحديث فارغ، أو `phone_number` ليس واحداً من أرقامك المتصلة. |
| `403` | قد لا يتمكن المفتاح أو عضو الفريق من تعديل التوجيه. تتطلب عمليات الكتابة حقوق تعديل على الحملات؛ وتتطلب عمليات قراءة القائمة والحالة حقوق عرض. |
| `404` | لم يتم العثور على نقطة الإدخال أو الوكيل — إما أنه غير موجود أو أنه ينتمي إلى حساب آخر. |

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


---

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

- [نقاط الإدخال](../ai-agents/entry-points.md) — المفهوم، وأنواع القواعد، ولوحة **من يجيب على المحادثات الجديدة** في التطبيق.
- [واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي](agents.md) — إنشاء وتكوين الوكلاء الذين توجه هذه القواعد إليهم.
- [واجهة برمجة تطبيقات القنوات](channels.md) — توصيل القنوات نفسها.
- [أتمتة التعليق إلى رسالة مباشرة](../ai-automation/comment-to-dm.md) — ما تفعله قواعد التعليق بمجرد تفعيلها.