So erstellen Sie eine benutzerdefinierte Integration für Zendesk Sunshine Conversations

Das Erstellen einer benutzerdefinierten Integration mit Zendesk Sunshine Conversations ermöglicht es Ihnen, massgeschneiderte Messaging-Erlebnisse zu schaffen, die genau auf Ihre Geschäftsanforderungen zugeschnitten sind. Egal, ob Sie ein proprietäres CRM verbinden, einen spezialisierten Bot erstellen oder komplexe Konversationsabläufe orchestrieren möchten, die Sunshine Conversations API bietet Ihnen die Grundlage, die Sie benötigen.

Dieser Leitfaden führt Sie durch alles, von der anfänglichen Einrichtung bis zur Produktionsbereitstellung. Am Ende verfügen Sie über einen funktionierenden Webhook-Server, der Nachrichten empfangen, intelligent antworten und bei Bedarf an menschliche Agenten übergeben kann. Eine offizielle Referenz finden Sie in der Zendesk API-Dokumentation.

Wenn Sie die Engineering-Arbeit lieber überspringen möchten, bietet eesel AI eine No-Code-Alternative, die sich in wenigen Minuten mit Zendesk verbindet und Konversationen autonom abwickelt.

Zendesk Sunshine Conversations verbindet Messaging-Kanäle über Webhooks und APIs mit Ihren Geschäftsanwendungen.

Was Sie benötigen

Bevor Sie eintauchen, stellen Sie sicher, dass Sie Folgendes eingerichtet haben.

Zendesk-Anforderungen:

• Ein Zendesk Suite Professional oder Enterprise Plan (der Zugriff auf die Sunshine Conversations API erfordert diese Stufen)
• Administratorzugriff auf Ihr Zendesk-Konto
• Mindestens 1.000 monatlich aktive Benutzer (MAUs), die in Ihrem Plan enthalten sind (zusätzliche MAU-Pakete sind für 50 $ pro 2.500 MAUs erhältlich)

Technische Anforderungen:

• Eine Serverumgebung (Node.js wird für diesen Leitfaden empfohlen)
• ngrok für lokale Webhook-Tests
• Grundkenntnisse in REST-APIs und Webhooks
• HTTPS-Endpunkt für die Produktion

Die Architektur von Sunshine Conversations verstehen

Sunshine Conversations ist die einheitliche Messaging-Plattform von Zendesk. Ursprünglich Smooch.io (von Zendesk im Jahr 2019 übernommen), betreibt es jetzt Messaging in der gesamten Zendesk Suite. Die Architektur basiert auf einigen Schlüsselkonzepten, die Sie verstehen müssen, bevor Sie mit dem Bau beginnen.

Apps: Jede App repräsentiert ein Unternehmen oder eine Marke. Sie erstellen im Admin Center eine App, die alle Ihre Konversationsdaten enthält.

Integrationen: Dies sind die Verbindungen zwischen Sunshine Conversations und externen Systemen. Benutzerdefinierte Integrationen verwenden Webhooks, um Nachrichten zu senden und zu empfangen.

Konversationen: Eine Konversation ist ein Thread von Nachrichten zwischen einem Benutzer und Ihrem Unternehmen. Konversationen bleiben kanalübergreifend bestehen (ein Benutzer kann im Web-Chat beginnen und auf WhatsApp fortfahren).

Switchboard (Schaltzentrale): Dies steuert, wer eine Konversation zu einem bestimmten Zeitpunkt "besitzt". Die Schaltzentrale leitet Konversationen zwischen Bots, Agenten und Integrationen weiter.

Authentifizierung: Die API verwendet Basic Auth (Key ID als Benutzername, Secret als Passwort) oder JWT-Token für erhöhte Sicherheit.

Der Ablauf funktioniert wie folgt: Ein Kunde sendet eine Nachricht über einen beliebigen verbundenen Kanal (Web-Widget, WhatsApp usw.). Sunshine Conversations empfängt die Nachricht und leitet sie an Ihre Webhook-Integration weiter. Ihr Server verarbeitet die Nachricht, entscheidet, wie er antworten soll, und sendet eine Antwort über die API zurück. Bei Bedarf kann Ihre Integration die Kontrolle über die Schaltzentrale an einen menschlichen Agenten übergeben.

Schritt 1: Erstellen Sie Ihre Sunshine Conversations App und API-Schlüssel

Zuerst müssen Sie eine App erstellen und API-Anmeldeinformationen generieren.

Navigieren Sie zum Zendesk Admin Center. Gehen Sie zu Apps und Integrationen > APIs > Conversations API.

Klicken Sie auf API-Schlüssel erstellen und geben Sie ihm einen beschreibenden Namen wie "Production Webhook Integration". Sie erhalten drei Informationen:

• App-ID: Eine eindeutige Kennung für Ihre App
• Key-ID: Wird als Benutzername für die API-Authentifizierung verwendet
• Geheimer Schlüssel: Wird als Passwort für die API-Authentifizierung verwendet

Bewahren Sie diese Anmeldeinformationen sicher auf. Sie benötigen sie für jeden API-Aufruf. Der geheime Schlüssel wird nur einmal angezeigt. Wenn Sie ihn verlieren, müssen Sie ein neues Schlüsselpaar generieren.

Richten Sie Ihre Umgebungsvariablen ein, um Anmeldeinformationen aus Ihrem Code herauszuhalten:

export SUNSHINE_APP_ID="your_app_id"
export SUNSHINE_KEY_ID="your_key_id"
export SUNSHINE_SECRET="your_secret_key"

Schritt 2: Richten Sie Ihre Webhook-Integration ein

Erstellen Sie nun die Webhook-Integration, die Nachrichtenereignisse empfängt.

Gehen Sie im Admin Center zu Integrationen > Conversations-Integrationen.

Klicken Sie auf Integration erstellen und wählen Sie Benutzerdefiniert als Typ aus. Konfigurieren Sie Folgendes:

Ziel-URL: Verwenden Sie für die lokale Entwicklung Ihre ngrok-URL (wir richten dies im nächsten Schritt ein). Verwenden Sie für die Produktion Ihren HTTPS-Endpunkt.

Trigger: Wählen Sie aus, welche Ereignisse Sie empfangen möchten. Aktivieren Sie mindestens:

• conversation:message - Empfängt alle eingehenden Nachrichten
• postback - Empfängt Schaltflächenklicks und Schnellantworten
• conversation:start - Benachrichtigt, wenn eine neue Konversation beginnt

Geheimnis: Generieren Sie eine zufällige Zeichenfolge zur Überprüfung der Webhook-Signatur. Dies stellt sicher, dass Anfragen tatsächlich von Zendesk stammen.

Speichern Sie Ihre Webhook-ID (wird nach der Erstellung angezeigt) und das freigegebene Geheimnis, das Sie konfiguriert haben. Sie benötigen beide zur Signaturüberprüfung.

Schritt 3: Erstellen Sie Ihren Webhook-Server

Lassen Sie uns einen einfachen Express.js-Server erstellen, der Nachrichten empfängt und beantwortet.

Initialisieren Sie zuerst Ihr Projekt:

mkdir sunshine-integration
cd sunshine-integration
npm init -y
npm install express crypto dotenv

Erstellen Sie eine index.js-Datei:

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' }));

// Webhook-Verifizierungs-Middleware
function verifyWebhook(req, res, next) {
  const signature = req.headers['x-smooch-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (hash !== signature) {
    return res.status(401).send('Unauthorized');
  }
  next();
}

// Eingehende Nachrichten verarbeiten
app.post('/webhook', verifyWebhook, async (req, res) => {
  const event = JSON.parse(req.body);

  // Empfang sofort bestätigen
  res.status(200).send('OK');

  // Das Ereignis verarbeiten
  if (event.trigger === 'message:appUser') {
    await handleUserMessage(event);
  }
});

async function handleUserMessage(event) {
  const message = event.messages[0];
  const userId = event.appUser._id;
  const conversationId = event.conversation._id;

  console.log(`Received: ${message.text} from ${userId}`);

  // Einfache Echo-Antwort (durch Ihre Logik ersetzen)
  await sendMessage(conversationId, `You said: ${message.text}`);
}

async function sendMessage(conversationId, text) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        author: { type: 'business' },
        content: { type: 'text', text: text }
      })
    }
  );

  if (!response.ok) {
    console.error('Failed to send message:', await response.text());
  }
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Erstellen Sie eine .env-Datei:

SUNSHINE_APP_ID=your_app_id
SUNSHINE_KEY_ID=your_key_id
SUNSHINE_SECRET=your_secret_key
WEBHOOK_SECRET=your_webhook_secret

Starten Sie Ihren Server:

node index.js

Schritt 4: Lokal mit ngrok testen

Da Sunshine Conversations einen öffentlichen HTTPS-Endpunkt benötigt, verwenden Sie ngrok, um Ihren lokalen Server freizugeben.

Installieren Sie ngrok und starten Sie einen Tunnel:

ngrok http 3000

Kopieren Sie die HTTPS-URL (etwa https://abc123.ngrok.io). Aktualisieren Sie Ihre Webhook-Integration im Admin Center mit dieser URL als Ziel-URL.

Testen Sie Ihre Integration, indem Sie eine Nachricht über das Zendesk Web Widget oder einen verbundenen Kanal senden. Sie sollten die Nachricht in Ihrer Serverkonsole protokolliert sehen, und der Bot sollte die Nachricht zurückgeben.

Schritt 5: Konfigurieren Sie die Schaltzentrale für Bot-zu-Agent-Übergaben

Die Schaltzentrale steuert, wann Ihr Bot Nachrichten verarbeitet und wann menschliche Agenten übernehmen. Dies ist für Produktionsbereitstellungen unerlässlich.

Wichtige Konzepte der Schaltzentrale:

• Kontrolle übergeben: Überträgt das Eigentum sofort an eine andere Integration
• Kontrolle anbieten: Teilt die Kontrolle, bis das Ziel sie akzeptiert
• Kontrolle freigeben: Gibt die Konversation in ihren Standardzustand zurück

So finden Sie Ihre Switchboard-ID:

async function getSwitchboardId() {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/switchboards`,
    {
      headers: { 'Authorization': `Basic ${auth}` }
    }
  );

  const data = await response.json();
  return data.switchboards[0].id;
}

So eskalieren Sie an einen menschlichen Agenten:

async function escalateToAgent(conversationId, switchboardId, metadata = {}) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/switchboard/passControl`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        switchboardIntegration: 'zd:agentWorkspace', // Zendesk Agent Workspace
        metadata: {
          priority: 'high',
          topic: metadata.topic || 'general',
          ...metadata
        }
      })
    }
  );
}

Wenn Sie die Kontrolle mit Metadaten übergeben, füllt Zendesk automatisch Ticketfelder aus, legt die Priorität fest und leitet sie basierend auf Ihren Triggern an das entsprechende Team weiter.

Schritt 6: Messaging-Kanäle verbinden

Ihre Integration funktioniert mit jedem Kanal, der mit Sunshine Conversations verbunden ist. Verfügbare Kanäle sind:

• Web-Widget (eingebaut)
• WhatsApp Business API
• Facebook Messenger
• Instagram
• Apple Messages for Business
• LINE
• Telegram
• SMS über Twilio oder MessageBird
• Android- und iOS-SDKs

Um einen Kanal hinzuzufügen, gehen Sie zu Admin Center > Kanäle > [Kanalname] und befolgen Sie die Authentifizierungsschritte. Jeder Kanal hat spezifische Anforderungen:

• WhatsApp: Erfordert Meta Business-Verifizierung und ein WhatsApp Business API-Konto
• Facebook/Instagram: Verbindet sich über Ihren Facebook Business Manager
• SMS: Erfordert ein Twilio- oder MessageBird-Konto mit einer Telefonnummer

Sobald die Verbindung hergestellt ist, fliessen alle Nachrichten unabhängig vom Kanal über denselben Webhook-Endpunkt. Ihr Code muss nicht geändert werden, um neue Kanäle zu unterstützen.

Testen und Debuggen Ihrer Integration

Testen Sie Ihre Integration gründlich, bevor Sie live gehen.

Best Practices für die lokale Entwicklung:

• Verwenden Sie die Replay-Funktion von ngrok, um Webhooks während des Debuggens erneut zu senden
• Implementieren Sie eine umfassende Protokollierung für jedes empfangene Ereignis und jede ergriffene Massnahme
• Erstellen Sie Testkonversationen und überprüfen Sie den vollständigen Ablauf von der Nachricht bis zur Antwort

Häufige Fehler und Lösungen:

Ratenbegrenzung: Sunshine Conversations begrenzt API-Anfragen standardmässig auf 100 pro Minute. Implementieren Sie eine ordnungsgemässe Handhabung:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await delay(retryAfter * 1000);
  // Wiederholen Sie die Anfrage
}

Konversationsgrössenbeschränkungen: Konversationen haben ein Limit von 30.000 Nachrichten. Archivieren Sie alte Konversationen, um unter diesem Limit zu bleiben.

Sicherheits-Best Practices

Produktionsintegrationen erfordern zusätzliche Sicherheitsmassnahmen.

Speicherung von Anmeldeinformationen: Übertragen Sie niemals Anmeldeinformationen in die Versionskontrolle. Verwenden Sie Umgebungsvariablen oder einen Secrets Manager wie AWS Secrets Manager oder HashiCorp Vault. Zendesk befolgt branchenübliche Sicherheitspraktiken, um Ihre Daten zu schützen.

Überprüfung der Webhook-Signatur: Überprüfen Sie immer den X-Smooch-Signature-Header. Ohne dies kann jeder gefälschte Webhooks an Ihren Endpunkt senden.

Nur HTTPS: Sunshine Conversations erfordert HTTPS für Webhook-URLs in der Produktion. Verwenden Sie ein gültiges SSL-Zertifikat.

JWT-Authentifizierung: Wechseln Sie für erhöhte Sicherheit von Basic Auth zu JWT-Token:

function generateJWT() {
  const header = { alg: 'HS256', typ: 'JWT' };
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    scope: 'app',
    iat: now,
    exp: now + 600 // 10 Minuten
  };

  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const signature = crypto
    .createHmac('sha256', process.env.SUNSHINE_SECRET)
    .update(`${encodedHeader}.${encodedPayload}`)
    .digest('base64url');

  return `${encodedHeader}.${encodedPayload}.${signature}`;
}

API-Schlüsselrotation: Generieren Sie regelmässig neue Schlüssel und widerrufen Sie alte. Sunshine Conversations unterstützt mehrere aktive Schlüssel für die Rotation ohne Ausfallzeiten.

Bereitstellung in der Produktion

Wenn Sie bereit sind, live zu gehen, befolgen Sie diese Checkliste.

Checkliste für die Produktionsbereitstellung:

• Wechseln Sie von ngrok zu einem permanenten HTTPS-Endpunkt
• Implementieren Sie eine ordnungsgemässe Fehlerbehandlung und Wiederholungslogik
• Richten Sie Überwachung und Benachrichtigungen für Webhook-Fehler ein
• Konfigurieren Sie die Protokollaggregation für das Debuggen
• Testen Sie Switchboard-Übergaben mit tatsächlichen Agenten
• Stellen Sie sicher, dass die Ratenbegrenzung Ihren Anwendungsfall nicht beeinträchtigt
• Dokumentieren Sie Ihre Eskalationsrichtlinien

Überwachungsempfehlungen:

Verfolgen Sie diese Metriken, um eine gesunde Integration sicherzustellen:

• Erfolgsrate der Webhook-Zustellung (Ziel: >99 %)
• Durchschnittliche Antwortzeit (unter 5 Sekunden halten)
• Fehlerrate nach Fehlertyp
• Konversationsvolumen nach Kanal

Richten Sie Warnungen für fehlgeschlagene Webhook-Zustellungen, hohe Fehlerraten und sich nähernde Ratenlimits ein.

Alternative: eesel AI für eine schnellere Implementierung

Das Erstellen einer benutzerdefinierten Integration gibt Ihnen die vollständige Kontrolle, erfordert jedoch erheblichen Entwicklungsaufwand und laufende Wartung. Wenn Sie KI-gestütztes Messaging ohne den technischen Aufwand benötigen, sollten Sie eesel AI als Alternative in Betracht ziehen.

eesel AI verbindet sich direkt mit Zendesk und verarbeitet den gesamten Konversationsablauf automatisch. Anstatt Webhooks und Switchboard-Logik zu erstellen, tun Sie einfach Folgendes:

1. Verbinden Sie eesel AI mit Ihrem Zendesk-Konto (One-Click-Integration)
2. Trainieren Sie den KI-Agenten mit Ihren vergangenen Tickets, dem Hilfecenter und der Dokumentation
3. Konfigurieren Sie Eskalationsregeln in einfachem Deutsch ("Eskalieren Sie Abrechnungsstreitigkeiten an das Finanzteam")
4. Testen Sie in einer Sandbox mit vergangenen Tickets, bevor Sie live gehen

Benutzerdefinierte Integrationen sind sinnvoll, wenn Sie proprietäre Systeme haben, die nicht zu Standardmustern passen oder hochspezialisierte Konversationsabläufe benötigen. Für die meisten Teams, die Zendesk KI-Messaging hinzufügen möchten, liefert eesel AI schnellere Ergebnisse mit weniger Wartung. Sie können eesel in Aktion sehen oder es kostenlos ausprobieren.

Beginnen Sie mit dem Aufbau mit Zendesk Sunshine Conversations

Sie haben jetzt alles, was Sie zum Erstellen einer benutzerdefinierten Integration mit Zendesk Sunshine Conversations benötigen. Von der Erstellung von API-Schlüsseln und der Einrichtung von Webhooks bis hin zur Handhabung der Schaltzentrale und der Bereitstellung in der Produktion ist die Grundlage vorhanden.

Die nächsten Schritte hängen von Ihrem spezifischen Anwendungsfall ab. Sie können sich in Ihr CRM integrieren, um Kundendaten abzurufen, sich mit einer Wissensdatenbank für intelligente Antworten verbinden oder eine benutzerdefinierte Routing-Logik basierend auf dem Nachrichteninhalt erstellen.

Wenn sich die benutzerdefinierte Route nach mehr Engineering anfühlt, als Ihr Team derzeit übernehmen kann, können wir Ihnen helfen. Unsere KI-Agenten integrieren sich in wenigen Minuten in Zendesk und verarbeiten Konversationen autonom, während sie bei Bedarf an Ihr Team eskalieren. Sie können eesel kostenlos ausprobieren und es anhand vergangener Tickets testen, um genau zu sehen, wie es funktionieren würde, bevor Sie live gehen.