Metadati delle conversazioni

I metadati delle conversazioni permettono di associare dati personalizzati chiave-valore alle conversazioni, creando un collegamento tra i tuoi sistemi e l’agente AI. I metadati attraversano l’intero flusso di lavoro Quickchat:

• Invio tramite API: usa questi endpoint per associare programmaticamente metadati a qualsiasi conversazione, per esempio dal CRM, dall’helpdesk o dal backend
• Invio tramite widget/embed: passa i metadati come parametri di inizializzazione al caricamento del widget oppure inseriscili dinamicamente durante una conversazione attiva tramite l’SDK JavaScript
• Visibili nella dashboard: i metadati personalizzati compaiono nei dettagli della conversazione nella Posta in arrivo. Le chiavi interne vengono filtrate, mentre i contatti raccolti e la memoria delle azioni hanno una presentazione specifica
• Inclusi nelle esportazioni: i metadati vengono inclusi quando esporti le conversazioni dalla dashboard, rendendoli disponibili per analisi offline
• Usati nelle azioni AI: i valori dei metadati possono essere inseriti direttamente come segnaposto {{metadata_<key>}} nelle Azioni AI. Vedi Variabili delle azioni AI per il riferimento completo dei segnaposto disponibili
• Disponibili all’agente AI quando consentito: il contesto del modello usa un sottoinsieme filtrato dei metadati. Salvare una chiave non garantisce che il modello la riceva o la menzioni

Usa i metadati per riferimenti ai clienti, contesto dell’account, analisi e input delle azioni. Memorizzazione, visualizzazione nella Posta in arrivo, sostituzione nelle azioni e contesto del modello sono usi distinti degli stessi dati.

Se nella dashboard è configurato uno schema JSON, i metadati vengono convalidati rispetto a quello schema.

Verifiche facoltative degli esempi

• 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. Questo controllo non esamina valori o permessi specifici dell’account.

• Verifica le condizioni di esecuzione di un’azione. Valuta le condizioni sui metadati di esempio forniti senza eseguire un’azione.

In un browser compatibile, questi controlli sono disponibili anche come strumenti del sito. I link aprono i moduli standard.

Contesto del modello e autorizzazione

Nei canali controllati dal visitatore, come Widget ed Embed del sito web, il contesto del modello ammette le chiavi di contatto del visitatore (visitor_name, visitor_email, visitor_phone_number) e le chiavi idonee richiamate o raccolte dalle azioni attive. I valori interni e riservati vengono filtrati; si applicano anche configurazione e limiti di dimensione. Le altre integrazioni hanno regole di contesto specifiche del canale. Una chiave personalizzata customer_tier o customer_id non diventa automaticamente visibile al modello solo perché l’hai inviata.

Un’azione può sostituire {{metadata_<key>}} quando costruisce la richiesta senza chiedere all’AI di generare quel valore. Questo non rende segreti i normali metadati: un valore idoneo può entrare separatamente nel contesto del modello o comparire nella risposta di un’azione. Non salvare chiavi API o password nei metadati personalizzati.

I metadati forniti dal browser non dimostrano identità o autorizzazione. Il servizio ricevente deve autenticare e autorizzare l’accesso ai record privati; un ID cliente o un livello di piano inviato dal browser non basta. Per la tua configurazione, verifica sia la richiesta risultante dell’azione sia la risposta dell’agente.

Recuperare i metadati

Ambito: read_all

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

Shell

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

Python

import requests

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

Risposta 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Impostare i metadati

Crea o aggiorna i metadati di una conversazione.

Ambito: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Corpo della richiesta

Parametro	Descrizione
metadata oggetto, obbligatorio	Metadati chiave-valore da salvare

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

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

Risposta 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---