Handoff Configuration

Human Handoff ermöglicht es Ihrem KI-Agenten, Konversationen automatisch an menschliche Operator zu übergeben, wenn er Situationen erkennt, die eine persönliche Note erfordern. Handoff ist KI-gesteuert — die KI bewertet die Konversation kontinuierlich anhand konfigurierbarer Richtlinien und löst einen Handoff aus, wenn es angemessen ist, ohne jeglichen manuellen Eingriff.

So funktioniert der automatische Handoff:

1. Während einer Konversation bewertet die KI jede Nachricht anhand Ihrer generischen Richtlinien (z. B. Frustration des Nutzers, fehlendes Wissen) und der von Ihnen definierten benutzerdefinierten Richtlinien
2. Wenn eine Richtlinie auslöst, zeigt die KI dem Besucher eine Bestätigungsnachricht und fragt, ob er mit einem Menschen sprechen möchte
3. Bestätigt der Besucher, wird die Konversation an einen menschlichen Operator übergeben, mit einer optionalen KI-generierten Zusammenfassung der bisherigen Konversation
4. Wenn Arbeitszeiten konfiguriert sind und die Anfrage außerhalb davon liegt, wird stattdessen eine benutzerdefinierte Nachricht angezeigt

Weitere Handoff-Methoden:

• Keyword-Trigger — Besucher können bestimmte Phrasen eingeben (z. B. “speak to human”, “agent”), um direkt einen Handoff anzufordern
• Manueller Handoff aus dem Dashboard — Operator können jede Konversation aus der Inbox übernehmen, indem sie die zuständige Person der Konversation ändern

Topic-based Routing ist eine erweiterte Funktion, die Handoffs basierend auf dem Konversationsthema an bestimmte Operator weiterleitet. Jedes Routing-Profil definiert ein Thema, eine Beschreibung, wann es zutrifft, und eine Liste von Operatorn, die dieses Thema bearbeiten. Wenn ein Handoff auslöst, ordnet die KI die Konversation dem relevantesten Routing-Profil zu und benachrichtigt die zugewiesenen Operator. Konfigurieren Sie Routing-Profile über das Array routing_profiles in der PUT-Anfrage.

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

Antwort 200 OK

Die Antwort enthält mehrere verschachtelte Objekte:

settings — Kern-Handoff-Konfiguration:

Field	Description
is_active boolean	Ob Human Handoff aktiviert ist
keywords array of strings	Trigger-Keywords, die einen Handoff auslösen (z. B. ["speak to human", "agent"])
ai_summary_active boolean	Bei einem Handoff eine KI-generierte Konversationszusammenfassung an den menschlichen Operator senden
topic_based_routing_active boolean	Ob themenbasiertes Routing an bestimmte Operator aktiviert ist (read-only, konfiguriert über Routing-Profile)
question_message string	Nachricht, die dem Besucher angezeigt wird und fragt, ob er mit einem Menschen verbunden werden möchte
confirmation_message string	Nachricht, die angezeigt wird, nachdem der Besucher den Handoff bestätigt hat (max. 500 Zeichen)
confirmation_outside_working_hours_message string	Nachricht, die angezeigt wird, wenn ein Handoff außerhalb der Arbeitszeiten angefordert wird (max. 500 Zeichen)
working_hours_active boolean	Handoff nur auf Arbeitszeiten beschränken
timezone string	Zeitzone für die Arbeitszeiten (z. B. "Europe/London")
send_email_notification boolean	Bei einem Handoff E-Mail-Benachrichtigungen an Operator senden
emails array of strings	Zu benachrichtigende E-Mail-Adressen

availability — Arbeitszeitenplan (Array von Slots):

Field	Description
id integer	ID des Verfügbarkeits-Slots
day_span string	Tag oder Tagesspanne (z. B. "monday", "monday-friday")
start_time string	Startzeit im Format "HH:MM"
end_time string	Endzeit im Format "HH:MM"

generic_guidelines — Vordefinierte Handoff-Trigger-Regeln (Array):

Field	Description
name string	Richtlinientyp: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Beschreibung, wann diese Richtlinie auslöst
is_active boolean	Ob diese Richtlinie aktiviert ist

custom_guidelines — Benutzerdefinierte Handoff-Trigger-Regeln (Array):

Field	Description
id integer	Richtlinien-ID
name string	Name der benutzerdefinierten Richtlinie (max. 100 Zeichen)
description string	Wann diese Richtlinie einen Handoff auslösen soll (max. 2000 Zeichen)
is_active boolean	Ob diese Richtlinie aktiviert ist

routing_profiles — Themenbasiertes Routing leitet Handoffs an die richtigen Operator weiter, basierend darauf, worum es in der Konversation geht.

Wenn ein Handoff auslöst, bewertet die KI die Konversation anhand aller aktiven Routing-Profile und ordnet sie dem relevantesten Thema zu. Die in diesem Profil aufgeführten Operator werden dann benachrichtigt. Wenn kein Routing-Profil passt, wird das Standard-Benachrichtigungsverhalten (E-Mail-Liste in settings.emails) verwendet.

Beispiel: Sie haben ein “Billing”-Routing-Profil, das Ihrem Finanzteam zugewiesen ist, und ein “Technical Support”-Profil, das Ingenieuren zugewiesen ist. Wenn ein Kunde nach einer Rechnung fragt und einen Handoff auslöst, ordnet die KI die Konversation “Billing” zu und benachrichtigt nur das Finanzteam — nicht die Ingenieure.

Konfigurieren Sie Routing-Profile im Dashboard unter Handoff > Topic-based Routing oder über das Array routing_profiles in der PUT-Anfrage.

Field	Description
id integer	ID des Routing-Profils
name string	Themenname (z. B. “Billing”, “Technical Support”) (max. 100 Zeichen)
description string	Wann dieses Profil passen soll — beschreiben Sie die Arten von Konversationen, die zu diesen Operatorn geleitet werden sollen (max. 2000 Zeichen)
is_active boolean	Ob dieses Routing-Profil aktiviert ist
user_ids array of integers	IDs der Operator, die benachrichtigt werden sollen, wenn dieses Profil passt

Update Handoff Configuration

Scope: write_all

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

Achtung

PUT ersetzt die gesamte Handoff-Konfiguration atomar. Sie müssen alle Abschnitte (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) im Request-Body angeben. Das Weglassen eines Abschnitts oder die Angabe unvollständiger Daten führt zu Validierungsfehlern. Um inkrementelle Änderungen vorzunehmen, holen Sie zuerst die aktuelle Konfiguration per GET, ändern Sie die benötigten Felder und senden Sie das vollständige Objekt per PUT zurück.

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

Antwort 200 OK — Gibt die aktualisierte Handoff-Konfiguration zurück.

---