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

تُعد نقطة الدخول (Entry Point) قاعدة توجيه: “عند حدوث هذا على هذه القناة، قم بتسليم المحادثة إلى هذا الوكيل (Agent)”. يؤدي ربط قناة ما إلى وصول الرسائل إلى الحساب، كما يمنحك إنشاء وكيل شيئاً يمكنه الرد، ولكن لا يقرر أي منهما من يجيب على الرسالة الأولى لشخص غريب. نقاط الدخول هي التي تقرر ذلك. للمنتج نفسه، راجع دليل نقاط الدخول.

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

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

في مستكشف واجهة برمجة التطبيقات. كل نقطة نهاية في هذه الصفحة موجودة في مواصفات OpenAPI المنشورة، لذا يمكنك تصفح حقولها بدقة وتشغيل طلبات مباشرة في مستكشف واجهة برمجة التطبيقات.

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

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

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. تم تعيين جهة الاتصال بالفعل لوكيل، يدوياً أو لأن محادثة مع هذا الوكيل جارية — يحتفظ نفس الوكيل بها. لا تقوم نقاط الدخول أبداً بنقل محادثة قائمة؛ لتسليم محادثة إلى وكيل مختلف، قم بتعيينها (في التطبيق، أو باستخدام إجراء الأتمتة).
3. جهة الاتصال ترد على بث — يجيب وكيل البث، أو لا أحد إذا لم يكن للبث وكيل.
4. تطابق نقطة دخول محددة. قواعد الكلمات الرئيسية تتفوق على قواعد التعليقات، والتي تتفوق بدورها على قواعد المتابعين. بين قاعدتين من نفس النوع، تفوز القاعدة التي تم تحديثها مؤخراً.
5. الإعداد الافتراضي للقناة التي وصلت عليها الرسالة. الإعداد الافتراضي المخصص لرقم معين كتب إليه جهة الاتصال يتفوق على الإعداد الافتراضي للقناة بأكملها.
6. لم يتم العثور على تطابق — تصل الرسالة إلى صندوق الوارد الخاص بفريقك ولا يرد أي مساعد.

هناك أمران يخففان من حدة الخطوة 6. الحساب الذي يحتوي على وكيل نشط واحد فقط ولا يوجد إعداد افتراضي للقناة لا يزال يحصل على هذا الوكيل كمسؤول عن الرد، لذا فإن الحساب الجديد الذي يربط واتساب ويرسل رسالة اختبار لا يواجه الصمت. لا ينطبق هذا الحد الأدنى أبداً على قناة تحتوي على قاعدة كلمات رئيسية (هناك، تُترك الرسالة التي لا تطابق أي كلمة رئيسية للإنسان عمداً) ولا يتجاوز أبداً قناة قمت بتعيينها على “لا أحد” (راجع ترك قناة دون رد من أحد).

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

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

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

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

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

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

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

cURL

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

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

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

الاستجابة

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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

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

الاستجابة

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

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

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

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

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

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

cURL

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

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

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)

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

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

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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

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

الاستجابة

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

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

حذف قاعدة #

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

cURL

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

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

import requests

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

الاستجابة

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

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

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

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

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

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

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

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

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

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

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