Articoli

Gli articoli sono gli elementi fondamentali della base di conoscenza. Crea, elenca, aggiorna ed elimina i contenuti che l'agente AI usa per rispondere alle domande.

Gli articoli sono gli elementi fondamentali della base di conoscenza dell’agente AI. Ogni articolo rappresenta una porzione di conoscenza: una pagina di assistenza, una FAQ, la descrizione di un prodotto o qualsiasi contenuto che l’AI dovrebbe conoscere.

Esistono tre tipi di articoli: Articoli (documenti completi con titolo e corpo), Paragrafi (brevi testi autonomi) e Articoli URL (creati automaticamente all’importazione di contenuti web). Puoi crearli manualmente tramite API, importarli da siti web con Importare contenuti esterni, caricare file con Caricamento file o sincronizzarli da Intercom.

Non è necessario riaddestrare. Ogni articolo creato, aggiornato o eliminato viene elaborato automaticamente in background e diventa effettivo appena l’elaborazione termina, in genere entro pochi secondi. Monitora il processo con il campo embed_state descritto sotto o con pending_embed_count in Recuperare le impostazioni della base di conoscenza.

Verifiche facoltative degli esempi

Visualizza un’anteprima della richiesta di un’azione API. Compila un modello di richiesta fornito con valori di esempio sintetici senza inviarlo. Ometti gli header con credenziali.
Visualizza un’anteprima delle corrispondenze JSONPath. Verifica percorsi radice, campi, indici di array e caratteri jolly rispetto al JSON fornito. Non esegue un’azione e non salva la memoria della conversazione.

Creare un articolo

Ambito: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/

Corpo della richiesta

Parametro	Descrizione
`content` stringa, obbligatorio	Contenuto dell’articolo
`type` stringa	`"Article"` (predefinito) o `"Paragraph"`
`title` stringa	Titolo dell’articolo

"Article": un documento completo della base di conoscenza con titolo e contenuto. Usalo per FAQ, articoli di assistenza e descrizioni di prodotti.
"Paragraph": un breve testo autonomo senza titolo. Usalo per fatti sintetici, risposte di una riga e dati di consultazione rapida.
"URL" (sola lettura): creato automaticamente quando importi contenuti da un sito web. Contiene il testo estratto dalla pagina e l’URL di origine. Non può essere impostato alla creazione.

Shell
Python

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()

Risposta 201 Created

{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "embed_state": "pending",
  "refresh_failure_reason": "",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}

Campo	Descrizione
`id` intero	ID numerico dell’articolo. È l’identificatore canonico usato in tutti i percorsi URL
`article_id` stringa	Identificatore stringa precedente. Può essere vuoto: usa invece `id`
`type` stringa	`"Article"`, `"Paragraph"` o `"URL"`
`title` stringa	Titolo dell’articolo
`description` stringa	Descrizione dell’articolo
`content` stringa	Contenuto dell’articolo
`deploy_state` stringa	`"draft"` o `"published"`: solo un’etichetta (vedi nota sotto)
`embed_state` stringa o null	Indica se l’articolo è disponibile: `"pending"`, `"embedding"`, `"embedded"` o `"failed"` (vedi nota sotto)
`state` stringa	Stato interno di elaborazione (vedi nota sotto)
`refresh_failure_reason` stringa	Motivo del fallimento dell’ultimo aggiornamento URL. Vuoto quando non è stato salvato un errore di aggiornamento classificato
`version` intero o null	Numero della versione corrente
`max_available_version` intero o null	Versione più alta disponibile
`url` stringa o null	URL di origine (per gli articoli di tipo URL)
`tags` array di stringhe	Tag associati
`created_timestamp` stringa	Data di creazione
`last_modified_timestamp` stringa	Data dell’ultima modifica
`downloaded_timestamp` stringa	Data del download
`last_updated_timestamp` stringa	Data dell’ultimo aggiornamento
`last_updated_from_external_source_timestamp` stringa o null	Ultimo aggiornamento dalla fonte esterna

Gli articoli hanno tre campi di stato. Solo uno indica se l’agente AI sta usando l’articolo:

embed_state: è quello rilevante. "pending" e "embedding" indicano che l’articolo è ancora in elaborazione; "embedded" indica che è disponibile e che l’agente AI lo usa; "failed" indica che l’elaborazione non è terminata e che l’articolo non viene usato. È il campo da interrogare dopo una scrittura.
deploy_state: "draft" o "published". È solo un’etichetta per la tua organizzazione: non influenza l’uso dell’articolo da parte dell’AI.
state: stato interno di recupero dei contenuti. La maggior parte degli utenti API può ignorarlo. Per un articolo URL, "refresh_failed" indica che l’ultimo aggiornamento non ha sostituito il contenuto salvato.
refresh_failure_reason: categoria stabile di un errore classificato nell’aggiornamento URL: "http_error", "soft_404", "off_domain_redirect", "auth_wall", "error_page", "empty_content" o "thin_content". Può essere vuoto quando l’estrazione fallisce prima che Quickchat possa classificare la pagina. L’ultimo contenuto salvato resta disponibile, a meno che anche embed_state sia fallito.

Elencare gli articoli

Ambito: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/

Parametri della query

Parametro	Descrizione
`limit` intero	Elementi per pagina
`offset` intero	Elementi da saltare
`types` stringa	Filtra per tipo: `Article`, `Paragraph`, `URL`
`tags` stringa	Filtra per tag
`url` stringa	Filtra per URL
`title` stringa	Filtra per titolo
`query` stringa	Cerca per contenuto

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()

Risposta 200 OK

{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "embed_state": "embedded",
      "refresh_failure_reason": "",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}

La risposta dell’elenco non include il campo content. Usa Recuperare un articolo per recuperare il contenuto completo di un articolo specifico.

Recuperare un articolo

Ambito: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Shell
Python

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Risposta 200 OK: restituisce l’oggetto articolo completo, con lo stesso schema della risposta di Creare un articolo, incluso il campo content.

Aggiornare un articolo

Ambito: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Corpo della richiesta

Parametro	Descrizione
`content` stringa	Contenuto aggiornato dell’articolo
`title` stringa	Titolo aggiornato
`tags` array di stringhe	Tag aggiornati
`save_mode` stringa	`"draft"` (predefinito) o `"publish"`

L’opzione save_mode: "draft" imposta solo il flag deploy_state: non impedisce all’AI di usare il contenuto. Un articolo in bozza viene elaborato e usato esattamente come uno pubblicato. Non usarla per preparare contenuti non ancora pronti: scrivi un articolo solo quando vuoi renderlo disponibile.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()

Risposta 200 OK: restituisce l’oggetto articolo aggiornato.

Eliminare gli articoli

Elimina uno o più articoli tramite ID.

Ambito: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/

Corpo della richiesta: array JSON degli ID degli articoli.

Shell
Python

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)

Risposta 200 OK

Cercare gli articoli

Cerca nel contenuto degli articoli tramite corrispondenza testuale.

Ambito: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search

Parametri della query

Parametro	Descrizione
`query` stringa, obbligatorio	Query di ricerca
`is_case_insensitive` booleano	Ricerca senza distinzione tra maiuscole e minuscole (predefinito: `true`)
`with_title_url_and_tags` booleano	Include titolo, URL e tag nella ricerca (predefinito: `true`)
`strict_search` booleano	Richiede una corrispondenza esatta (predefinito: `false`)
`num_of_display_articles` intero	Numero di articoli da visualizzare (predefinito: `5`)
`num_of_data_articles` intero	Numero di articoli in cui cercare (predefinito: `15`)

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()

Risposta 200 OK

{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}

Elencare i paragrafi

Elenca tutti gli articoli di tipo Paragraph. I paragrafi sono brevi testi autonomi senza titolo, a differenza degli articoli completi che hanno sia titolo sia corpo del contenuto.

Ambito: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs

Parametri della query

Parametro	Descrizione
`limit` intero	Elementi per pagina
`offset` intero	Elementi da saltare
`query` stringa	Filtra per contenuto

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()

Risposta 200 OK

{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}

Articoli

Verifiche facoltative degli esempi

Creare un articolo

Elencare gli articoli

Recuperare un articolo

Aggiornare un articolo

Eliminare gli articoli

Cercare gli articoli

Elencare i paragrafi

Per iniziare

Agente AI

Actions

Conversazioni

Channels

Il tuo sito web

Helpdesk e CRM

App di messaggistica

Account e fatturazione

Per iniziare

Configurazione

Knowledge Base

Conversazioni