واجهة برمجة تطبيقات الأسئلة الشائعة (FAQs API) #

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

جميع نقاط النهاية أدناه نسبية إلى عنوان URL الأساسي https://api.youraiconnector.com/v1. يجب أن تكون كل طلبية مصادقاً عليها — راجع الوصول إلى واجهة برمجة التطبيقات والمصادقة. الوصول إلى واجهة برمجة التطبيقات هو ميزة مدفوعة؛ وبدونها، يتم رفض الطلبات مع 403.

كيف يستخدم الروبوت الأسئلة الشائعة: عند إنشاء أو تغيير سؤال شائع، تقوم المنصة بإعداد بيانات البحث الخاصة به (المستخدمة لمطابقة السؤال الشائع مع الأسئلة الواردة) في الخلفية. عادة ما ينتهي هذا في غضون ثوانٍ قليلة، وبعد ذلك يبدأ الروبوت في استخدام المدخل تلقائياً.

كائن الأسئلة الشائعة (FAQ object) #

كل سؤال شائع يتم استرجاعه من واجهة برمجة التطبيقات له هذا الشكل:

الحقول التي يمكنك تعيينها هي: question، وanswer، وis_active، وis_global، وcategory، وtags، وorder_index. تدير المنصة كل شيء آخر (بيانات البحث، وعدد مرات الاستخدام، والطوابع الزمنية)؛ يتم تجاهل أي حقول أخرى في نص طلبك.

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

GET /faqs

يعيد الأسئلة الشائعة في حسابك، بدءاً من الأحدث. يمكنك اختيارياً التصفية حسب حملة واحدة أو حسب حالة النشاط.

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

cURL

curl "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.faqs, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs",
    params={"campaign_id": "campaign123", "limit": 50},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["faqs"], data["next_cursor"])

الاستجابة

{
  "success": true,
  "faqs": [
    {
      "id": "aBcD1234eFgH5678",
      "question": "How long does shipping take?",
      "answer": "Standard shipping takes 3-5 business days.",
      "category": "shipping",
      "tags": ["logistics", "delivery"],
      "is_active": true,
      "is_global": false,
      "usage_count": 12,
      "order_index": 0,
      "campaign_ids": ["campaign123"],
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-02T08:30:00.000Z"
    }
  ],
  "next_cursor": "aBcD1234eFgH5678"
}

عندما تكون next_cursor هي null، لا توجد نتائج أخرى.

الحصول على سؤال شائع (FAQ) #

GET /faqs/{faqId}

إرجاع سؤال شائع واحد بواسطة معرفه (ID).

cURL

curl "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { faq } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
faq = res.json()["faq"]

الاستجابة

{
  "success": true,
  "faq": {
    "id": "aBcD1234eFgH5678",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"],
    "is_active": true,
    "is_global": false,
    "usage_count": 12,
    "order_index": 0,
    "campaign_ids": ["campaign123"],
    "created_at": "2026-01-01T12:00:00.000Z",
    "updated_at": "2026-01-02T08:30:00.000Z"
  }
}

إنشاء سؤال شائع (FAQ) #

POST /faqs

إنشاء سؤال شائع جديد وربطه بحملة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    question: "How long does shipping take?",
    answer: "Standard shipping takes 3-5 business days.",
    category: "shipping",
    tags: ["logistics"],
  }),
});
const { faq_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "tags": ["logistics"],
    },
)
faq_id = res.json()["faq_id"]

الاستجابة

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

تحديث الأسئلة الشائعة #

PUT /faqs/{faqId}

يُحدِّث الأسئلة الشائعة جزئياً. يتم تغيير الحقول القابلة للكتابة المقدمة فقط؛ بينما يحتفظ كل شيء آخر بقيمته الحالية. يؤدي تغيير question أو answer تلقائياً إلى تحديث بيانات بحث الأسئلة الشائعة في الخلفية.

إذا قمت بإرسال question أو answer، فيجب أن تكون سلاسل نصية غير فارغة. إرسال حقول قابلة للكتابة غير معروفة يؤدي إلى إرجاع 400.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_active: false }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False},
)
data = res.json()

الاستجابة

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

حذف الأسئلة الشائعة #

DELETE /faqs/{faqId}

يحذف الأسئلة الشائعة نهائياً. يمكنك اختيارياً تمرير campaign_id كمعامل استعلام لإزالة الأسئلة الشائعة أيضاً من قائمة الأسئلة الشائعة الخاصة بتلك الحملة.

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

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123",
  { 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/faqs/aBcD1234eFgH5678",
    params={"campaign_id": "campaign123"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

الاستجابة

{
  "success": true
}

حذف الأسئلة الشائعة بالجملة #

POST /faqs/bulk-delete

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

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/bulk-delete", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq_ids: ["faqId1", "faqId2"],
    campaign_id: "campaign123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/bulk-delete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123"},
)
data = res.json()

الاستجابة

{
  "success": true,
  "deleted_count": 2
}

الأسئلة الشائعة حول الاستيراد #

POST /faqs/import

استيراد جماعي لما يصل إلى 500 سؤال شائع وربطها جميعاً بحملة واحدة. العناصر التي يطابق question الخاص بها سؤالاً شائعاً موجوداً في مكتبتك (مع تجاهل حالة الأحرف) يتم تحديثها بدلاً من إنشاء نسخة مكررة.

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

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "faqs": [
      { "question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide." },
      { "question": "What is your return policy?", "answer": "You can return any item within 30 days." }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    faqs: [
      {
        question: "Do you ship internationally?",
        answer: "Yes, we ship to most countries worldwide.",
      },
      {
        question: "What is your return policy?",
        answer: "You can return any item within 30 days.",
      },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "faqs": [
            {"question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide."},
            {"question": "What is your return policy?", "answer": "You can return any item within 30 days."},
        ],
    },
)
data = res.json()

الاستجابة

{
  "success": true,
  "faq_ids": ["aBcD1234eFgH5678", "iJkL9012mNoP3456"],
  "imported_count": 2
}

faq_ids هي معرفات الأسئلة الشائعة التي تم إنشاؤها أو تحديثها، بنفس الترتيب الذي قدمتها به.

إعادة ترتيب الأسئلة الشائعة #

POST /faqs/reorder

يحدد ترتيب عرض الأسئلة الشائعة الخاصة بالحملة. قم بتوفير القائمة الكاملة لمعرفات الأسئلة الشائعة بالترتيب المطلوب؛ يتم تحديث موضع كل سؤال شائع ليتطابق مع مكانه في المصفوفة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/reorder", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    ordered_faq_ids: ["faqId2", "faqId1", "faqId3"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"],
    },
)
data = res.json()

الاستجابة

{
  "success": true
}

إذا لم يتم العثور على الحملة أو أي من معرفات الأسئلة الشائعة في حسابك، فسيقوم الطلب بإرجاع 404 One or more FAQs were not found.

ربط سؤال شائع بحملة #

POST /faqs/{faqId}/link

يربط سؤالاً شائعاً موجوداً بحملة إضافية. يمكن مشاركة السؤال الشائع بواسطة أي عدد من الحملات، لذا لا يلزم الاحتفاظ بنفس الإجابة إلا مرة واحدة فقط.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

الاستجابة

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

إلغاء ربط الأسئلة الشائعة من حملة #

POST /faqs/{faqId}/unlink

يؤدي هذا إلى إزالة الأسئلة الشائعة من حملة دون حذف الأسئلة الشائعة نفسها. تظل الأسئلة الشائعة في مكتبتك وتظل مرتبطة بأي حملات أخرى.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

الاستجابة

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

إعادة بناء بيانات البحث الخاصة بالأسئلة الشائعة #

POST /faqs/{faqId}/rebuild-embeddings

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

تُرجع نقطة النهاية هذه 202 Accepted لأن العمل يستمر بعد إرسال الاستجابة. تكون قيمة status دائمًا "processing" — أعد جلب الأسئلة الشائعة لاحقًا إذا كنت بحاجة إلى تأكيد الاكتمال.

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

الاستجابة

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "status": "processing"
}

إدارة الأسئلة الشائعة بمساعدة الذكاء الاصطناعي #

تتجاوز نقاط النهاية أدناه عمليات CRUD العادية: فهي تستدعي نفس أدوات المساعدة بالذكاء الاصطناعي التي يستخدمها محرر الأسئلة الشائعة في لوحة التحكم — للعثور على التكرارات، وإنشاء إدخالات من مستند، ومطابقة الأسئلة الشائعة مع مهام فجوات المعرفة المفتوحة. تستخدم نصوص الطلبات في هذه المجموعة أسماء حقول camelCase (campaignId، taskId، sourceIds…)، والتي تطابق أشكال طلبات التطبيق نفسه، بدلاً من snake_case المستخدمة في أماكن أخرى في هذه الصفحة — انسخ الأمثلة أدناه بدلاً من تخمين اسم الحقل.

إنشاء نسخة مخصصة لحملة واحدة من سؤال شائع #

POST /faqs/{faqId}/fork-for-campaign

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

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign456",
    "question": "How long does shipping take to the EU?",
    "answer": "For EU orders, shipping takes 7-10 business days."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "campaign456",
      question: "How long does shipping take to the EU?",
      answer: "For EU orders, shipping takes 7-10 business days.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign456",
        "question": "How long does shipping take to the EU?",
        "answer": "For EU orders, shipping takes 7-10 business days.",
    },
)
data = res.json()

الاستجابة — 201 Created

{
  "success": true,
  "faq_id": "nEwFaQiD9012mNoP",
  "campaign_id": "campaign456",
  "original_faq_id": "aBcD1234eFgH5678"
}

العثور على الأسئلة الشائعة المتشابهة #

POST /faqs/dedupe

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

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={},
)
data = res.json()

الاستجابة — 202 Accepted

{
  "success": true,
  "job_id": "dedupJob_aBc123"
}

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

تجاهل نتيجة فحص التكرار #

POST /faqs/dedupe/dismiss

يمسح مهمة إلغاء التكرار المنتهية حتى تتوقف عن الظهور كنتيجة نشطة. عملية غير مؤثرة (Idempotent) — آمنة للاستدعاء حتى لو لم يكن هناك شيء لتجاهله. يُرجع 409 إذا كانت المهمة لا تزال queued أو processing (لا يمكنك تجاهل تشغيل لم ينتهِ بعد).

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe/dismiss", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

الاستجابة

{ "success": true }

إنشاء أسئلة شائعة من المستندات التي تم تحميلها #

POST /faqs/generate-from-documents

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

لا يحمل نقطة النهاية هذه الملف: يجب أن تشير storagePath إلى ملف موجود بالفعل ضمن مجلد التحميلات الخاص بك (users/{your user id}/uploads/)، وهو نفس الاصطلاح المستخدم في استيراد مستند تم تحميله في واجهة برمجة تطبيقات قاعدة المعرفة.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/generate-from-documents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "uploadedFiles": [
      { "storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/generate-from-documents", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    uploadedFiles: [
      { storagePath: "users/abc123uid/uploads/handbook.pdf", fileName: "handbook.pdf", mimeType: "application/pdf" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/generate-from-documents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "uploadedFiles": [
            {"storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf"},
        ],
    },
)
data = res.json()

الاستجابة — 202 Accepted

{
  "success": true,
  "faqCount": 6,
  "reusedCount": 2,
  "modifiedCount": 1,
  "newCount": 3
}

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

تطبيق تغييرات الأسئلة الشائعة المراجعة #

POST /faqs/apply-optimization

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

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/apply-optimization?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "acceptedChanges": [
      { "action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days." },
      { "action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/apply-optimization", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    acceptedChanges: [
      { action: "create_new", question: "Do you ship to the EU?", answer: "Yes, EU shipping takes 7-10 business days." },
      { action: "remove", faq_ref_path: "users/abc123uid/faqs/oldFaqId" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/apply-optimization",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "acceptedChanges": [
            {"action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days."},
            {"action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId"},
        ],
    },
)
data = res.json()

الاستجابة

{
  "success": true,
  "message": "Applied 2 FAQ changes",
  "faq_count": 7
}

faq_count هو إجمالي عدد الأسئلة الشائعة المرتبطة بالحملة (أو الوكيل) بعد التطبيق. إذا لم تكن هناك مجموعة تغييرات معلقة ليتم تطبيقها، تكون الاستجابة { "success": true, "message": "No pending FAQ changes to apply" }.

العثور على أسئلة شائعة مشابهة لمهمة #

POST /faqs/similar-for-task

ترتيب مكتبة الأسئلة الشائعة الخاصة بك حسب الصلة بسؤال مهمة فجوة المعرفة — وهو نفس البحث الموجود خلف أداة اختيار “استخدام سؤال شائع موجود” في لوحة التحكم. للقراءة فقط. يجب أن تشير taskId إلى مهمة من النوع faq_update.

تستجيب نقطة النهاية هذه دائمًا بـ 200، حتى في حالة الفشل المتوقع مثل مهمة غير معروفة — تحقق من success في النص الأساسي بدلاً من حالة HTTP.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/similar-for-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "limit": 10 }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/similar-for-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", limit: 10 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/similar-for-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "limit": 10},
)
data = res.json()

الاستجابة

{
  "success": true,
  "data": {
    "task_id": "task789",
    "matches": [
      {
        "faq_id": "aBcD1234eFgH5678",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "created_at": "2026-01-01T12:00:00.000Z",
        "similarity": 0.81,
        "embedding_similarity": 0.81,
        "keyword_similarity": 0.6,
        "bm25_score": 4.2,
        "distance": 0.19
      }
    ]
  }
}

يتم فرز المطابقات حسب similarity (مطابقة دلالية عند توفرها، أو تداخل الكلمات الرئيسية بخلاف ذلك)، مع عرض الأفضل أولاً. في حالة الفشل الطفيف، يكون الشكل { "success": false, "error": "...", "error_code": 404 } — حيث يعكس error_code ما ستكون عليه حالة HTTP عادةً.

حل مهمة باستخدام أسئلة شائعة موجودة #

POST /faqs/resolve-task

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

مثل نقطة النهاية أعلاه، تستجيب هذه دائمًا بـ 200 — تحقق من success في النص الأساسي.

حقول الطلب

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/resolve-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "faqId": "aBcD1234eFgH5678" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/resolve-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", faqId: "aBcD1234eFgH5678" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/resolve-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "faqId": "aBcD1234eFgH5678"},
)
data = res.json()

الاستجابة

{
  "success": true,
  "data": {
    "task_id": "task789",
    "faq_id": "aBcD1234eFgH5678",
    "follow_up_status": "published"
  }
}

يخبرك follow_up_status بما حدث لمتابعة جهة الاتصال: published (تم الإرسال على الفور)، queued (كان الذكاء الاصطناعي في منتصف الرد على جهة الاتصال تلك، لذا سيتم إرساله لاحقًا)، skipped_no_contact (المهمة ليس لها جهة اتصال مرتبطة)، أو skipped_no_campaign (لا توجد حملة للإرسال من خلالها).

أخطاء واجهة برمجة تطبيقات الأسئلة الشائعة #

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

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

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

POST /faqs/similar-for-task و POST /faqs/resolve-task هما الاستثناءان الوحيدان في هذه الصفحة: فهما يستجيبان بـ 200 حتى في حالة الفشل المتوقع (مهمة غير معروفة، نوع مهمة خاطئ) ويضعان الحالة الحقيقية في error_code ضمن النص الأساسي بدلاً من ذلك — راجع كل نقطة نهاية أعلاه.

ذات صلة #

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