API FAQ

Le FAQ sono le voci di domanda e risposta a cui il tuo bot AI attinge quando risponde ai clienti. Ogni FAQ appartiene al tuo account e può essere collegata a una o più campagne, in modo che la stessa risposta possa essere riutilizzata ovunque sia pertinente. L’API FAQ ti consente di gestire tale libreria a livello programmatico: creare, aggiornare, importare in blocco, riordinare e collegare le FAQ alle campagne dal tuo codice.

Tutti gli endpoint seguenti sono relativi all’URL di base https://api.youraiconnector.com/v1. Ogni richiesta deve essere autenticata: consulta Accesso API e Autenticazione. L’accesso all’API è una funzionalità a pagamento; in caso contrario, le richieste verranno rifiutate con un 403.

Come il bot utilizza una FAQ: Quando crei o modifichi una FAQ, la piattaforma prepara i suoi dati di ricerca (utilizzati per abbinare la FAQ alle domande in arrivo) in background. Questa operazione solitamente si conclude in pochi secondi, dopodiché il bot inizia a utilizzare la voce automaticamente.

L’oggetto FAQ

Ogni FAQ restituita dall’API ha questa struttura:

Campo	Tipo	Descrizione
`id`	string	L’identificativo univoco della FAQ.
`question`	string	La domanda del cliente a cui questa voce risponde.
`answer`	string	La risposta fornita dal bot AI.
`category`	string \| null	Etichetta di categoria facoltativa a formato libero.
`tags`	string[]	Etichette facoltative per organizzare le FAQ.
`is_active`	boolean	Indica se al bot è consentito utilizzare questa FAQ. Il valore predefinito è `true`.
`is_global`	boolean	Contrassegna la FAQ come non legata a una specifica campagna o ad un Agente. Non rende la FAQ applicabile ovunque: una FAQ viene utilizzata solo dalle campagne e dagli Agenti a cui è collegata. Il valore predefinito è `false`.
`usage_count`	integer	Quante volte questa FAQ è stata utilizzata nelle risposte dell’AI.
`order_index`	integer	Posizione di visualizzazione di questa FAQ all’interno della sua campagna.
`campaign_ids`	string[]	ID delle campagne a cui questa FAQ è collegata.
`created_at`	string \| null	Timestamp ISO 8601 di quando la FAQ è stata creata.
`updated_at`	string \| null	Timestamp ISO 8601 dell’ultima modifica.

I campi che puoi impostare sono: question, answer, is_active, is_global, category, tags e order_index. La piattaforma gestisce tutto il resto (dati di ricerca, conteggi di utilizzo, timestamp); qualsiasi altro campo nel corpo della richiesta viene ignorato.

Elenca FAQ

GET /faqs

Restituisce le FAQ nel tuo account, dalla più recente alla meno recente. Filtra facoltativamente per una singola campagna o per stato attivo.

Parametri di query

Parametro	Obbligatorio	Descrizione
`campaign_id`	No	Restituisce solo le FAQ collegate a questa campagna.
`is_active`	No	Restituisce solo le FAQ con questo stato attivo (`true` o `false`). Questo filtro viene applicato per pagina, quindi una pagina potrebbe contenere meno elementi di `limit`.
`limit`	No	Numero massimo di FAQ per pagina. Predefinito `50`, massimo `100`.
`cursor`	No	Un ID FAQ da cui continuare. Passa il valore `next_cursor` dalla pagina precedente.

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

Risposta

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

Quando next_cursor è null, non ci sono più risultati.

Ottieni una FAQ

GET /faqs/{faqId}

Restituisce una singola FAQ tramite il suo 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"]

Risposta

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

Crea una FAQ

POST /faqs

Crea una nuova FAQ e la collega a una campagna.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna a cui collegare la nuova FAQ.
`question`	Sì	La domanda del cliente a cui risponde questa voce.
`answer`	Sì	La risposta che il bot dovrebbe fornire.
`is_active`	No	Indica se il bot può utilizzare questa FAQ. Il valore predefinito è `true`.
`is_global`	No	Indica se la FAQ si applica a tutte le campagne. Il valore predefinito è `false`.
`category`	No	Un’etichetta di categoria a formato libero.
`tags`	No	Una matrice di etichette.
`order_index`	No	Posizione di visualizzazione all’interno della campagna. Il valore predefinito è `0`.

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

Risposta

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

Aggiorna una FAQ

PUT /faqs/{faqId}

Aggiorna parzialmente una FAQ. Vengono modificati solo i campi scrivibili forniti; tutto il resto mantiene il suo valore attuale. La modifica di question o answer aggiorna automaticamente i dati di ricerca della FAQ in background.

Se invii question o answer, devono essere stringhe non vuote. L’invio di campi scrivibili non riconosciuti restituisce 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()

Risposta

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

Elimina una FAQ

DELETE /faqs/{faqId}

Elimina definitivamente una FAQ. Passa facoltativamente campaign_id come parametro di query per rimuovere la FAQ anche dall’elenco FAQ di quella campagna.

Parametri di query

Parametro	Obbligatorio	Descrizione
`campaign_id`	No	Rimuovi anche le FAQ dall’elenco FAQ di questa campagna.

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

Risposta

{
  "success": true
}

Eliminazione in blocco delle FAQ

POST /faqs/bulk-delete

Elimina fino a 500 FAQ in un’unica richiesta. Quando viene fornito campaign_id, le FAQ eliminate vengono rimosse anche dall’elenco FAQ di quella campagna.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`faq_ids`	Sì	Un array non vuoto di ID FAQ da eliminare (max 500).
`campaign_id`	No	Rimuovi anche le FAQ eliminate dall’elenco FAQ di questa campagna.

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

Risposta

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

FAQ sulle importazioni

POST /faqs/import

Importa in blocco fino a 500 FAQ e le collega tutte a una campagna. Gli elementi il cui question corrisponde a una FAQ esistente nella tua libreria (senza distinzione tra maiuscole e minuscole) aggiornano tale FAQ invece di crearne un duplicato.

Suggerimento sulle prestazioni: la ricerca di duplicati analizza l’intera libreria di FAQ, pertanto librerie molto grandi rallentano le importazioni. È preferibile effettuare poche importazioni di grandi dimensioni piuttosto che molte piccole.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna a cui sono collegate tutte le FAQ importate.
`faqs`	Sì	Un array non vuoto di elementi FAQ (max 500). Ogni elemento deve avere `question` e `answer` non vuoti; può includere anche `is_active`, `is_global`, `category`, `tags` e `order_index`.

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

Risposta

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

faq_ids sono gli ID delle FAQ create o aggiornate, nell’ordine in cui sono stati forniti.

Riordina FAQ

POST /faqs/reorder

Imposta l’ordine di visualizzazione delle FAQ di una campagna. Fornisci l’elenco completo degli ID delle FAQ nell’ordine desiderato; la posizione di ogni FAQ viene aggiornata per corrispondere al suo posto nell’array.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna le cui FAQ devono essere riordinate.
`ordered_faq_ids`	Sì	Un array non vuoto di tutti gli ID delle FAQ della campagna nell’ordine di visualizzazione desiderato (massimo 500).

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

Risposta

{
  "success": true
}

Se la campagna o uno qualsiasi degli ID delle FAQ non viene trovato nel tuo account, la richiesta restituisce 404 One or more FAQs were not found.

Collega una FAQ a una campagna

POST /faqs/{faqId}/link

Collega una FAQ esistente a una campagna aggiuntiva. Una FAQ può essere condivisa da un numero qualsiasi di campagne, quindi la stessa risposta deve essere gestita una sola volta.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna a cui collegare la FAQ.

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

Risposta

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

Scollegare una FAQ da una campagna

POST /faqs/{faqId}/unlink

Rimuove una FAQ da una campagna senza eliminare la FAQ stessa. La FAQ rimane nella tua libreria e resta collegata a qualsiasi altra campagna.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna da cui rimuovere la FAQ.

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

Risposta

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

Ricostruire i dati di ricerca di una FAQ

POST /faqs/{faqId}/rebuild-embeddings

Accoda una ricostruzione dei dati utilizzati dal bot AI per trovare questa FAQ (i suoi dati di ricerca semantica e per parole chiave). Questo è utile se una FAQ non viene rilevata nelle risposte come previsto. La ricostruzione viene eseguita in background e solitamente si completa in pochi secondi; la FAQ potrebbe essere temporaneamente esclusa dalle risposte dell’AI mentre viene ricostruita.

Questo endpoint restituisce 202 Accepted perché il lavoro continua dopo l’invio della risposta. Lo status è sempre "processing": recupera nuovamente la FAQ in seguito se hai bisogno di confermare il completamento.

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

Risposta

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

Gestione delle FAQ assistita dall’IA

Gli endpoint sottostanti vanno oltre il semplice CRUD: richiamano gli stessi strumenti di assistenza IA utilizzati dall’editor delle FAQ della dashboard, per trovare duplicati, generare voci da un documento e abbinare le FAQ a task aperti relativi a lacune di conoscenza. I corpi delle richieste in questo set utilizzano nomi di campo camelCase (campaignId, taskId, sourceIds…), che corrispondono alle strutture di richiesta dell’app, anziché i snake_case utilizzati altrove in questa pagina: copia gli esempi sottostanti invece di indovinare il nome di un campo.

Crea una copia di una FAQ specifica per una campagna

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

Crea una nuova FAQ che è una copia di una esistente, limitata a una singola campagna, e ricollega tale campagna alla nuova copia invece che all’originale. Utilizza questa funzione quando desideri personalizzare una risposta per una campagna senza modificarla ovunque venga utilizzata la FAQ originale. La FAQ originale rimane al suo posto: perde solo il collegamento con questa campagna.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaign_id`	Sì	La campagna a cui limitare la nuova copia e da cui ricollegare la FAQ originale.
`question`	Sì	La domanda per la nuova copia specifica per la campagna.
`answer`	Sì	La risposta per la nuova copia specifica per la campagna.

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

Risposta — 201 Created

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

Trova FAQ quasi duplicate

POST /faqs/dedupe

Avvia un processo in background che scansiona la tua libreria di FAQ alla ricerca di voci quasi duplicate o sovrapposte e le unisce o le rimuove dove il sistema è sicuro. Utile dopo un’importazione massiva o dopo diversi cicli di FAQ generate dall’IA che hanno lasciato sovrapposizioni nella libreria. È possibile eseguire solo un processo di deduplicazione alla volta per account: avviare un secondo processo mentre uno è ancora in esecuzione restituisce 409.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`sourceIds`	No	Array di ID di origine della knowledge base a cui limitare la deduplicazione. Ometti per scansionare l’intera libreria di FAQ.

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

Risposta — 202 Accepted

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

Il processo viene eseguito in background e solitamente richiede alcuni minuti su una libreria di grandi dimensioni. Non esiste un endpoint di stato separato: recupera nuovamente GET /faqs dopo una breve attesa per vedere cosa è cambiato. Quando hai finito di esaminare il risultato, chiama l’endpoint di chiusura sottostante per cancellarlo.

Chiudi un risultato di controllo duplicati

POST /faqs/dedupe/dismiss

Cancella il processo di deduplicazione terminato in modo che smetta di apparire come risultato attivo. Idempotente: è sicuro chiamarlo anche se non c’è nulla da chiudere. Restituisce 409 se il processo è ancora queued o processing (non è possibile chiudere un’esecuzione che non è ancora terminata).

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

Risposta

{ "success": true }

Genera FAQ dai documenti caricati

POST /faqs/generate-from-documents

Legge uno o più documenti già presenti nell’archivio file del tuo account e fa sì che l’IA rediga le FAQ dal loro contenuto, confrontando le bozze con la tua libreria esistente in modo da riutilizzare o aggiornare le voci invece di creare duplicati. I risultati non vengono scritti immediatamente: vengono archiviati come un set di modifiche in sospeso nella campagna affinché tu possa esaminarli, per poi essere applicati (o eliminati) con Applica le modifiche alle FAQ revisionate qui sotto. Questa operazione comporta un costo in crediti, poiché si tratta di un passaggio di generazione tramite IA sul testo del documento.

Questo endpoint non gestisce il file: storagePath deve puntare a un file già presente nella tua cartella di caricamento (users/{your user id}/uploads/), seguendo la stessa convenzione di Importa un documento caricato nell’API della Knowledge Base.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaignId`	Sì	La campagna per cui vengono proposte le FAQ generate.
`uploadedFiles`	Sì	Array non vuoto di file da leggere, ciascuno `{ storagePath, fileName, mimeType }`. `storagePath` deve iniziare con `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()

Risposta — 202 Accepted

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

faqCount è il numero totale di modifiche proposte in attesa di revisione; reusedCount, modifiedCount e newCount suddividono tale numero in FAQ che corrispondono a una voce esistente invariata, quelle che l’IA propone di modificare e quelle nuove di zecca. I file caricati vengono eliminati dall’archivio una volta terminata l’elaborazione, indipendentemente dal fatto che abbia avuto successo o meno.

Applica le modifiche alle FAQ revisionate

POST /faqs/apply-optimization

Applica (o elimina) un set in sospeso di modifiche alle FAQ proposte dall’IA — il tipo prodotto da Genera FAQ dai documenti qui sopra, o dalla revisione dell’ottimizzazione delle FAQ della dashboard. Scegli esattamente quali modifiche proposte accettare; tutto ciò che non viene menzionato rimane invariato (una modifica omessa non viene mai trattata come un rifiuto che elimina qualcosa).

Campi della richiesta

Campo	Obbligatorio	Descrizione
`campaignId`	Uno dei due	La campagna le cui modifiche alle FAQ in sospeso vengono applicate.
`agentId`	Uno dei due	L’Agente IA le cui modifiche alle FAQ in sospeso vengono applicate, su un account nativo dell’agente. Fornisci esattamente uno tra `campaignId` / `agentId`, mai entrambi.
`acceptedChanges`	Sì	Array delle modifiche che accetti, ciascuna `{ action, faq_id?, faq_ref_path?, question?, answer?, edit_scope? }`. `action` è uno tra `keep`, `remove`, `add_from_library`, `create_new`, `modify`. Invia un array vuoto per eliminare il set in sospeso senza applicare nulla.

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

Risposta

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

faq_count è il conteggio totale delle FAQ collegate della campagna (o dell’Agente) dopo l’applicazione. Se non c’era alcun set di modifiche in sospeso da applicare, la risposta è { "success": true, "message": "No pending FAQ changes to apply" }.

Trova FAQ simili a un task

POST /faqs/similar-for-task

Classifica la tua libreria di FAQ in base alla rilevanza rispetto alla domanda di un task di lacuna di conoscenza (knowledge-gap) — la stessa ricerca alla base del selettore “Usa una FAQ esistente” della dashboard. Sola lettura. taskId deve puntare a un task di tipo faq_update.

Questo endpoint risponde sempre 200, anche in caso di errore previsto come un task sconosciuto: controlla success nel corpo della risposta invece dello stato HTTP.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`taskId`	Sì	Il task `faq_update` per cui trovare corrispondenze.
`limit`	No	Numero massimo di corrispondenze da restituire. Il valore predefinito è 20, con un limite massimo di 50.

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

Risposta

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

Le corrispondenze sono ordinate per similarity (corrispondenza semantica quando disponibile, altrimenti sovrapposizione di parole chiave), dalla migliore alla peggiore. In caso di errore lieve, la struttura è { "success": false, "error": "...", "error_code": 404 }: error_code rispecchia quello che sarebbe normalmente lo stato HTTP.

Risolvere un task con una FAQ esistente

POST /faqs/resolve-task

Risolve un task di lacuna informativa collegandolo a una FAQ già esistente (invece di scriverne una nuova), invia la risposta di tale FAQ al contatto che ha generato la lacuna e contrassegna il task come completato. Utilizza questa funzione dopo che Trova FAQ simili a un task ha individuato una FAQ esistente che copre già la domanda.

Come l’endpoint precedente, questo risponde sempre 200: controlla success nel corpo della risposta.

Campi della richiesta

Campo	Obbligatorio	Descrizione
`taskId`	Sì	Il task `faq_update` da risolvere.
`faqId`	Sì	La FAQ esistente da collegare e inviare come risposta.

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

Risposta

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

follow_up_status indica cosa è successo al follow-up del contatto: published (inviato immediatamente), queued (l’IA stava già rispondendo a quel contatto, quindi verrà inviato in seguito), skipped_no_contact (il task non ha un contatto collegato) o skipped_no_campaign (nessuna campagna attraverso cui inviarlo).

FAQ errori API

Gli endpoint delle FAQ restituiscono il formato di errore standard:

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

Stato	Quando si verifica su un endpoint FAQ
`400`	Un campo obbligatorio manca o non è valido (ad esempio un `question` vuoto, un `campaign_id` mancante o più di 500 elementi in una richiesta massiva).
`404`	La FAQ o la campagna non è stata trovata: o non esiste o appartiene a un altro account.
`409`	`POST /faqs/dedupe` è stato chiamato mentre un processo di deduplicazione è già `queued`/`processing`, oppure `POST /faqs/dedupe/dismiss` è stato chiamato mentre il processo non è ancora terminato.

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

POST /faqs/similar-for-task e POST /faqs/resolve-task sono le due eccezioni in questa pagina: rispondono 200 anche per un errore previsto (task sconosciuto, tipo di task errato) e inseriscono lo stato reale nel campo error_code del corpo della risposta: vedi i singoli endpoint sopra.

Correlati

API Campagne — le campagne a cui sono collegate le tue FAQ.
API Knowledge Base — importa automaticamente siti web e documenti nelle FAQ e raggruppa le FAQ in gruppi di conoscenza riutilizzabili.
Accesso API — genera la tua chiave API.
Autenticazione — tutti i modi per trasmettere la tua chiave.

API FAQ #

L’oggetto FAQ #

Elenca FAQ #

Ottieni una FAQ #

Crea una FAQ #

Aggiorna una FAQ #

Elimina una FAQ #

Eliminazione in blocco delle FAQ #

FAQ sulle importazioni #

Riordina FAQ #

Collega una FAQ a una campagna #

Scollegare una FAQ da una campagna #

Ricostruire i dati di ricerca di una FAQ #

Gestione delle FAQ assistita dall’IA #

Crea una copia di una FAQ specifica per una campagna #

Trova FAQ quasi duplicate #

Chiudi un risultato di controllo duplicati #

Genera FAQ dai documenti caricati #

Applica le modifiche alle FAQ revisionate #

Trova FAQ simili a un task #

Risolvere un task con una FAQ esistente #

FAQ errori API #

Correlati #

API FAQ

L’oggetto FAQ

Elenca FAQ

Ottieni una FAQ

Crea una FAQ

Aggiorna una FAQ

Elimina una FAQ

Eliminazione in blocco delle FAQ

FAQ sulle importazioni

Riordina FAQ

Collega una FAQ a una campagna

Scollegare una FAQ da una campagna

Ricostruire i dati di ricerca di una FAQ

Gestione delle FAQ assistita dall’IA

Crea una copia di una FAQ specifica per una campagna

Trova FAQ quasi duplicate

Chiudi un risultato di controllo duplicati

Genera FAQ dai documenti caricati

Applica le modifiche alle FAQ revisionate

Trova FAQ simili a un task

Risolvere un task con una FAQ esistente

FAQ errori API

Correlati