Conversazioni

Quickchat AI registra e analizza automaticamente ogni conversazione dell’agente AI su tutti i canali: widget, Slack, WhatsApp, Telegram e altri. L’API Conversazioni offre accesso programmatico a questi dati per creare dashboard personalizzate, alimentare pipeline di analisi, attivare flussi nel CRM o integrarsi con gli strumenti di business intelligence esistenti.

Ogni conversazione include analisi AI: rilevamento del sentiment, classificazione degli argomenti, monitoraggio della risoluzione e segnalazione automatica delle conversazioni che potrebbero richiedere attenzione umana. Insieme allo storico completo dei messaggi, ai clic sui link monitorati e ai metadati personalizzati, hai tutto il necessario per capire come i visitatori interagiscono con l’agente AI.

I dati delle conversazioni sono distribuiti tra diversi endpoint:

• Elencare le conversazioni: informazioni di base, dettagli del visitatore, stato. Per dashboard, panoramiche e query filtrate
• Recuperare i dettagli di una conversazione: informazioni complete, inclusi unified_analysis (approfondimenti generati dall’AI) e client_metadata
• Recuperare gli eventi di una conversazione: storico completo dei messaggi, clic sui link monitorati e voci di log
• Recuperare/impostare i metadati: dati chiave-valore personalizzati che associ alle conversazioni (vedi Metadati delle conversazioni)

Elencare le conversazioni

Ambito: read_all

GET https://app.quickchat.ai/v1/api_core/conversations

Parametri della query

Parametro	Descrizione
limit intero	Elementi per pagina
offset intero	Elementi da saltare
query stringa	Cerca per numero progressivo, UUID o testo del messaggio
assignee_type stringa	"ai_assistant", "human_operator" o "unassigned"
source stringa	"widget", "slack", "telegram", "whatsapp", ecc.
resolution_status stringa	"open" o "resolved"
created_timestamp_start_date datetime	Filtra per data di creazione (inizio)
created_timestamp_end_date datetime	Filtra per data di creazione (fine)
last_message_at_start_date datetime	Filtra per data dell’ultimo messaggio (inizio)
last_message_at_end_date datetime	Filtra per data dell’ultimo messaggio (fine)
most_frequent_language stringa	Filtra per lingua rilevata
order stringa	"desc" (predefinito, dal più recente) o "asc" (dal meno recente). L’ordine crescente serve a procedere in avanti da una conversazione nota, quindi abbinalo a last_message_at_start_date

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "resolution_status": "open"},
)
data = response.json()

Risposta 200 OK

{
  "items": [
    {
      "id": "conv-uuid-1234",
      "ord": 42,
      "created_at": "2026-01-15T10:30:00Z",
      "last_message_at": "2026-01-15T10:35:00Z",
      "title": "Return policy question",
      "source": "widget",
      "terminated": false,
      "resolution_status": "open",
      "has_unread_messages": true,
      "supports_inbox_control": true,
      "last_message_content": "What is your return policy?",
      "most_frequent_language": "en",
      "assignee": {
        "type": "ai_assistant"
      },
      "visitor_name": "John",
      "visitor_email": "john@example.com",
      "visitor_phone_number": null,
      "visitor_label": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 42
}

Campo	Descrizione
id stringa	UUID della conversazione
ord intero	Numero progressivo della conversazione
created_at stringa	Timestamp di creazione della conversazione
last_message_at stringa	Timestamp del messaggio più recente
title stringa	Titolo della conversazione generato dall’AI
source stringa	Canale da cui è iniziata la conversazione, per esempio "widget", "slack", "whatsapp"
terminated booleano	Indica se la conversazione è terminata
resolution_status stringa	"open" o "resolved"
has_unread_messages booleano	Indica se ci sono messaggi non letti
supports_inbox_control booleano	Indica se la fonte della conversazione supporta il controllo dalla Posta in arrivo (assegnazione, passaggio)
last_message_content stringa	Contenuto dell’ultimo messaggio della conversazione
most_frequent_language stringa	Lingua rilevata più spesso nella conversazione
assignee oggetto	Assegnatario corrente (type: "ai_assistant", "human_operator" o "unassigned")
visitor_name stringa o null	Nome del visitatore (dal modulo pre-chat o dal profilo del canale)
visitor_email stringa o null	Indirizzo email del visitatore
visitor_phone_number stringa o null	Numero di telefono del visitatore
visitor_label stringa o null	Etichetta personalizzata assegnata al visitatore

Recuperare i dettagli di una conversazione

Ambito: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Risposta 200 OK

{
  "id": "conv-uuid-1234",
  "ord": 42,
  "created_at": "2026-01-15T10:30:00Z",
  "last_message_at": "2026-01-15T10:35:00Z",
  "title": "Return policy question",
  "source": "widget",
  "terminated": false,
  "resolution_status": "open",
  "has_unread_messages": true,
  "supports_inbox_control": true,
  "last_message_content": "What is your return policy?",
  "most_frequent_language": "en",
  "assignee": {
    "type": "ai_assistant"
  },
  "url": null,
  "client_metadata": {"userId": 12},
  "last_visitor_message_at": "2026-01-15T10:34:00Z",
  "unified_analysis": {
    "sentiment": "neutral",
    "resolution_status": "open",
    "topic": "Return policy",
    "is_flagged": false,
    "flag_reason": null
  },
  "visitor_name": "John",
  "visitor_email": "john@example.com",
  "visitor_phone_number": null,
  "visitor_label": null
}

La risposta di dettaglio include tutti i campi della risposta dell’elenco, più:

Campo	Descrizione
url stringa o null	URL della pagina in cui è iniziata la conversazione (solo widget)
client_metadata oggetto o null	Coppie chiave-valore personalizzate associate alla conversazione
last_visitor_message_at stringa	Timestamp dell’ultimo messaggio del visitatore
unified_analysis oggetto o null	Analisi della conversazione generata dall’AI (vedi sotto)

Campi di unified_analysis:

Campo	Descrizione
sentiment stringa	Sentiment della conversazione rilevato dall’AI, per esempio "positive", "neutral", "negative"
resolution_status stringa	Stato di risoluzione valutato dall’AI (può differire da resolution_status di livello superiore)
topic stringa	Argomento della conversazione rilevato dall’AI
is_flagged booleano	Indica se l’AI ha segnalato la conversazione per una revisione umana
flag_reason stringa o null	Motivo della segnalazione della conversazione

resolution_status e unified_analysis.resolution_status

Il campo resolution_status di livello superiore ("open" o "resolved") è lo stato canonico impostato manualmente o da regole di automazione.

Il valore unified_analysis.resolution_status viene calcolato dall’analisi AI e può essere diverso: per esempio l’AI potrebbe classificare una conversazione come risolta in base al contenuto anche se lo stato di livello superiore è ancora "open". Usa il campo di livello superiore per filtri e flussi di lavoro; usa unified_analysis per analisi e approfondimenti.

Recuperare gli eventi di una conversazione

Recupera tutti gli eventi di una conversazione: messaggi, link monitorati e log.

Ambito: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/

Parametri della query

Parametro	Descrizione
limit intero	Elementi per pagina
offset intero	Elementi da saltare

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 20},
)
data = response.json()

Risposta 200 OK

{
  "items": [
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-001",
        "ord": 1,
        "created_at": "2026-01-15T10:30:00Z",
        "content": "Hello! How can I help you today?",
        "author": "ai_assistant",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": true,
        "attachments": []
      }
    },
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-002",
        "ord": 2,
        "created_at": "2026-01-15T10:31:00Z",
        "content": "What is your return policy?",
        "author": "visitor",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": false,
        "attachments": []
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 2
}

Tipi di evento: message, tracked_link, log

Tipi di autore: ai_assistant, visitor, human_operator

Campo	Descrizione
type stringa	Tipo di evento: "message", "tracked_link" o "log"
data.id stringa	Identificatore univoco del messaggio
data.ord intero	Numero progressivo del messaggio
data.created_at stringa	Timestamp dell’evento
data.content stringa	Contenuto del messaggio
data.author stringa	"ai_assistant", "visitor" o "human_operator"
data.handoff_state stringa o null	Stato del passaggio, se pertinente
data.message_insights oggetto o null	Approfondimenti sul messaggio generati dall’AI
data.feedback oggetto o null	Feedback dell’utente sul messaggio
data.client_metadata oggetto o null	Metadati personalizzati associati al messaggio
data.sources_generated array	Articoli della base di conoscenza usati dall’AI per generare la risposta
data.is_welcome booleano	Indica se è un messaggio di benvenuto
data.attachments array	File allegati

---