Human Handoff

Die Human Handoff-Funktion ermöglicht es Agent-Entwickler:innen, externe Kundendienstsysteme zu integrieren, um Supportanfragen von Nutzer:innen gezielt an menschliche Mitarbeitende weiterzuleiten. Aktuell werden Kundendienstsysteme wie Intercom, Livedesk, Livechat, Zoho Sales IQ und Sobot unterstützt; darüber hinaus lassen sich über Webhook oder Custom Helpdesk (eigenes Kundenservicesystem) weitere Human Support-Systeme flexibel anbinden.

So aktivieren Sie Human Handoff

In den Agent-Einstellungen unter Human Handoff auf die Schaltfläche „Aktivieren“ klicken, um Human Handoff zu aktivieren.
Das gewünschte Kundendienstsystem auswählen – unterstützt werden Intercom, Webhook, Livedesk, Custom Helpdesk (eigenes Kundenservicesystem) usw.
Die Authentifizierungskonfiguration des ausgewählten Drittanbieter-Kundendienstsystems abschließen, um eine erfolgreiche Nachrichtenübermittlung sicherzustellen (für Custom Helpdesk ist keine Authentifizierungskonfiguration erforderlich, siehe „Custom Helpdesk“ konfigurieren).
Die Einstellungen rund um Human Handoff entsprechend den Anforderungen Ihres Unternehmens anpassen.
Im Agent-Konversationsfenster eine Human Handoff-Anfrage starten, um die Funktion zu nutzen.

Human-Service-Modi

Die Human Handoff-Funktion unterstützt drei Modi: Externe Plattform → Help-Desk, Help-Desk → Help-Desk und Custom Helpdesk (eigenes Kundenservicesystem).

Modus	Woher startet der:die Nutzer:in die Konversation	Wer betreut die Nutzer:innen	Rolle von GPTBots	Geeignetes Szenario
Externe Plattform → Help-Desk	Beliebiger vom Agent-Integrationsmodul unterstützter Kanal (WhatsApp / iframe / Widget / Share / LINE usw.)	Das ausgewählte Drittanbieter-Help-Desk-System (z. B. Intercom)	Übergibt die Nutzer:innen-Konversation an das Help-Desk-System und leitet Nachrichten in beide Richtungen weiter	Sie nutzen bereits eine Help-Desk-Plattform wie Intercom oder Livedesk und möchten Nutzer:innen aus mehreren Kanälen zentral dort betreuen lassen
Help-Desk → Help-Desk	Die eigenen Kanäle des Help-Desk-Systems (z. B. die Intercom-Plattform)	Dasselbe Help-Desk-System	Fungiert als KI-Bot innerhalb der Plattform und übergibt bei Human Handoff an die Servicemitarbeitenden der Plattform	Nutzer:innen chatten ohnehin bereits innerhalb der Help-Desk-Plattform
Custom Helpdesk (eigenes Kundenservicesystem)	Die eigenen Kanäle Ihres selbst entwickelten Kundenservicesystems	Die Servicemitarbeitenden Ihres selbst entwickelten Kundenservicesystems	Übernimmt nur KI-Gehirn + Konversationsarchivierung; bei Human Handoff wird lediglich ein Signal über die API zurückgegeben, keine Weiterleitung	Sie verfügen bereits über ein selbst entwickeltes Kundenservicesystem; Nutzer:innen-Kanäle und Servicemitarbeitende befinden sich auf Ihrer Seite

Am Beispiel des Help-Desk-Systems Intercom unterscheiden sich die ersten beiden Modi wie folgt:

flowchart TD
    A["Human Handoff Feature"] --> B["Andere zur Help-Desk-Plattform"] & C["Help-Desk zu Help-Desk"]
    B --> D["Nutzer:in startet Konversation über Agent-integrierte Kanäle"]
    D --> E["Plattformen wie WhatsApp/Iframe/Widget/Share/LINE"] & G["Intercom-Plattform"]
    E --> F["Intercom Help-Desk-System empfängt und bearbeitet"]
    G --> Q["Kann von Intercom-System nicht empfangen/verarbeitet werden"]
    C --> H["Nutzer:in startet Anfrage über Help-Desk-Plattform"]
    H --> I["Intercom-Plattform"] & K["Nicht-Intercom-Plattform"]
    I --> J["Intercom Help-Desk-System empfängt und bearbeitet"]
    K --> L["Kann von Intercom-System nicht empfangen/verarbeitet werden"]
     A:::Peach
     B:::Sky
     C:::Aqua
     D:::Sky
     E:::Sky
     G:::Sky
     F:::Sky
     Q:::Sky
     H:::Aqua
     I:::Aqua
     K:::Aqua
     J:::Aqua
     L:::Aqua
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Peach stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D

Der grundlegende Unterschied des Custom Helpdesk-Modus zu den beiden anderen Modi: GPTBots „übergibt“ die Konversation nicht mehr für Sie. Nutzer:innen-Kanäle und Servicemitarbeitende befinden sich ohnehin bereits in Ihrem Kundenservicesystem. GPTBots beantwortet lediglich die Fragen und teilt Ihnen bei Bedarf über die Antwort der Send Message API mit, dass an einen Menschen übergeben werden soll. Die anschließende Zuweisung an Servicemitarbeitende und die Nachrichtenzustellung übernimmt vollständig Ihr System.

Authentifizierung „Andere zur Help-Desk-Plattform“

Nutzer:innen können von jeder durch das Agent-Integrationsmodul unterstützten Plattform aus Human-Service-Anfragen stellen. Das ausgewählte Help-Desk-System empfängt und bearbeitet diese Anfragen. Zum Beispiel:

Wenn Nutzer:innen auf Plattformen wie WhatsApp, Iframe, Widget, Share oder LINE eine Konversation starten und Human Service anfordern, empfängt und bearbeitet das Intercom Help-Desk-System die Anfrage.
Wird die Anfrage direkt auf der Intercom-Plattform gestellt, kann das Intercom-System diese im „Andere zur Help-Desk“-Modus nicht empfangen oder verarbeiten.

Intercom-Authentifizierung

Vollständige Anleitung zur Bereitstellung von Human Handoff über Intercom:

App erstellen
Registrieren Sie sich zunächst bei Intercom und folgen Sie der Anleitung zur Erstellung eines Workspaces. Rufen Sie über „Account Avatar – Einstellungen – APPS & INTEGRATIONEN“ die Seite Developer Hub auf. Klicken Sie im Developer Hub auf „Neue App“, um eine Anwendung zu erstellen. Ist die App bereits vorhanden, wählen Sie diese aus, um die Einstellungen aufzurufen.
Access Token abrufen und in GPTBots eintragen

Wählen Sie den Menüpunkt „Authentifizierung“ und kopieren Sie das Access Token.
Tragen Sie das Token in das Eingabefeld „Access Token“ unter „Human Handoff – Intercom-Authentifizierung“ ein.
Tragen Sie die Human Handoff-Nachrichtenempfangsadresse in Intercom ein
Kopieren Sie die URL unter „GPTBots Nachrichtenempfangsadresse“ und fügen Sie diese in Intercom unter „Endpoint URL“ im Webhooks-Menü ein.
Abonnieren Sie wichtige Business-Events in Intercom
Im Bereich „Themen“ des Webhooks-Menüs wählen Sie mit „Thema auswählen ...“ die folgenden 4 Events aus und speichern Sie die Konfiguration:
- conversation.admin.closed
- conversation.admin.replied
- conversation.admin.snoozed
- conversation.read

Damit ist die Intercom-Konfiguration abgeschlossen. Sie können nun im Agent-Konversationsfenster Human Handoff anfordern. Nach erfolgreicher Initiierung erhält das Intercom Help-Desk-System die Nachricht des Nutzers. Sobald Sie antworten, ist die Human Handoff-Verbindung offiziell hergestellt.

Livedesk-Authentifizierung

Melden Sie sich in der Livedesk Developer Console an.
Navigieren Sie zum Livedesk-Produkt, wählen Sie „Projekteinstellungen – API-Verwaltung – API Key“ und kopieren Sie API Key und API Secret.
Tragen Sie das Projekt-Secret in das Feld „Access Token“ unter „GPTBots – Human Handoff – Andere zu Livedesk“ ein und speichern Sie die Konfiguration.

Webhook-Authentifizierung

Vollständige Anleitung zur Bereitstellung von Human Handoff-Services via Webhook:

Entwickelnde müssen zunächst einen Webhook-Empfangsservice auf ihrem Server bereitstellen, der die folgenden drei Schnittstellen bietet, um Human-Service-Anfragen vom Agent zu empfangen und Nachrichten zu verarbeiten. Details siehe Human Handoff Service – Webhook.
- Session erstellen: /conversation/establish
- Chat: /chat
- Session schließen: /conversation/close
Anschließend müssen URL, Benutzername und Passwort des Webhook-Empfangsservices in der Agent-Konfiguration für Human Service hinterlegt werden, damit der Agent Nachrichten an den Webhook-Service senden kann.

URL-Adresse: Erforderlich, um Nachrichten von Nutzer:innen auf Agent-Seite zu empfangen
Benutzername: Optional, abhängig vom Webhook-Service
Passwort: Optional, abhängig vom Webhook-Service
Zum Schluss die API-Funktion unter „Agent-Integration-API“ aktivieren und die GPTBots-Nachrichtenempfangsadresse als Webhook-Sende-URL eintragen, damit Human-Antworten im Agent-Chatfenster angezeigt werden. Details siehe Human Handoff Service – Webhook.

Die Webhook-Authentifizierung ist damit abgeschlossen. Sie können jetzt Human Service im Agent-Chatfenster anfordern. Nach erfolgreicher Initiierung empfängt der Webhook-Service die Nachricht des Nutzers.

Unterschied zwischen Webhook und Custom Helpdesk: Im Webhook-Modus erstellt GPTBots weiterhin aktiv eine Human Handoff-Session und pusht Nutzer:innen-Nachrichten an Ihre /chat-Schnittstelle; Antworten der Servicemitarbeitenden werden über die API an das Agent-Konversationsfenster zurückgegeben, und Mechanismen wie Timeout-Wartezeit und Session-Timeout sind wirksam. Dieser Modus eignet sich für das Szenario „Nutzer:innen chatten über GPTBots-Kanäle (Widget / WhatsApp usw.), die Servicemitarbeitenden arbeiten in Ihrem eigenen System“. Im Custom Helpdesk-Modus pusht GPTBots keinerlei Nachrichten aktiv, sondern gibt lediglich das Human Handoff-Signal in der API-Antwort zurück. Dieser Modus eignet sich für das Szenario „Nutzer:innen und Servicemitarbeitende befinden sich beide in Ihrem eigenen System“.

Livechat-Authentifizierung

Entwickelnde müssen ein eigenes Livechat-Konto erstellen, um die organization_id zu erhalten. Livechat-Konto erstellen
App erstellen, Blocks hinzufügen, App-Autorisierung wählen und als Server-App festlegen. Auf dieser Seite erhalten Sie die clientId. App erstellen

Fügen Sie Blocks hinzu, wählen Sie APP Webhook und tragen Sie die GPTBots-Nachrichtenempfangsadresse als Webhook-URL ein.
Fügen Sie Blocks hinzu, wählen Sie Chat Webhook und tragen Sie die GPTBots-Nachrichtenempfangsadresse als Webhook-URL ein. Wählen Sie incoming_event und chat_deactivated.
Klicken Sie auf Private Installation, um zur Installationsseite zu gelangen, und installieren Sie die App.
Geben Sie organization_id und liveChatClientId aus den vorherigen Schritten in die Maske ein und bestätigen Sie mit OK, um die Konfiguration abzuschließen. Die Livechat-Konfiguration ist nun abgeschlossen.

Sobot-Authentifizierung

Bitte folgen Sie der Anleitung zur Sobot-Integration, um den Human Service einzurichten. Sobot Human Service ist nur im Sobot-Widget verfügbar.

Zoho Sales IQ-Authentifizierung

Loggen Sie sich in Ihr Zoho-Konto ein und öffnen Sie die Zoho API Console.

Hinweis: Falls Ihr Konto nicht in der US-Region liegt, müssen Sie die Domain wechseln. Details siehe: Voraussetzung – Org OAuth Token generieren.
Tragen Sie die aktuelle Service-Domain in Homepage-URL ein und geben Sie unter Authorized Redirect URIs die Service-Domain + /api/console/bot/zoho/salesiq/org/redirect an. Klicken Sie auf ERSTELLEN. Nach erfolgreicher Erstellung werden Client ID und Client Secret angezeigt. Kopieren Sie diese für die spätere Konfiguration.
Loggen Sie sich bei GPTBots ein, tragen Sie die Client ID und das Client Secret aus der Zoho API Console ein, geben Sie den Screen Name an und wählen Sie die Server-Region.
- Client ID und Client Secret: Erforderlich, siehe Vorbereitung.
- Screen Name: Erforderlich, entnehmen Sie diesen der URL nach dem Domainnamen (z. B. https://salesiq.zoho.com/gptbos/mychats/000000000000003 → Screen Name: gptbots).
- Server-Region: Wählen Sie die Region Ihres Zoho-Kontos.
  Nach dem Ausfüllen auf Autorisieren klicken.
Nach Klick auf Autorisieren erscheint ein Status-Popup. Bitte auf Akzeptieren klicken.
Public Key: Optional. Wenn Sie „Secure your webhook“ aktivieren, muss dieser eingetragen werden. Andernfalls nicht erforderlich. Für die Webhook-Konfiguration siehe: Zoho Sales IQ Integration.
Wählen Sie eine passende Zoho-Servicegruppe aus. Nach Auswahl übernimmt diese Gruppe die Konversation.

Hinweis: In diesem Szenario kann der Bot keine von Zoho gesendeten Dateien empfangen. Dateien von Zoho werden nicht angezeigt.

Human Handoff konfigurieren

Human Handoff

Service-Status: Zeigt die Verfügbarkeit des Drittanbieter-Human Handoff-Systems an

Nicht konfiguriert: Wenn noch keine Authentifizierungsdaten hinterlegt wurden
Service verfügbar: Wenn Authentifizierungsdaten erfolgreich hinterlegt und geprüft wurden
Service nicht verfügbar: Wenn hinterlegte Authentifizierungsdaten fehlerhaft/ungültig sind

Trigger-Zeitpunkt: Unterstützt individuelle Trigger-Beschreibungen, damit das LLM korrekt erkennt, wann Human Handoff ausgelöst werden soll

Timeout-Mechanismus
Timeout-Wartezeit: Standard 60 s. Maximale Wartezeit nach Anforderung von Human Handoff. Nach Ablauf wird der:die Nutzer:in gefragt, ob die Anfrage beendet oder weiter gewartet werden soll.
Session-Timeout: Standard 180 s. Nach der letzten Nachricht des Human Agents wird die Session automatisch beendet, wenn innerhalb von N Sekunden keine Nutzer:innen-Antwort erfolgt.
Human Handoff-Zeiträume

Bis zu 10 Human-Service-Zeiträume individuell festlegen:

Wöchentlich: Auswahl von Montag bis Sonntag und Festlegung der Servicezeiten, die wöchentlich gelten
Individuell: Auswahl eines absoluten Datums und Festlegung der Servicezeit, die einmalig gilt

Bei mehreren Zeiträumen:

Zunächst werden alle Servicezeit-Regeln des jeweiligen Kalendertags gefiltert
Überlappende Zeitfenster werden anhand der breitesten Zeitregel gebündelt. Nicht überlappende Zeitfenster werden separat betrachtet.
Gibt es mehrere nicht überlappende Zeitfenster, entstehen mehrere effektive Servicezeiten pro Tag.

Beispiel: Am 12.12.2024 gelten vier Zeitregeln: 09:00 ~ 12:00, 10:00 ~ 12:00, 13:00 ~ 18:00, 15:00 ~ 17:00.
Effektive Servicezeitfenster: 09:00 ~ 12:00, 13:00 ~ 18:00

Antwort außerhalb der Servicezeiten
Liegt die Anfrage außerhalb der Servicezeiten, wird automatisch mit einem vordefinierten Text geantwortet.
Gesprächsinhalte übertragen
Beim erfolgreichen Aufruf des Drittanbieter-Systems werden N Chatverläufe + aktuelle Nutzer:innen-Frage an das Human Handoff-System übermittelt.

Hinweis: Bei Auswahl von Custom Helpdesk (eigenes Kundenservicesystem) erstellt GPTBots keine Human Handoff-Session und stellt keine Nachrichten zu. Daher sind der oben beschriebene Timeout-Mechanismus, die Human Handoff-Zeiträume und die Übertragung von Gesprächsinhalten unwirksam; Human Handoff-Anfragen werden stets als erfolgreich zurückgegeben. Wartezeiten, Warteschlangen, Antworten außerhalb der Servicezeiten usw. müssen von Ihrem Kundenservicesystem selbst umgesetzt werden.

Human Service-Anfrage starten

Nutzer:in startet eine Human Handoff-Anfrage
Möchte ein:e Nutzer:in Human Handoff in Anspruch nehmen, prüft das LLM, ob Human Handoff ausgelöst werden soll. Wird dies bejaht, ruft das LLM das Human Handoff-Tool auf und fordert die Eingabe einer E-Mail-Adresse an. Liegt die E-Mail bereits vor, entfällt dieser Schritt und die Anfrage wird direkt eingeleitet.
- Ist der:die Nutzer:in eingeloggt und die E-Mail verifiziert, liegt die E-Mail-Adresse vor.
- Wird die E-Mail über den Befehl window.ChatBot.setEmail("somebody@mail.com") im Bubble-Widget gesetzt, liegt sie vor.
- Wird die E-Mail über iframe_url + ?email=somebody@mail.com im Iframe übergeben, liegt sie vor.
Sobald das Drittanbieter-Human Handoff-System die Nachricht empfängt und auf die erste Nachricht antwortet, beginnt die Human Handoff-Session offiziell.
Nutzer:innen können beliebig viele Nachrichten mit dem Human Handoff-System austauschen. Sowohl Nutzer:innen als auch Human Service-Mitarbeitende können die Konversation jederzeit beenden.

Binden Sie beliebige Drittanbieter-Kundendienstsysteme wie Intercom, Webhook, Livechat usw. an. Alle oben genannten Funktionen sind anwendbar.
Im Modus Custom Helpdesk (eigenes Kundenservicesystem) werden die Schritte 2 und 3 von Ihrem Kundenservicesystem selbst umgesetzt; GPTBots gibt in Schritt 1 bei erfolgreichem Human Handoff lediglich ein Signal über die API zurück. Details siehe unten.

Authentifizierung „Help-Desk zu Help-Desk“

In diesem Modus können Nutzer:innen Human-Service-Anfragen ausschließlich von der Help-Desk-Plattform selbst aus stellen. Das gleiche Help-Desk-System empfängt und bearbeitet diese Anfragen. Zum Beispiel:

Wird die Anfrage auf der Intercom-Plattform gestellt, empfängt und bearbeitet Intercom diese.
Wird die Anfrage von einer anderen Plattform gestellt, kann Intercom sie in diesem Modus nicht empfangen oder bearbeiten.

Intercom zu Intercom

Bitte folgen Sie dem Intercom-Integrationsleitfaden für die Konfiguration.

Zoho Sales IQ zu Zoho Sales IQ

Bitte folgen Sie der Zoho Sales IQ-Integrationsanleitung.

Hinweis: In diesem Szenario kann es aufgrund von Modellbeschränkungen (OpenAI-GPT-4o-mini) dazu kommen, dass kein Human Service ausgelöst werden kann. Es wird empfohlen, andere Modelle zu verwenden.

Livechat zu Livechat

Bitte folgen Sie dem Livechat-Integrationsleitfaden.

Livedesk zu Livedesk

Bitte folgen Sie dem Livedesk-Integrationsleitfaden.

„Custom Helpdesk“ konfigurieren (eigenes Kundenservicesystem)

Geeignet für Unternehmen, die bereits über ein selbst entwickeltes Kundenservicesystem verfügen: Endnutzer:innen und Servicemitarbeitende befinden sich in Ihrem System, und nur der Schritt „KI-Antwort“ wird an GPTBots ausgelagert. In diesem Modus erstellt GPTBots keine Human Handoff-Session und stellt keine Nachrichten aktiv zu; bei Bedarf wird lediglich ein Human Handoff-Signal in der Antwort der Nachricht-senden-API zurückgegeben. Die Zuweisung an Servicemitarbeitende und die Nachrichtenzustellung übernimmt Ihr System.

Konfigurationsschritte

Klicken Sie in den Agent-Einstellungen unter „Human Handoff“ auf „Aktivieren“, wählen Sie als Human Handoff-System Custom Helpdesk aus – Authentifizierungsdaten sind nicht erforderlich – und bestätigen Sie mit „OK“.
Aktivieren Sie unter „Agent – Integration – API“ die API-Funktion und rufen Sie den API Key ab.
Konfigurieren Sie bei Bedarf den „Trigger-Zeitpunkt“. Bei FlowAgent können Sie im Human Handoff-Knoten eine „Vorlage für Mitarbeiter-Notizen“ konfigurieren, die als Übergabenotiz an Ihr System zurückgegeben wird.

Nutzungsablauf

Sämtliche Interaktionen erfolgen über die Nachricht senden API:

Normale Konversation: Rufen Sie die Nachricht-senden-API mit role=user auf; der Agent antwortet wie gewohnt.
Human Handoff-Signal empfangen: Löst der Agent einen Human Handoff aus, enthält die Antwort human_trigger: true sowie die Übergabenotiz handoff.note (im Streaming-Modus als Frames mit Code 36 / 107). Ihr System weist die Konversation daraufhin einem:einer Servicemitarbeitenden zu. Die Notiz dient ausschließlich als Referenz für Servicemitarbeitende und darf Nutzer:innen nicht angezeigt werden.
Nachrichten archivieren: Während der menschlichen Betreuung werden Antworten der Servicemitarbeitenden mit role=human_agent (optional mit den Mitarbeiterinformationen human_agent_info) übermittelt; bei Nutzer:innen-Nachrichten übergeben Sie ai_response: false oder lassen den Parameter weg. Solche Nachrichten werden nur archiviert, lösen keine KI-Antwort aus und verbrauchen keine Credits.
Rückgabe an die KI: Nachdem der:die Servicemitarbeitende die Betreuung beendet hat, übergeben Sie in der nächsten Nutzer:innen-Nachricht ai_response: true; die Konversation wird wieder normal von der KI beantwortet.

Hinweis:

In diesem Modus sind Timeout-Mechanismus, Human Handoff-Zeiträume und die Übertragung von Gesprächsinhalten unwirksam; Human Handoff-Anfragen werden stets als erfolgreich zurückgegeben.

Wird nach Abschluss der menschlichen Betreuung vergessen, ai_response: true zu übergeben, verbleibt die Konversation dauerhaft im Status „nur archivieren“ und Nutzer:innen erhalten keine KI-Antworten mehr.

Wenn Nutzer:innen über GPTBots-Kanäle (Widget / iframe / WhatsApp usw.) chatten und sich lediglich die Servicemitarbeitenden in Ihrem System befinden, verwenden Sie bitte die Webhook-Authentifizierung.