Wie man einen benutzerdefinierten Bot mit Zendesk Switchboard erstellt: Eine Anleitung für Entwickler

Wenn Sie einen benutzerdefinierten Bot erstellen müssen, der direkt in die Messaging-Infrastruktur von Zendesk integriert wird, müssen Sie mit dem Zendesk Switchboard arbeiten. Diese Routing-Schicht innerhalb von Sunshine Conversations bestimmt, welches System (Ihr Bot, eine KI eines Drittanbieters oder menschliche Agenten) jedes Kundengespräch steuert.

Das Erstellen einer benutzerdefinierten Integration bietet Ihnen maximale Flexibilität. Sie steuern die Logik, die Übergaberegeln und das Verhalten Ihres Bots über verschiedene Kanäle hinweg. Dies erfordert jedoch auch Entwicklungsressourcen und laufende Wartung.

Für Teams, die Automatisierung ohne die API-Komplexität wünschen, gibt es einen einfacheren Weg. Wir übernehmen die Bot-Orchestrierung automatisch, ohne dass eine Switchboard-Konfiguration erforderlich ist. Wenn Sie jedoch die vollständige Kontrolle benötigen, die eine native Integration bietet, führt Sie dieser Leitfaden durch das vollständige Setup.

Was Sie benötigen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Zendesk Suite Professional oder höher - Switchboard-APIs erfordern mindestens den Professional-Plan, der ab 115 US-Dollar pro Agent und Monat beginnt
• Sunshine Conversations API-Zugangsdaten - Sie benötigen eine Schlüssel-ID (Key ID), ein Geheimnis (Secret) und eine App-ID (App ID) aus Ihrem Zendesk Admin Center
• Webhook-Endpunkt - Ein sicherer HTTPS-Endpunkt, an den Zendesk Konversationsereignisse senden kann
• Entwicklungsumgebung - Ihr Bot muss irgendwo mit Internetzugang gehostet werden, um Webhooks zu empfangen und API-Aufrufe zu tätigen

Wenn Sie nicht über Suite Professional verfügen oder keine Entwicklungsressourcen zur Verfügung stehen, stellt eine verwaltete Lösung wie unsere eine Verbindung über Standard-Zendesk-Kanäle her, ohne dass eine API-Konfiguration erforderlich ist.

Grundlegendes zu den Konzepten von Zendesk Switchboard

Das Switchboard kann sich anfangs abstrakt anfühlen. Lassen Sie uns aufschlüsseln, wie es tatsächlich funktioniert.

Das Switchboard und seine Integrationen

Stellen Sie sich das Switchboard als Verkehrsregler vor. Es sitzt zwischen Ihren Kunden und Ihren Geschäftssystemen und leitet jedes Gespräch an das richtige Ziel weiter.

Jedes System, das Gespräche führen kann, wird als Switchboard-Integration angezeigt. Dies beinhaltet:

• Zendesk KI-Agenten (der native Bot, identifiziert als zd:answerBot)
• KI-Agenten Advanced (Ultimate-basiert, identifiziert als ultimate)
• Agent Workspace (Ihre menschlichen Agenten, identifiziert als zd:agentWorkspace)
• Bots von Drittanbietern (Marketplace-Integrationen über OAuth)
• Benutzerdefinierte Integrationen (Ihr Webhook-basierter Bot)

Quelle: Zendesk Switchboard-Dokumentation

Integrationsstatus: aktiv, ausstehend und Standby

Jede Switchboard-Integration existiert für jedes Gespräch in einem von drei Zuständen:

Es kann immer nur eine Integration aktiv sein. Die aktive Integration ist diejenige, von der erwartet wird, dass sie auf Kundennachrichten antwortet. Wenn sich Ihr Bot im Standby-Modus befindet, empfängt er keine conversation:message-Ereignisse.

Quelle: Zendesk Switchboard-Dokumentation

Kontrollübertragungsoperationen

Ihr Bot muss vier Schlüsseloperationen verarbeiten:

Meistens verwenden Sie passControl mit dem Schlüsselwort "next", um an die Integration zu eskalieren, die als Ihr Standard-Responder konfiguriert ist (normalerweise Agent Workspace).

Quelle: Zendesk Switchboard-Dokumentation

Schritt 1: Holen Sie sich Ihre Sunshine Conversations API-Zugangsdaten

Ihr Bot kommuniziert mit Zendesk über die Sunshine Conversations API. So erhalten Sie die benötigten Zugangsdaten.

Melden Sie sich zunächst in Ihrem Zendesk Admin Center an. Navigieren Sie zu Apps und Integrationen und dann zu Conversations API. Wenn Sie noch keine API-Zugangsdaten erstellt haben, klicken Sie auf API-Schlüssel erstellen.

Sie erhalten:

• Schlüssel-ID (fungiert als Benutzername für die API-Authentifizierung)
• Geheimnis (fungiert als Passwort, speichern Sie dies sicher)
• App-ID (identifiziert Ihre Sunshine Conversations-App)

Speichern Sie alle drei Werte. Sie verwenden sie bei jedem API-Aufruf Ihres Bots.

Testen Sie Ihre Zugangsdaten mit einem einfachen API-Aufruf, um Ihre Switchboards aufzulisten:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

Wenn Sie eine JSON-Antwort mit Ihren Switchboard-Details erhalten, funktionieren Ihre Zugangsdaten.

Quelle: Zendesk Admin Center-Dokumentation

Schritt 2: Erstellen Sie Ihre benutzerdefinierte Integration

Bevor Ihr Bot dem Switchboard beitreten kann, muss er als Integration in Sunshine Conversations vorhanden sein. Dadurch wird die Webhook-Endpunktregistrierung erstellt, die Zendesk verwendet, um Ereignisse an Ihren Bot zu senden.

Verwenden Sie die Create Integration API:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "type": "custom",
    "name": "my-custom-bot",
    "webhooks": [{
      "target": "https://your-bot-endpoint.com/webhook",
      "triggers": ["conversation:create", "conversation:message"]
    }]
  }'

Die Antwort enthält ein id-Feld. Speichern Sie diese Integrations-ID, Sie benötigen sie für den nächsten Schritt.

Quelle: Zendesk Conversations API-Referenz

Schritt 3: Fügen Sie Ihre Integration zum Switchboard hinzu

Eine Integration zu haben, reicht nicht aus. Sie müssen sie Ihrem Switchboard hinzufügen, damit sie tatsächlich die Kontrolle über Gespräche übernehmen kann.

Finden Sie zunächst Ihre Switchboard-ID:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

Erstellen Sie nun eine Switchboard-Integration, die Ihre benutzerdefinierte Integration mit dem Switchboard verknüpft:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards/{switchboard_id}/switchboardIntegrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "name": "my-custom-bot",
    "integrationId": "{custom_integration_id}",
    "deliverStandbyEvents": false,
    "nextSwitchboardIntegrationId": "{agent_workspace_integration_id}"
  }'

Wichtige Parameter erklärt:

• name: Eine lesbare Kennung für Ihren Bot
• integrationId: Die ID aus Schritt 2
• deliverStandbyEvents: Auf false setzen, es sei denn, Sie müssen Gespräche verfolgen, die Sie nicht aktiv bearbeiten
• nextSwitchboardIntegrationId: Normalerweise Ihre Agent Workspace-Integrations-ID, dies bestimmt, wohin Gespräche gehen, wenn Ihr Bot eskaliert

Quelle: Zendesk Conversations API-Referenz

Schritt 4: Konfigurieren Sie Webhooks für Ihren Bot

Ihr Bot muss Echtzeitereignisse von Zendesk empfangen. Die Webhook-Konfiguration, die Sie in Schritt 2 eingerichtet haben, definiert, wohin diese Ereignisse gehen, aber Ihr Endpunkt muss sie ordnungsgemäß verarbeiten.

Erforderliche Webhook-Ereignisse

Ihr Bot sollte mindestens Folgendes abonnieren:

• conversation:create - Neues Gespräch gestartet
• conversation:message - Kunde hat eine Nachricht gesendet
• switchboard:passControl - Die Kontrolle wurde an Ihren Bot übergeben oder von ihm übernommen
• switchboard:releaseControl - Gespräch wurde freigegeben (Ticket geschlossen)

Webhook-Payload-Struktur

Jeder Webhook enthält ein Array von Ereignissen. So sieht ein Nachrichtenereignis aus:

{
  "app": { "id": "5ebee0975ac5304b664a12fa" },
  "webhook": { "id": "5f4eaef81e3dcc117c7ba48a", "version": "v2" },
  "events": [{
    "id": "5f74a0d52b5315fc007e798a",
    "createdAt": "2020-09-30T15:14:29.834Z",
    "type": "conversation:message",
    "payload": {
      "conversation": {
        "id": "f52b01137aa6c250bc7251fa",
        "activeSwitchboardIntegration": {
          "id": "67dc32a58d289d63bfeb6346",
          "name": "my-custom-bot"
        }
      },
      "message": {
        "author": { "type": "user" },
        "content": { "type": "text", "text": "I need help with my order" }
      }
    }
  }]
}

Überprüfen, ob Sie die Kontrolle haben

Überprüfen Sie vor dem Antworten auf eine Nachricht das Objekt activeSwitchboardIntegration. Wenn der name nicht mit dem Namen der Switchboard-Integration Ihres Bots übereinstimmt, sollten Sie nicht antworten. Das Gespräch wird von einem anderen System geführt.

Quelle: Zendesk Receiving Messages-Dokumentation

Schritt 5: Implementieren Sie die Kontrollübertragungslogik

Wenn Ihr Bot feststellt, dass er das Problem des Kunden nicht lösen kann, muss er an einen menschlichen Agenten eskalieren. Hier kommt passControl ins Spiel.

Grundlegende Eskalation

So übergeben Sie die Kontrolle an die nächste konfigurierte Integration (normalerweise Agent Workspace):

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/passControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"switchboardIntegration": "next"}'

Übergeben von Metadaten zum Ausfüllen von Ticketfeldern

Eine der leistungsstärksten Funktionen ist das Ausfüllen von Zendesk-Ticketfeldern während der Übergabe. Fügen Sie Metadaten in Ihren passControl-Aufruf ein:

{
  "switchboardIntegration": "zd-agentWorkspace",
  "metadata": {
    "dataCapture.systemField.priority": "high",
    "dataCapture.systemField.tags": "bot-escalated,shipping-issue",
    "dataCapture.systemField.group_id": "360000123456",
    "dataCapture.ticketField.54321": "Order #12345",
    "first_message_id": "603012d7e0a3f9000c879b67"
  }
}

Dadurch werden automatisch die Ticketpriorität festgelegt, Tags hinzugefügt, einer bestimmten Gruppe zugewiesen, ein benutzerdefiniertes Feld ausgefüllt und gesteuert, wie viel Gesprächsverlauf der Agent sieht.

Freigeben der Kontrolle nach der Lösung

Wenn Ihr Bot das Problem des Kunden vollständig löst, rufen Sie releaseControl auf, um das Gespräch zurückzusetzen:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/releaseControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{}'

Dadurch wird die aktive Integration gelöscht. Wenn der Kunde später zurückkehrt, beginnt er neu mit Ihrem Standard-Responder.

Quelle: Zendesk Conversations API-Referenz

Schritt 6: Testen Sie Ihre benutzerdefinierte Bot-Integration

Überprüfen Sie vor der Liveschaltung, ob jeder Teil Ihrer Integration korrekt funktioniert.

Test-Checkliste

1. Erstellen Sie ein Testgespräch über Ihr Web Widget oder Ihren Messaging-Kanal
2. Überprüfen Sie, ob Ihr Bot das conversation:create-Ereignis empfängt
3. Senden Sie eine Testnachricht und bestätigen Sie, dass Ihr Bot conversation:message empfängt
4. Überprüfen Sie, ob Ihr Bot nur antwortet, wenn activeSwitchboardIntegration.name übereinstimmt
5. Testen Sie die Eskalation, indem Sie Ihren passControl-Flow auslösen
6. Überprüfen Sie die Ticketerstellung im Agent Workspace mit korrekten Metadaten
7. Schließen Sie das Ticket und bestätigen Sie, dass die Kontrolle nach dem Ausführen der Automatisierung an Ihren Bot zurückgegeben wird

Häufige Testprobleme

Quelle: Zendesk Agent Workspace-Dokumentation

Häufige Muster und Best Practices

Kanalspezifisches Routing

Verschiedene Kanäle benötigen oft unterschiedliche Standard-Responder. Konfigurieren Sie Standardwerte pro Kanal mithilfe der Update Integration API:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations/{channel_integration_id} \
  -X PATCH \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"defaultResponderId": "{switchboard_integration_id}"}'

Leiten Sie beispielsweise WhatsApp-Gespräche direkt an Agenten weiter (Kanal mit hohem Wert), während Sie den Web Widget-Traffic zuerst an Ihren Bot senden.

Phasenweise Einführung während Migrationen

Wenn Sie von einer Bot-Plattform zu einer anderen migrieren, führen Sie beide während des Übergangs gleichzeitig aus:

1. Fügen Sie beide Bots als Switchboard-Integrationen hinzu
2. Leiten Sie bestimmte Marken oder Kanäle an jeden Bot weiter
3. Verlagern Sie den Traffic schrittweise, während Sie den neuen Bot validieren
4. Entfernen Sie die alte Bot-Integration, sobald die Migration abgeschlossen ist

Steuern des Gesprächsverlaufs

Standardmäßig enthält Zendesk die letzten 10 Nachrichten beim Erstellen eines Tickets. Um das vollständige Gespräch einzubeziehen, verfolgen Sie die erste Nachrichten-ID, wenn das Gespräch beginnt:

{
  "metadata": {
    "first_message_id": "{first_message_id}"
  }
}

Übergeben Sie dies in Ihrem passControl-Aufruf, um sicherzustellen, dass Agenten den vollständigen Gesprächsverlauf sehen.

Behebung häufiger Probleme

Gespräche bleiben bei der falschen Integration hängen

Wenn Kunden mit einem Bot sprechen, der hätte eskaliert werden sollen, überprüfen Sie, ob Ihr Bot passControl oder releaseControl korrekt aufruft. Überprüfen Sie auch, ob die nextSwitchboardIntegrationId in der Switchboard-Integration Ihres Bots konfiguriert ist.

Metadaten werden nicht an Tickets übergeben

Feld-Schlüssel müssen exakten Mustern folgen:

• Standardfelder: dataCapture.systemField.{field_name}
• Benutzerdefinierte Felder: dataCapture.ticketField.{field_id}

Überprüfen Sie Ihre benutzerdefinierten Feld-IDs im Zendesk Admin Center. Es handelt sich um numerische Werte, nicht um die Feldnamen, die Sie in der Benutzeroberfläche sehen.

Übergaben schlagen stillschweigend fehl

Aktivieren Sie die Protokollierung für alle Webhook-Ereignisse, die Ihr Bot empfängt. Wenn Sie passControl aufrufen, aber keine Änderung des Switchboards feststellen, überprüfen Sie, ob Ihre API-Zugangsdaten die richtigen Bereiche haben und Ihre Payload-JSON gültig ist.

Unbekannter aktiver Integrationsstatus

Wenn Sie sich nicht sicher sind, welche Integration derzeit ein Gespräch steuert, verwenden Sie die Get Conversation API:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id} \
  --user '{key_id}:{secret}'

Überprüfen Sie die Eigenschaft activeSwitchboardIntegration in der Antwort.

Ein einfacherer Ansatz zur Zendesk-Bot-Orchestrierung

Das Erstellen und Warten einer benutzerdefinierten Switchboard-Integration erfordert laufende Entwicklungsressourcen. Ihr Team muss die Webhook-Infrastruktur, die API-Versionsverwaltung, die Fehlerbehandlung und die kontinuierliche Wartung verwalten, wenn Zendesk seine Plattform aktualisiert.

Für Teams, die Automatisierung ohne die API-Komplexität wünschen, bieten wir einen anderen Ansatz. eesel AI übernimmt die Orchestrierung automatisch, ohne dass eine Switchboard-Konfiguration erforderlich ist.

So funktioniert es:

• Keine API-Konfiguration erforderlich - Wir integrieren über die Standardkanäle von Zendesk
• Lernt aus Ihren Inhalten - Unsere KI trainiert auf Ihrem Hilfe-Center, vergangenen Tickets und der Dokumentation
• Automatische Weiterleitung - Gespräche werden basierend auf Ihren Regeln weitergeleitet, ohne manuelle Switchboard-Einrichtung
• Eskalationsregeln in einfachem Deutsch - Anstelle von JSON definieren Sie Regeln wie "Eskalieren Sie Abrechnungsstreitigkeiten immer an einen Menschen"

Unser Business-Plan umfasst KI-Agentenfunktionen, die direkt auf Kunden reagieren, KI-Triage für die Ticketweiterleitung und Massensimulation zum Testen anhand vergangener Tickets vor der Liveschaltung. Die Pläne beginnen bei 239 US-Dollar pro Monat (jährliche Abrechnung) mit einer 7-tägigen kostenlosen Testversion.

Die richtige Wahl hängt von den technischen Fähigkeiten Ihres Teams ab. Native Switchboard bietet maximale Flexibilität für komplexe benutzerdefinierte Logik. Unser Ansatz bietet eine schnellere Amortisierungszeit, wenn Sie eine ausgefeilte Automatisierung ohne die Infrastrukturarbeit wünschen.