Chat

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 chiavi dei metadati. Verifica come i nomi di campo forniti diventano chiavi di variabili, inclusi nomi duplicati ed errori per chiavi riservate. Non esamina i valori o i permessi specifici dell’account.

Chat

L’endpoint Chat in tempo reale invia il messaggio di un visitatore all’agente AI e restituisce la risposta dell’AI in un unico scambio. È l’endpoint da usare per creare un’interfaccia di chat personalizzata basata su Quickchat AI.

Si distingue dagli altri endpoint per due aspetti: si trova in app.quickchat.ai/chat, fuori dai percorsi base /v1/api/ e /v1/api_core/, e legge scenario_id dal corpo della richiesta anziché dal token. Usa la stessa autenticazione tramite token Bearer del resto dell’API.

Nota

Invia ogni richiesta a https://app.quickchat.ai/chat. Lo scenario_id nel corpo deve corrispondere all’agente AI a cui è associato il token Bearer.

Inviare un messaggio

POST https://app.quickchat.ai/chat

Corpo della richiesta

Parametro	Descrizione
scenario_id stringa, obbligatorio	ID dell’agente AI. Deve corrispondere allo scenario_id associato al token Bearer
text stringa, obbligatorio	Messaggio di input dell’utente
conv_id stringa	ID della conversazione. Omettilo nella prima richiesta per iniziare una nuova conversazione, poi passa il conv_id restituito nelle richieste successive per continuarla
client_metadata oggetto	Coppie chiave-valore personalizzate, consigliamo al massimo 5 chiavi, associate a ogni messaggio. Vengono mostrate come colonne di dati nell’esportazione delle conversazioni dalla Posta in arrivo

Una richiesta senza conv_id avvia una nuova conversazione e il conv_id generato viene restituito nella risposta. Salva quel conv_id e invialo nelle richieste successive per mantenere il contesto della conversazione tra più interazioni dell’utente.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Risposta 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Campo	Descrizione
conv_id stringa	Identificatore della conversazione. Viene sempre restituito. Reinseriscilo nel campo conv_id del corpo per continuare la conversazione
reply stringa	Risposta dell’agente AI. Può contenere HTML, per esempio interruzioni di riga <br>
ord_number intero	Numero progressivo del messaggio nella conversazione
src intero	Indicatore interno della fonte. I client API possono ignorare questo campo

Per continuare una conversazione esistente, passa nuovamente il conv_id ricevuto:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Metadati del client

L’endpoint Chat accetta il parametro facoltativo client_metadata: attributi personalizzati assegnati a ogni nuovo messaggio e mostrati come colonne di dati nell’esportazione delle conversazioni dalla Posta in arrivo. Puoi associare gli stessi attributi tramite il widget. Consigliamo di inviare al massimo 5 chiavi alla volta, per esempio {"userId": 12, "website": "mywebsite.com"}. È una raccomandazione, non un limite imposto dall’API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Filtrare la base di conoscenza per tag

Puoi aggiungere tag agli articoli della base di conoscenza e usarli per limitare gli articoli a cui l’AI attinge, così risponde usando solo un sottoinsieme della base di conoscenza. Questo filtro è attualmente supportato solo tramite API.

Per filtrare per tag, aggiungi una chiave kb_topic a client_metadata. La chiave kb_topic deve essere presente in ogni richiesta della conversazione, inclusa quella iniziale. Il valore può cambiare tra una richiesta e l’altra, ma la chiave deve essere presente per tutta la conversazione affinché il filtro venga applicato.

Nell’esempio seguente, tutti gli articoli con il tag your-topic oppure senza alcun tag sono inclusi tra le conoscenze candidate per la risposta.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Errori

L’endpoint Chat restituisce un messaggio di errore in testo semplice con un codice di stato HTTP appropriato.

Stato	Descrizione	Azione
400	scenario_id mancante o nessuna credenziale fornita	Includi scenario_id nel corpo e un header valido Authorization: Bearer <API_TOKEN>
400	conv_id non valido (Conversation conv_id <id> is not valid.)	Ometti conv_id per avviare una nuova conversazione oppure passa un conv_id restituito da una risposta precedente
401	Credenziali non valide (Unauthorized.)	Verifica che il token Bearer o la chiave API sia valido per questo scenario_id
404	scenario_id sconosciuto (No implementation found for scenario_id <id>)	Verifica lo scenario_id e che il token Bearer sia associato a esso
500	Errore interno del server	Un problema da parte nostra. Contatta l’assistenza
503	Servizio non disponibile	I server sono temporaneamente sovraccarichi o in manutenzione. Se il problema persiste, contatta l’assistenza