API pentru Întrebări frecvente (FAQs) #

Întrebările frecvente (FAQs) sunt intrările de tip întrebare-răspuns pe care botul tău AI le folosește atunci când răspunde clienților. Fiecare FAQ aparține contului tău și poate fi asociat uneia sau mai multor campanii, astfel încât același răspuns să poată fi refolosit oriunde este relevant. API-ul pentru FAQs îți permite să gestionezi acea bibliotecă programatic — să creezi, să actualizezi, să imporți în masă, să reordonezi și să asociezi FAQs campaniilor direct din codul tău.

Toate endpoint-urile de mai jos sunt relative la URL-ul de bază https://api.youraiconnector.com/v1. Fiecare cerere trebuie să fie autentificată — consultă Acces API și Autentificare. Accesul la API este o funcționalitate cu plată; fără acesta, cererile sunt respinse cu un 403.

Cum folosește botul un FAQ: Când creezi sau modifici un FAQ, platforma pregătește datele de căutare (folosite pentru a potrivi FAQ-ul cu întrebările primite) în fundal. Acest proces durează de obicei câteva secunde, după care botul începe să folosească automat intrarea respectivă.

Obiectul FAQ #

Fiecare FAQ returnat de API are următoarea structură:

Câmpurile pe care le poți seta sunt: question, answer, is_active, is_global, category, tags și order_index. Platforma gestionează tot restul (datele de căutare, numărul de utilizări, marcajele temporale); orice alte câmpuri din corpul cererii tale sunt ignorate.

Listare FAQs #

GET /faqs

Returnează FAQs din contul tău, cele mai noi fiind primele. Opțional, poți filtra după o singură campanie sau după starea de activare.

Parametri de interogare

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"])

Răspuns

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

Când next_cursor este null, nu mai există rezultate.

Obține o întrebare frecventă (FAQ) #

GET /faqs/{faqId}

Returnează o singură întrebare frecventă (FAQ) după ID-ul acesteia.

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

Răspuns

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

Creează o întrebare frecventă (FAQ) #

POST /faqs

Creează o nouă întrebare frecventă (FAQ) și o conectează la o campanie.

Câmpuri de solicitare

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

Răspuns

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

Actualizarea unei întrebări frecvente (FAQ) #

PUT /faqs/{faqId}

Actualizează parțial o întrebare frecventă. Doar câmpurile editabile furnizate sunt modificate; tot restul își păstrează valoarea curentă. Modificarea question sau answer reîmprospătează automat datele de căutare ale întrebării frecvente în fundal.

Dacă trimiți question sau answer, acestea trebuie să fie șiruri de caractere care nu sunt goale. Trimiterea unor câmpuri editabile nerecunoscute returnează un 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()

Răspuns

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

Ștergerea unei întrebări frecvente (FAQ) #

DELETE /faqs/{faqId}

Șterge permanent o întrebare frecventă. Opțional, transmite campaign_id ca parametru de interogare pentru a elimina, de asemenea, întrebarea frecventă din lista de întrebări frecvente a acelei campanii.

Parametri de interogare

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

Răspuns

{
  "success": true
}

Ștergerea în masă a întrebărilor frecvente #

POST /faqs/bulk-delete

Șterge până la 500 de întrebări frecvente într-o singură cerere. Când campaign_id este furnizat, întrebările frecvente șterse sunt eliminate și din lista de întrebări frecvente a acelei campanii.

Câmpuri de solicitare

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

Răspuns

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

Întrebări frecvente (FAQ) importate #

POST /faqs/import

Importă în masă până la 500 de întrebări frecvente și le conectează pe toate la o singură campanie. Elementele a căror question corespunde unei întrebări frecvente existente în biblioteca ta (fără a ține cont de majuscule/minuscule) actualizează acea întrebare frecventă în loc să creeze un duplicat.

Sfat de performanță: Potrivirea duplicatelor scanează întreaga bibliotecă de întrebări frecvente, deci bibliotecile foarte mari încetinesc importurile. Preferă importuri mai puține și mai mari în detrimentul multor importuri mici.

Câmpuri de solicitare

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

Răspuns

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

faq_ids sunt ID-urile întrebărilor frecvente create sau actualizate, în ordinea în care le-ați furnizat.

Reordonarea întrebărilor frecvente #

POST /faqs/reorder

Stabilește ordinea de afișare a întrebărilor frecvente dintr-o campanie. Furnizați lista completă a ID-urilor FAQ în ordinea dorită; poziția fiecărei întrebări frecvente este actualizată pentru a corespunde locului său în matrice.

Câmpuri de solicitare

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

Răspuns

{
  "success": true
}

Dacă campania sau oricare dintre ID-urile FAQ nu este găsită în contul tău, cererea returnează 404 One or more FAQs were not found.

Conectează o întrebare frecventă (FAQ) la o campanie #

POST /faqs/{faqId}/link

Conectează o întrebare frecventă (FAQ) existentă la o campanie suplimentară. O întrebare frecventă poate fi partajată de orice număr de campanii, astfel încât același răspuns trebuie menținut o singură dată.

Câmpuri de solicitare

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

Răspuns

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

Deconectarea unei întrebări frecvente (FAQ) de la o campanie #

POST /faqs/{faqId}/unlink

Elimină o întrebare frecventă dintr-o campanie fără a șterge întrebarea în sine. Întrebarea frecventă rămâne în biblioteca ta și continuă să fie conectată la orice alte campanii.

Câmpuri de solicitare

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

Răspuns

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

Reconstruirea datelor de căutare ale unei întrebări frecvente #

POST /faqs/{faqId}/rebuild-embeddings

Pune la coadă o reconstrucție a datelor pe care botul AI le folosește pentru a găsi această întrebare frecventă (datele sale de căutare semantică și prin cuvinte cheie). Acest lucru este util dacă o întrebare frecventă nu este preluată în răspunsuri așa cum era de așteptat. Reconstrucția rulează în fundal și se finalizează de obicei în câteva secunde; întrebarea frecventă poate fi exclusă temporar din răspunsurile AI în timp ce este reconstruită.

Acest endpoint returnează 202 Accepted deoarece procesul continuă după ce răspunsul este trimis. status este întotdeauna "processing" — re-interogați întrebarea frecventă mai târziu dacă trebuie să confirmați finalizarea.

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

Răspuns

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

Gestionarea FAQ asistată de AI #

Endpoint-urile de mai jos depășesc funcționalitățile CRUD simple: ele apelează aceleași instrumente de asistență AI pe care le folosește editorul de FAQ din tabloul de bord — identificarea duplicatelor, generarea de intrări dintr-un document și potrivirea FAQ-urilor cu sarcinile deschise privind lacunele de cunoștințe. Corpurile cererilor din acest set utilizează nume de câmpuri camelCase (campaignId, taskId, sourceIds…), care corespund formelor de cerere ale aplicației, în loc de snake_case utilizat în altă parte pe această pagină — copiați exemplele de mai jos în loc să ghiciți numele unui câmp.

Creați o copie a unui FAQ specifică unei campanii #

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

Creează un nou FAQ care este o copie a unuia existent, limitat la o singură campanie, și re-conectează acea campanie la noua copie în loc de cea originală. Utilizați această funcție atunci când doriți să personalizați un răspuns pentru o campanie fără a-l modifica peste tot unde este utilizat FAQ-ul original. FAQ-ul original rămâne pe loc — își pierde doar legătura cu această campanie.

Câmpuri de solicitare

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

Răspuns — 201 Created

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

Găsirea FAQ-urilor aproape duplicate #

POST /faqs/dedupe

Pornește o sarcină de fundal care scanează biblioteca dvs. de FAQ pentru intrări aproape duplicate sau care se suprapun și le îmbină sau le elimină acolo unde există certitudine. Util după o importare în masă sau după mai multe runde de FAQ-uri generate de AI care au lăsat biblioteca cu suprapuneri. Doar o singură sarcină de deduplicare poate rula per cont la un moment dat — pornirea unei a doua sarcini în timp ce una este încă în desfășurare returnează 409.

Câmpuri de solicitare

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

Răspuns — 202 Accepted

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

Sarcina rulează în fundal și durează de obicei câteva minute pentru o bibliotecă mare. Nu există un endpoint de stare separat — re-interogați GET /faqs după o scurtă așteptare pentru a vedea ce s-a schimbat. Când ați terminat de revizuit rezultatul, apelați endpoint-ul de respingere de mai jos pentru a-l șterge.

Respingerea unui rezultat de verificare a duplicatelor #

POST /faqs/dedupe/dismiss

Șterge sarcina de deduplicare finalizată, astfel încât să nu mai apară ca rezultat activ. Idempotent — sigur de apelat chiar dacă nu există nimic de respins. Returnează 409 dacă sarcina este încă queued sau processing (nu puteți respinge o execuție care nu s-a finalizat).

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

Răspuns

{ "success": true }

Generați întrebări frecvente (FAQ) din documentele încărcate #

POST /faqs/generate-from-documents

Citește unul sau mai multe documente aflate deja în stocarea de fișiere a contului dvs. și pune AI-ul să redacteze întrebări frecvente din conținutul acestora, verificând ciornele față de biblioteca existentă, astfel încât să refolosească sau să actualizeze intrările în loc să creeze duplicate. Rezultatele nu sunt scrise imediat — ele sunt stocate ca un set de modificări în așteptare în cadrul campaniei pentru a fi revizuite, apoi aplicate (sau eliminate) cu Aplică modificările FAQ revizuite de mai jos. Această acțiune consumă credite, deoarece reprezintă o etapă de generare AI pe baza textului din document.

Acest endpoint nu transportă fișierul: storagePath trebuie să indice un fișier aflat deja în propriul folder de încărcări (users/{your user id}/uploads/), respectând aceeași convenție ca la Importă un document încărcat din API-ul Bazei de cunoștințe.

Câmpuri de solicitare

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

Răspuns — 202 Accepted

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

faqCount este numărul total de modificări propuse care așteaptă revizuirea; reusedCount, modifiedCount și newCount descompun acest număr în întrebări frecvente care s-au potrivit cu o intrare existentă fără modificări, cele pe care AI-ul propune să le editeze și cele complet noi. Fișierele încărcate sunt șterse din stocare odată ce procesarea se termină, indiferent dacă aceasta reușește sau nu.

Aplică modificările FAQ revizuite #

POST /faqs/apply-optimization

Aplică (sau elimină) un set în așteptare de modificări FAQ propuse de AI — tipul produs de Generează întrebări frecvente din documente de mai sus sau de revizuirea optimizării FAQ din tabloul de bord. Alegeți exact ce modificări propuse să acceptați; orice nu menționați rămâne neatins (o modificare omisă nu este niciodată tratată ca o respingere care șterge ceva).

Câmpuri de solicitare

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

Răspuns

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

faq_count este numărul total de întrebări frecvente legate de campanie (sau Agent) după aplicare. Dacă nu a existat niciun set de modificări în așteptare de aplicat, răspunsul este { "success": true, "message": "No pending FAQ changes to apply" }.

Găsește întrebări frecvente similare cu o sarcină #

POST /faqs/similar-for-task

Clasifică biblioteca dvs. de întrebări frecvente în funcție de relevanța pentru întrebarea unei sarcini de tip „knowledge-gap” — aceeași căutare din spatele selectorului „Folosește o întrebare frecventă existentă” din tabloul de bord. Doar citire. taskId trebuie să indice o sarcină de tip faq_update.

Acest endpoint răspunde întotdeauna cu 200, chiar și în cazul unei erori așteptate, cum ar fi o sarcină necunoscută — verificați success în corp în loc de starea HTTP.

Câmpuri de solicitare

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

Răspuns

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

Potrivirile sunt sortate după similarity (potrivire semantică atunci când este disponibilă, suprapunere de cuvinte cheie în caz contrar), cele mai bune fiind primele. În cazul unei erori minore, formatul este { "success": false, "error": "...", "error_code": 404 } — error_code reflectă ceea ce ar fi fost în mod normal starea HTTP.

Rezolvarea unei sarcini cu un FAQ existent #

POST /faqs/resolve-task

Rezolvă o sarcină de tip „lacună de cunoștințe” prin conectarea acesteia la un FAQ pe care îl aveți deja (în loc să scrieți unul nou), trimite răspunsul acelui FAQ către contactul care a declanșat lacuna și marchează sarcina ca finalizată. Utilizați acest lucru după ce Găsirea FAQ-urilor similare cu o sarcină identifică un FAQ existent care acoperă deja întrebarea.

La fel ca endpoint-ul de mai sus, acesta răspunde întotdeauna cu 200 — verificați success în corp.

Câmpuri de solicitare

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

Răspuns

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

follow_up_status vă spune ce s-a întâmplat cu urmărirea contactului: published (trimis imediat), queued (AI-ul era deja în mijlocul unui răspuns către acel contact, deci va fi trimis ulterior), skipped_no_contact (sarcina nu are niciun contact asociat) sau skipped_no_campaign (nu există nicio campanie prin care să fie trimis).

Erori API pentru întrebări frecvente (FAQ) #

Endpoint-urile FAQ returnează plicul de eroare standard:

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

Codurile partajate pe care orice endpoint le poate returna — 401, 403 (planul dvs. nu include acces API), 429 (limită de rată) și 500 — sunt listate cu îndrumări pentru reîncercare în Erori și Paginare.

POST /faqs/similar-for-task și POST /faqs/resolve-task sunt cele două excepții de pe această pagină: ele răspund cu 200 chiar și pentru o eroare așteptată (sarcină necunoscută, tip de sarcină greșit) și plasează starea reală în error_code din corp în schimb — consultați fiecare endpoint de mai sus.

Legate #

• API Campanii — campaniile la care sunt legate FAQ-urile dumneavoastră.
• API Bază de cunoștințe — importați automat site-uri web și documente în FAQ-uri și grupați FAQ-urile în grupuri de cunoștințe reutilizabile.
• Acces API — generați cheia API.
• Autentificare — toate modalitățile de a transmite cheia dumneavoastră.