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

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

• عنوان URL الأساسي — https://api.youraiconnector.com/v1
• المصادقة — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع المصادقة)
• الأخطاء والترقيم — راجع الأخطاء والترقيم

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

إذا كنت جديداً على مفهوم الوكلاء، فاقرأ وكلاء الذكاء الاصطناعي أولاً.

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

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

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

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

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

{
  "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
}

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

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

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

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

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

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

cURL

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

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

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)

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

إنشاء وكيل #

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

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

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

cURL

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

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

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)

{
  "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

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

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

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

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

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

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)

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

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

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

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

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

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

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 ساعة. الأيام التي تتركها ستحتفظ بما كانت عليه، وأي مفتاح ليس يوم عمل سيتم رفضه — لذا فإن الخطأ المطبعي لا يمكن أن يمر دون تأثير.

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)

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

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

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

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

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

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)

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

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

تكرار وكيل #

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

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

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

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

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

حذف وكيل #

DELETE /agents/{agentId}

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

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

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

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

محظور (409)

{
  "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": []
}

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

يتم الاحتفاظ بالتعديلات التي يتم إجراؤها في المحرر، وأي إعادة صياغة يتم إنتاجها بواسطة التحسين باستخدام الذكاء الاصطناعي، كـ مسودة غير منشورة حتى تقوم بنشرها. يستمر الوكيل المباشر (Live Agent) في الرد بإعداداته الحالية حتى ذلك الحين.

نشر المسودة #

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

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

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

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

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

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

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

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

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 المسيء. يجب أن يحتوي واحد منهما على الأقل على نص.

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)

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

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

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

قواعد الوسم #

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

كائن القاعدة

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

POST /agents/{agentId}/tags

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)

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

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

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

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) عن تطبيق ذلك الوسم. يظل الوسم نفسه، وأي جهات اتصال تحمل هذا الوسم بالفعل، دون تغيير.

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

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

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

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

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)

{ "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 لمصدر واحد. أرسل أياً منهما. إرفاق شيء مرفق بالفعل لا يغير شيئاً.

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)

{
  "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).

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 لإزالتها مرة أخرى. يمكن مشاركة الأسئلة الشائعة بواسطة أي عدد من الوكلاء. راجع واجهة برمجة تطبيقات الأسئلة الشائعة.

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

الأدوات #

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

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

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 — راجع الوظائف المخصصة لمعرفة ماهيتها.

خوادم MCP #

خادم MCP هو حزمة جاهزة من الأدوات التي يمكن لوكيلك اكتشافها واستدعاؤها بنفسه — راجع ربط خوادم MCP بالبوت الخاص بك. يتم تسجيل الخوادم مرة واحدة في الحساب، ثم يتم إرفاقها بأي وكلاء يجب أن يستخدموها.

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

تسجيل خادم #

POST /mcp-servers

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)

{
  "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) وحملة كانت تستخدمه.

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) — اختبار قبل الحفظ لا يخزن أي شيء.

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)

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

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

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

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

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)

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

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

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

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

سرد الوسائط #

GET /agents/{agentId}/media-library

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

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

{
  "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.

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 لمسح الحد).

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)

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

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

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

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

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

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

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). حتى تحتوي القناة على واحدة، تظل الرسالة الأولى من شخص لم تتحدث معه من قبل مخزنة، ولكن لا يلتقطها أحد ولا يرد أي مساعد.

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

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

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).

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

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)

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

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

هذه نسخة مختصرة. يغطي دليل Entry Points API القواعد الكاملة للترتيب والتعليقات والمتابعين، ووكيل واحد لكل رقم WhatsApp، وتغيير القاعدة أو حذفها. راجع Entry Points لمعرفة المفهوم، وChannels API لربط القناة نفسها.

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

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

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

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

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

ذات صلة #

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