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 Topic-based Routing est une fonctionnalité avancée qui achemine les handoffs vers des opérateurs spécifiques selon le sujet de la conversation. Chaque profil de routage définit un sujet, une description des cas où il s’applique et une liste d’opérateurs qui traitent ce sujet. Lorsqu’un handoff se déclenche, l’IA fait correspondre la conversation au profil de routage le plus pertinent et notifie les opérateurs assignés. Configurez les profils de routage via le tableau routing_profiles dans la requête PUT.

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.

Lorsqu’un handoff se déclenche, l’IA évalue la conversation par rapport à tous les profils de routage actifs et la fait correspondre au sujet le plus pertinent. Les opérateurs listés dans ce profil sont alors notifiés. Si aucun profil de routage ne correspond, le comportement de notification par défaut (la liste d’e-mails dans settings.emails) est utilisé.

Exemple : Vous avez un profil de routage “Billing” assigné à votre équipe finance et un profil “Technical Support” assigné aux ingénieurs. Lorsqu’un client pose une question sur une facture et déclenche un handoff, l’IA fait correspondre la conversation à “Billing” et notifie uniquement l’équipe finance — pas les ingénieurs.

Configurez les profils de routage dans le Dashboard sous Handoff > Topic-based Routing, ou via le tableau routing_profiles dans la requête PUT.

Field	Description
id integer	ID du profil de routage
name string	Nom du sujet (p. ex. “Billing”, “Technical Support”) (max 100 caractères)
description string	Quand ce profil doit correspondre — décrivez les types de conversations à acheminer vers ces opérateurs (max 2000 caractères)
is_active boolean	Si ce profil de routage est activé
user_ids array of integers	IDs des opérateurs à notifier lorsque ce profil correspond

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. Vous devez inclure toutes les sections (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) dans le corps de la requête. Omettre une section ou fournir des données partielles entraînera des erreurs de validation. 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.

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.

---