Handoff Configuration

Human Handoff permet à votre AI Agent de transférer automatiquement les conversations à des opérateurs humains lorsqu’il détecte des situations nécessitant une touche personnelle. Le handoff est piloté par l’IA — l’IA évalue en continu la conversation par rapport à des consignes configurables et déclenche un handoff lorsque c’est approprié, sans aucune intervention manuelle.

Comment fonctionne le handoff automatique :

1. Pendant une conversation, l’IA évalue chaque message par rapport à vos generic guidelines (p. ex. frustration de l’utilisateur, manque de connaissances) et aux custom guidelines que vous définissez
2. Lorsqu’une consigne se déclenche, l’IA affiche au visiteur un message de confirmation lui demandant s’il souhaite parler à un humain
3. Si le visiteur confirme, la conversation est transférée à un opérateur humain, avec un résumé optionnel de la conversation jusqu’ici, généré par l’IA
4. Si des horaires de travail sont configurés et que la demande survient en dehors de ceux-ci, un message personnalisé est affiché à la place

Méthodes de handoff supplémentaires :

• Keyword triggers — Les visiteurs peuvent taper des phrases spécifiques (p. ex. “speak to human”, “agent”) pour demander directement un handoff
• Handoff manuel depuis le Dashboard — Les opérateurs peuvent prendre en charge n’importe quelle conversation depuis l’Inbox en changeant l’assigné de la conversation

Le Routage par sujet permet à l’IA d’attribuer un handoff à un coéquipier d’après sa description de routage. Chaque profil appartient à un seul utilisateur et est distinct des catégories de sujets dans Insights. Configurez les profils via routing_profiles dans la requête PUT. L’attribution et les destinataires des notifications par e-mail sont des paramètres distincts.

Get Handoff Configuration

Scope: 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()

Response 200 OK

La réponse contient plusieurs objets imbriqués :

settings — Configuration de base du handoff :

Field	Description
is_active boolean	Si le human handoff est activé
keywords array of strings	Mots-clés déclencheurs qui provoquent un handoff (p. ex. ["speak to human", "agent"])
ai_summary_active boolean	Envoyer à l’opérateur humain un résumé de la conversation généré par l’IA lors du handoff
topic_based_routing_active boolean	Si le routage par sujet vers des opérateurs spécifiques est activé (lecture seule, configuré via les profils de routage)
question_message string	Message affiché au visiteur lui demandant s’il souhaite être mis en relation avec un humain
confirmation_message string	Message affiché après que le visiteur a confirmé le handoff (max 500 caractères)
confirmation_outside_working_hours_message string	Message affiché lorsqu’un handoff est demandé en dehors des horaires de travail (max 500 caractères)
working_hours_active boolean	Restreindre le handoff aux horaires de travail uniquement
timezone string	Fuseau horaire des horaires de travail (p. ex. "Europe/London")
send_email_notification boolean	Envoyer des notifications par e-mail aux opérateurs lors d’un handoff
emails array of strings	Adresses e-mail à notifier

availability — Planning des horaires de travail (tableau de créneaux) :

Field	Description
id integer	ID du créneau de disponibilité
day_span string	Jour ou plage de jours (p. ex. "monday", "monday-friday")
start_time string	Heure de début au format "HH:MM"
end_time string	Heure de fin au format "HH:MM"

generic_guidelines — Règles prédéfinies de déclenchement du handoff (tableau) :

Field	Description
name string	Type de consigne : "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Description des cas où cette consigne se déclenche
is_active boolean	Si cette consigne est activée

custom_guidelines — Règles de déclenchement du handoff définies par l’utilisateur (tableau) :

Field	Description
id integer	ID de la consigne
name string	Nom de la consigne personnalisée (max 100 caractères)
description string	Quand cette consigne doit déclencher un handoff (max 2000 caractères)
is_active boolean	Si cette consigne est activée

routing_profiles — Le routage par sujet dirige les handoffs vers les bons opérateurs selon le sujet de la conversation.

Lorsque l’IA lance un handoff, elle peut sélectionner un coéquipier parmi les profils de routage actifs. La conversation est attribuée à cet utilisateur si la sélection est valide ; sinon, elle reste sans attribution. D’autres déclencheurs de handoff peuvent également la laisser sans attribution. Les notifications par e-mail utilisent settings.send_email_notification et settings.emails indépendamment du choix de routage.

Exemple : Donnez à un coéquipier de l’équipe finance la description de routage “Billing and invoice questions” et à un ingénieur “Technical support”. Pour une question sur une facture, l’IA peut attribuer le handoff au coéquipier de l’équipe finance. La liste configurée des destinataires des e-mails ne change pas du fait de cette attribution.

Configurez les profils sous Actions & MCPs > Transfert à un humain > Modifier l’action > Routage par sujet, ou via la requête PUT.

Field	Description
user_id integer	ID utilisateur du coéquipier ; l’utilisateur doit avoir accès à cet AI Agent
routing_description string	Conversations que ce coéquipier doit traiter (max 150 caractères ; ne doit pas être vide lorsque le profil est actif)
is_active boolean	Si ce profil de routage est activé
email, first_name, last_name strings	Informations utilisateur renvoyées par GET ; non requises dans PUT

Update Handoff Configuration

Scope: write_all

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

Attention

PUT remplace toute la configuration du handoff de manière atomique. Incluez settings, availability, generic_guidelines et custom_guidelines. Incluez routing_profiles pour conserver le routage : si vous l’omettez, sa valeur par défaut est une liste vide et les profils existants sont supprimés. Pour effectuer des modifications incrémentales, faites d’abord un GET de la configuration actuelle, modifiez les champs dont vous avez besoin, puis effectuez un PUT de l’objet complet. Chaque profil de routage utilise user_id, routing_description et 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()

Response 200 OK — Retourne la configuration du handoff mise à jour.

---