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

Themenbasiertes Routing ermöglicht der AI, eine Übergabe einem einzelnen Teammitglied anhand dessen Routing-Beschreibung zuzuweisen. Jedes Profil gehört zu einem einzelnen Nutzer und ist unabhängig von den Themenkategorien in Insights. Konfigurieren Sie Profile über routing_profiles in der PUT-Anfrage. Zuweisung und Empfänger von E-Mail-Benachrichtigungen sind getrennte Einstellungen.

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 die AI eine Übergabe einleitet, kann sie ein Teammitglied aus den aktiven Routing-Profilen auswählen. Bei gültiger Auswahl wird die Konversation diesem Nutzer zugewiesen; andernfalls bleibt sie ohne Zuweisung. Auch bei anderen Übergabeauslösern kann sie ohne Zuweisung bleiben. Für E-Mail-Benachrichtigungen gelten settings.send_email_notification und settings.emails unabhängig von der Routing-Auswahl.

Beispiel: Geben Sie einem Teammitglied aus dem Finanzbereich die Routing-Beschreibung “Billing and invoice questions” und einem Ingenieur “Technical support”. Bei einer Rechnungsfrage kann die AI die Übergabe dem Teammitglied aus dem Finanzbereich zuweisen. Die konfigurierte E-Mail-Empfängerliste ändert sich durch diese Zuweisung nicht.

Konfigurieren Sie Profile unter Aktionen & MCPs > Menschliche Übergabe > Aktion bearbeiten > Themenbasiertes Routing oder über die PUT-Anfrage.

Field	Description
user_id integer	Nutzer-ID des Teammitglieds; der Nutzer muss Zugriff auf diesen AI Agent haben
routing_description string	Konversationen, die dieses Teammitglied bearbeiten soll (max. 150 Zeichen; darf bei aktivem Profil nicht leer sein)
is_active boolean	Ob dieses Routing-Profil aktiviert ist
email, first_name, last_name strings	Von GET zurückgegebene Nutzerdaten; für PUT nicht erforderlich

Update Handoff Configuration

Scope: write_all

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

Achtung

PUT ersetzt die gesamte Handoff-Konfiguration atomar. Geben Sie settings, availability, generic_guidelines und custom_guidelines an. Geben Sie auch routing_profiles an, um das Routing beizubehalten: Wird es weggelassen, wird standardmäßig eine leere Liste verwendet und die vorhandenen Profile werden entfernt. 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. Jedes Routing-Profil verwendet user_id, routing_description und 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()

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

---