Configurazione del passaggio

Il passaggio a un operatore consente all’agente AI di trasferire automaticamente le conversazioni a operatori umani quando rileva situazioni che richiedono un intervento personale. Il passaggio è guidato dall’AI: l’AI valuta continuamente la conversazione rispetto a linee guida configurabili e avvia il passaggio quando opportuno, senza interventi manuali.

Come funziona il passaggio automatico:

1. Durante una conversazione, l’AI valuta ogni messaggio rispetto alle linee guida generiche, per esempio frustrazione dell’utente o mancanza di conoscenza, e alle linee guida personalizzate che definisci
2. Quando si attiva una linea guida, l’AI mostra al visitatore un messaggio di conferma chiedendo se desidera parlare con una persona
3. Se il visitatore conferma, la conversazione viene trasferita a un operatore umano, facoltativamente con un riepilogo della conversazione generato dall’AI
4. Se è configurato un orario di lavoro e la richiesta arriva fuori orario, viene invece mostrato un messaggio personalizzato

Altri metodi di passaggio:

• Attivazione tramite parole chiave: i visitatori possono digitare frasi specifiche, per esempio “parla con una persona” o “operatore”, per richiedere direttamente il passaggio
• Passaggio manuale dalla dashboard: gli operatori possono prendere in carico qualsiasi conversazione dalla Posta in arrivo cambiandone l’assegnatario

L’Instradamento per argomento permette all’AI di assegnare un passaggio a un collega in base alla sua descrizione di instradamento. Ogni profilo appartiene a un utente ed è distinto dalle categorie di argomenti in Approfondimenti. Configura i profili tramite routing_profiles nella richiesta PUT. Assegnazione e destinatari delle notifiche email sono impostazioni separate.

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.

• Valida un dataset di test. Verifica un piccolo dataset fornito rispetto al formato supportato senza eseguire l’agente AI.

Recuperare la configurazione del passaggio

Ambito: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Risposta 200 OK

La risposta contiene diversi oggetti annidati:

settings: configurazione principale del passaggio:

Campo	Descrizione
is_active booleano	Indica se il passaggio a un operatore è attivo
keywords array di stringhe	Parole chiave che richiedono un passaggio, per esempio ["speak to human", "agent"]
ai_summary_active booleano	Invia all’operatore umano un riepilogo della conversazione generato dall’AI al momento del passaggio
topic_based_routing_active booleano	Indica se è attivo l’instradamento per argomento verso operatori specifici (sola lettura, configurato tramite i profili di instradamento)
question_message stringa	Messaggio mostrato al visitatore per chiedere se desidera parlare con una persona
confirmation_message stringa	Messaggio mostrato dopo la conferma del passaggio da parte del visitatore (massimo 500 caratteri)
confirmation_outside_working_hours_message stringa	Messaggio mostrato quando il passaggio viene richiesto fuori dall’orario di lavoro (massimo 500 caratteri)
working_hours_active booleano	Limita il passaggio al solo orario di lavoro
timezone stringa	Fuso orario dell’orario di lavoro, per esempio "Europe/London"
send_email_notification booleano	Invia notifiche email agli operatori al passaggio
emails array di stringhe	Indirizzi email da avvisare

availability: calendario dell’orario di lavoro (array di intervalli):

Campo	Descrizione
id intero	ID dell’intervallo di disponibilità
day_span stringa	Giorno o intervallo di giorni, per esempio "monday", "monday-friday"
start_time stringa	Ora di inizio in formato "HH:MM"
end_time stringa	Ora di fine in formato "HH:MM"

generic_guidelines: regole predefinite di attivazione del passaggio (array):

Campo	Descrizione
name stringa	Tipo di linea guida: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description stringa	Descrizione di quando si attiva questa linea guida
is_active booleano	Indica se la linea guida è attiva

custom_guidelines: regole di attivazione del passaggio definite dall’utente (array):

Campo	Descrizione
id intero	ID della linea guida
name stringa	Nome della linea guida personalizzata (massimo 100 caratteri)
description stringa	Quando questa linea guida deve attivare il passaggio (massimo 2000 caratteri)
is_active booleano	Indica se la linea guida è attiva

routing_profiles: l’instradamento per argomento indirizza i passaggi agli operatori appropriati in base al contenuto della conversazione.

Quando l’AI avvia un passaggio, può selezionare un collega dai profili di instradamento attivi. La conversazione viene assegnata a quell’utente se la scelta è valida; altrimenti resta non assegnata. Anche altri meccanismi di passaggio possono lasciarla non assegnata. Le notifiche email usano settings.send_email_notification e settings.emails indipendentemente dalla scelta di instradamento.

Esempio: assegna a un collega della contabilità la descrizione “Domande su fatturazione e fatture” e a un tecnico “Assistenza tecnica”. Per una domanda su una fattura, l’AI può assegnare il passaggio al collega della contabilità. L’elenco configurato dei destinatari email non cambia in seguito all’assegnazione.

Configura i profili in Azioni e MCP > Passaggio a un operatore > Modifica azione > Instradamento per argomento, oppure tramite la richiesta PUT.

Campo	Descrizione
user_id intero	ID utente del collega; l’utente deve avere accesso a questo agente AI
routing_description stringa	Conversazioni che il collega deve gestire (massimo 150 caratteri; non può essere vuota quando il profilo è attivo)
is_active booleano	Indica se il profilo di instradamento è attivo
email, first_name, last_name stringhe	Dettagli dell’utente restituiti da GET; non richiesti in PUT

Aggiornare la configurazione del passaggio

Ambito: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

Attenzione

PUT sostituisce atomicamente l’intera configurazione del passaggio. Includi settings, availability, generic_guidelines e custom_guidelines. Includi routing_profiles per mantenere l’instradamento: ometterlo equivale a un elenco vuoto e rimuove i profili esistenti. Per modifiche incrementali, recupera prima la configurazione corrente con GET, modifica i campi necessari e invia nuovamente l’oggetto completo con PUT. Ogni profilo di instradamento usa user_id, routing_description e is_active.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Risposta 200 OK: restituisce la configurazione aggiornata del passaggio.

---