Panoramica

Quickchat AI offre un’API REST per accedere programmaticamente alla configurazione dell’agente AI, alla base di conoscenza, alle conversazioni, alle azioni AI e ad altro ancora.

Verifiche facoltative degli esempi

• Confronta i metodi di distribuzione. Confronta i canali dichiarati, l’accesso al sito e le funzionalità richieste con le opzioni di configurazione di Quickchat AI. Non esamina il sito o l’account.

• Verifica una connessione MCP di esempio. Inizializza ed elenca gli strumenti soltanto sull’endpoint della documentazione Cloudflare o di Microsoft Learn. Non esegue accessi né strumenti.

Autenticazione

Tutti gli endpoint API usano l’autenticazione tramite token Bearer. Includi il token API nell’header Authorization di ogni richiesta:

Authorization: Bearer <API_TOKEN>

I token si creano nella dashboard Quickchat in App esterne > API. Ogni token è un JWT che contiene il tuo scenario_id, quindi non serve un ulteriore header identificativo.

• Validità del token: 52 settimane dalla creazione
• I token possono essere revocati in qualsiasi momento dalla dashboard
• Ogni token è limitato a un singolo agente AI (scenario)
• La creazione dei token richiede il piano Business o superiore; nei piani inferiori l’opzione è disabilitata e l’endpoint restituisce 402 Payment Required

Nota

L’endpoint Chat in tempo reale (POST https://app.quickchat.ai/chat) accetta lo stesso token Bearer del resto dell’API, ma si trova fuori dal percorso base /v1/api/ e richiede scenario_id nel corpo della richiesta. Consulta la pagina Chat per il riferimento completo.

Ambiti dei token

I token API vengono creati con uno di due ambiti:

Ambito	Livello di accesso	Descrizione
read_all	Sola lettura	Può leggere tutte le risorse, ma non crearle, aggiornarle o eliminarle
write_all	Lettura e scrittura	Accesso completo a tutti gli endpoint, incluse le operazioni di scrittura

• L’ambito viene assegnato al token quando lo crei nella dashboard in App esterne > API
• L’ambito write_all include automaticamente tutti i permessi di read_all
• L’uso di un token read_all su un endpoint di scrittura restituisce 403 con "Insufficient token scope. Required: write_all"

Consiglio

Usa token read_all per monitoraggio, analisi e integrazioni di sola lettura. Usa token write_all solo quando l’integrazione deve creare o modificare risorse.

Ambiti richiesti per gruppo di endpoint:

Gruppo di endpoint	Operazioni di lettura	Operazioni di scrittura
Impostazioni del chatbot	read_all	write_all
Impostazioni della base di conoscenza	read_all	write_all
Articoli	read_all	write_all
URL degli articoli per lingua	read_all	write_all
Tag	read_all	Nessuna
Caricamento file	Nessuna	write_all
Importazione di contenuti esterni	Nessuna	write_all
Base di conoscenza Intercom	read_all	write_all
Configurazione del widget	read_all	write_all
Conversazioni	read_all	Nessuna
Metadati delle conversazioni	read_all	write_all
Configurazione del passaggio	read_all	write_all
Valutazione della conversazione	read_all	write_all
Azioni AI	read_all	write_all

URL base

Gruppo di endpoint	URL base
Base di conoscenza, Azioni AI, Caricamento file, Importazione, Impostazioni del chatbot, Widget, Passaggio, Valutazione della conversazione	https://app.quickchat.ai/v1/api/
Conversazioni	https://app.quickchat.ai/v1/api_core/
Chat in tempo reale	https://app.quickchat.ai/chat

Limiti di frequenza

I limiti di frequenza si applicano per token e per endpoint.

Categoria	Limite	Si applica a
READ	120 richieste/min	GET e operazioni di elenco
WRITE	60 richieste/min	POST, PATCH, PUT, DELETE
HEAVY	20 richieste/min	Caricamenti di file, importazioni, estrazione di contenuti

Quando superi un limite di frequenza, l’API restituisce HTTP 429 Too Many Requests.

Webhook

Quickchat AI non invia webhook in uscita. Non è possibile iscriversi a un evento e ricevere una richiesta POST al proprio endpoint quando arriva un messaggio, una conversazione viene trasferita o viene chiusa.

Le alternative disponibili hanno scopi diversi:

• Le Azioni AI chiamano la tua API durante una conversazione. Le azioni API offrono le modalità Decide l’AI, Prima della prima risposta e Quando i metadati corrispondono. Le modalità automatiche tentano una chiamata per conversazione alle condizioni documentate; non sono iscrizioni a ogni messaggio o passaggio. Usale per attività come registrare un contatto o avvisare il tuo sistema quando sono disponibili i dati richiesti.
• Google Sheets aggiunge una riga quando viene eseguita la relativa azione. Non registra automaticamente ogni messaggio o passaggio.
• Il polling dell’API Conversazioni recupera le conversazioni salvate e i relativi eventi, inclusi messaggi ed eventuali indicatori di passaggio registrati. Rispetta la paginazione e il limite READ indicato sopra. Il polling introduce ritardo; confrontare lo stato tra interrogazioni può far perdere modifiche intermedie. Non presumere che offra uno storico completo di ogni passaggio o cambio di assegnazione.

L’accesso API richiede il piano Business; vedi Piani e limiti.

Paginazione

Gli endpoint di elenco supportano la paginazione tramite parametri della query:

Parametro	Descrizione
limit intero	Numero di elementi per pagina
offset intero	Numero di elementi da saltare

Le risposte paginate seguono questa struttura:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Gestione degli errori

Tutti gli errori vengono restituiti come JSON nel seguente formato:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Stato	Codice	Descrizione
400	BAD_REQUEST	Input non valido o campi obbligatori mancanti
401	PERMISSION_DENIED	Token non valido, scaduto o revocato
402	PAYMENT_REQUIRED	È richiesto un abbonamento attivo
403	PERMISSION_DENIED	Il token non ha l’ambito richiesto per questa operazione
404	NOT_FOUND	Risorsa non trovata
409	CONFLICT	Operazione in conflitto, per esempio una modifica simultanea
422	VALIDATION_ERROR	Il corpo della richiesta non supera la convalida dello schema
429	TOO_MANY_REQUESTS	Limite di frequenza superato
500	UNKNOWN	Errore interno del server
503	SERVICE_UNAVAILABLE	Indisponibilità temporanea

---