Conversazione

Parla con l'AI nella tua app o nel tuo sistema di assistenza clienti, con supporto alle risposte in streaming e al passaggio a un operatore, alla chiusura e alla valutazione della conversazione.

POST /v1/chat

{
  "message": "有没有 400 美元以内的潜水表？",
  "conversation_id": null,
  "user": {"id": "u_123", "name": "李四", "email": "li@example.com", "ip": "85.214.132.117", "language": null},
  "stream": false
}

Se non passi conversation_id viene creata una nuova conversazione: l'ID viene restituito nella risposta e va poi incluso nei messaggi successivi.
user è il tuo server a comunicarcelo direttamente (chi chiama con l'API Key è considerato affidabile); solo se presente possiamo cercare gli ordini.
Lingua di risposta predefinita: se passi user.language (ad es. de, zh-CN, pt-BR) usiamo quella; altrimenti passa user.ip e la deduciamo dalla posizione; se non passi nulla, usiamo la lingua predefinita del pannello. Se il cliente chiede di cambiare lingua durante la conversazione, vale la sua richiesta.
Con stream: false la risposta è {"conversation_id", "message", "status", "products"}; message uguale a null significa che la conversazione è in gestione a un operatore e il messaggio è già stato passato a una persona.
Con stream: true viene restituito un flusso SSE; gli eventi sono nella tabella qui sotto.

Evento `type`	Contenuto
`user_message`	Messaggio del cliente salvato
`delta`	Un segmento di testo `text` della risposta, da concatenare in ordine
`products`	Schede prodotto trovate dall'AI
`language`	Il cliente ha chiesto di cambiare lingua di risposta; `language` è il nuovo codice lingua
`status`	Cambio di stato della conversazione (ad es. passaggio a operatore)
`replace`	Sostituisce l'intera risposta ricevuta con `text` (in caso di errore, con un messaggio di riserva)
`queued_for_human`	La conversazione è in gestione a un operatore, nessuna risposta AI
`done`	Messaggio finale salvato e stato della conversazione
`error`	Errore

Altre API

Metodo	Percorso	Descrizione
GET	`/v1/conversations`	Elenco conversazioni, `?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	La conversazione e tutti i messaggi
POST	`/v1/conversations/{id}/messages`	Il tuo sistema di assistenza risponde come operatore: `{"content", "agent_name"}`; la conversazione passa subito allo stato operatore
POST	`/v1/conversations/{id}/status`	Azione lato assistenza: `{"status": "ai"}` la restituisce all'AI, `{"status": "closed"}` chiude la conversazione
POST	`/v1/conversations/{id}/close`	Il cliente chiude la conversazione nella tua App; se è già chiusa rispondiamo comunque con successo
POST	`/v1/conversations/{id}/rating`	Valutazione del cliente dopo la chiusura: `{"rating": "good" \| "bad", "comment": "facoltativo, massimo 500 caratteri"}`, modificabile

Stati della conversazione: ai (risposta AI), pending_human (in attesa di operatore), human (in gestione a un operatore), closed (chiusa).

Nella conversazione trovi anche: closed_by, cioè chi l'ha chiusa (customer il cliente, agent l'operatore, ai l'AI dopo che il cliente ha indicato di non avere altri problemi), e rating / rating_comment / rated_at per la valutazione del cliente.

Chiusura della conversazione: nella parte superiore della finestra web c'è il pulsante «Chiudi conversazione» (con doppia conferma); nel mini-programma WeChat anche l'invio di «结束» da parte del cliente chiude la conversazione; se in «Impostazioni robot» è attiva l'opzione «L'AI chiude automaticamente la conversazione», quando il cliente dichiara esplicitamente di non avere altri problemi l'AI saluta e chiude la conversazione. Dopo la chiusura, nella finestra web chiediamo al cliente di valutare soddisfatto / non soddisfatto e di lasciare un commento; su WeChat gli chiediamo di rispondere 1 o 2; i messaggi successivi del cliente aprono una nuova conversazione.

Assegnazione dopo il passaggio a operatore: in «Impostazioni robot» scegli il metodo di assegnazione: all'operatore con meno conversazioni attive (predefinito), a rotazione, oppure operatore che prende in carico da solo. L'assegnazione automatica va solo agli operatori che hanno selezionato «Online» e hanno la pagina del pannello aperta; ognuno ha un limite di conversazioni simultanee (si imposta nella pagina «Team»); se l'operatore assegnato non risponde entro il tempo stabilito (2 minuti per impostazione predefinita), la conversazione viene riassegnata. Nella conversazione, assigned_member_id è l'operatore assegnato, assigned_at è l'ora di assegnazione e handoff_at è l'ora del passaggio a operatore. Quando tutti sono al completo, i clienti si mettono in coda e nella finestra web vedono quante persone ci sono davanti.

Orari di servizio e messaggi: se in «Impostazioni robot» attivi gli orari di servizio, fuori orario il passaggio a operatore non mette il cliente in coda: nella finestra web compare un modulo per lasciare un messaggio (nome, email o telefono, problema), mentre nelle conversazioni WeChat e tramite API aperta è l'AI a invitare il cliente a lasciare un messaggio; lo stesso vale negli orari di servizio quando nessun operatore è online. Il messaggio genera un ticket; quando l'operatore risponde, se la conversazione originale non è ancora chiusa la risposta viene inviata lì, e se il cliente ha lasciato un'email viene inviata anche un'email a nome del negozio. Se il passaggio a operatore è impostato solo su «Invia al mio sistema», gli orari di servizio non vengono considerati.

Questa pagina ti è stata utile?

Ultimo aggiornamento: 31 ottobre 2026