Zendesk Sunshine Conversations API Übersicht: Ein Entwickler-Leitfaden für 2026

Wenn Sie eine Kunden-Messaging-Lösung entwickeln, sind Sie wahrscheinlich schon mit dem Albtraum konfrontiert worden, separate Integrationen für WhatsApp, Facebook Messenger, SMS und In-App-Chat zu verwalten. Jeder Kanal hat seine eigene API, Dokumentation und Eigenheiten. Der Wartungsaufwand vervielfacht sich mit jedem Kanal, den Sie hinzufügen.

Zendesk Sunshine Conversations löst dies, indem es eine einzige REST API bereitstellt, die 14+ Messaging-Kanäle vereinheitlicht. Ursprünglich als Smooch.io entwickelt, bevor Zendesk es übernahm, ermöglicht Sunshine Conversations Entwicklern, einmal zu entwickeln und auf jeder wichtigen Messaging-Plattform bereitzustellen.

In diesem Leitfaden werde ich genau aufschlüsseln, was die Sunshine Conversations API bietet, wie sie funktioniert und was Sie wissen müssen, um loszulegen. Ich werde auch zeigen, wie eesel AI eine Alternative für Teams bietet, die KI-gestütztes Messaging ohne den Aufbau benutzerdefinierter Integrationen wünschen.

Was ist Zendesk Sunshine Conversations?

Sunshine Conversations ist eine Multi-Channel-Messaging-Plattform, die das Herzstück des Zendesk Kundenerlebnis-Ökosystems bildet. Sie fungiert als Übersetzungsschicht zwischen Ihrer Anwendung und Dutzenden von Messaging-Kanälen und normalisiert die Eigenheiten jeder Plattform in eine konsistente API.

Die Plattform bedient zwei Hauptzielgruppen:

Für Entwickler entfällt die Notwendigkeit, separate Integrationen für jeden Messaging-Kanal zu erstellen. Anstatt die Eigenheiten der WhatsApp Business API, die Webhook-Formate von Facebook Messenger und die Besonderheiten von SMS-Anbietern zu erlernen, integrieren Sie sich einmal mit Sunshine Conversations und die Plattform erledigt den Rest.

Für Unternehmen ermöglicht es die Verbindung bestehender Tools wie Helpdesks, CRMs und Bot-Plattformen mit Kunden über ihre bevorzugten Messaging-Kanäle, oft ohne Code zu schreiben.

Das Smooch.io Erbe

Sunshine Conversations begann sein Leben als Smooch.io, eine eigenständige Messaging-Plattform, die von Zendesk übernommen wurde. Sie werden immer noch auf Smooch-Referenzen in älterer Dokumentation und einigen SDK-Repositories stoßen. Die Kernplattform wurde vollständig in die Zendesk Suite integriert, aber die API-Architektur und viele Endpunkte behalten die Smooch-DNA bei.

Für lizenzierte Zendesk-Kunden ist die Basis-URL https://{subdomain}.zendesk.com/sc. Ältere Sunshine Conversations Konten verwenden weiterhin https://api.smooch.io.

Kern-API-Fähigkeiten und Architektur

Die Sunshine Conversations API folgt den REST-Prinzipien mit JSON-Anfrage- und Antwortkörpern. Die aktuelle Version ist v2, obwohl v1.1 für bestehende Integrationen weiterhin unterstützt wird.

Wichtige Endpunkte und Ressourcen

Die API konzentriert sich auf mehrere Kernressourcen:

Ressource	Primäre Operationen	Anwendungsfall
Nachrichten (Messages)	Senden, empfangen, Nachrichten auflisten	Kern-Messaging-Funktionalität
Konversationen (Conversations)	Konversations-Threads erstellen, lesen, aktualisieren, löschen	Konversationsmanagement
Benutzer (Users)	Profilverwaltung, Authentifizierung, Zusammenführung	Kundenidentität
Webhooks	Ereignisse abonnieren, Endpunkte verwalten	Echtzeitbenachrichtigungen
Anhänge (Attachments)	Mediendateien hochladen, abrufen	Rich-Messaging-Unterstützung

Alle Endpunkte verwenden Standard-HTTP-Methoden: GET zum Abrufen, POST zum Erstellen, PATCH zum Aktualisieren und DELETE zum Entfernen. Die API gibt konsistente Fehlerformate mit HTTP-Statuscodes und beschreibenden Fehlerobjekten zurück.

Paginierung und Limits

Sunshine Conversations verwendet Cursor-basierte Paginierung anstelle von Offset-Paginierung. Dieser Ansatz vermeidet Leistungsprobleme bei großen Datensätzen, indem er einen Zeiger auf ein bestimmtes Element anstelle von Seitenzahlen zurückgibt.

Sie können die Abfrageparameter page[after] oder page[before] verwenden, um vorwärts oder rückwärts durch die Ergebnisse zu navigieren. Ein optionaler Parameter page[size] steuert die Anzahl der Datensätze, die pro Anfrage zurückgegeben werden.

Beachten Sie diese harten Limits:

Limit	Wert	Auswirkung
Nachrichten pro Konversation	30.000	Ältere Konversationen müssen archiviert werden
JSON Anfragegröße	100KB	Große Payloads werden abgelehnt
Datei Uploadgröße	50MB	Medienanhänge haben Größenbeschränkungen
Ratenbegrenzung (Rate limiting)	Variabel	429 Statuscode bei Überschreitung

Wenn Sie Ratenbegrenzungen erreichen, gibt die API den Status 429 Too Many Requests zurück. Implementieren Sie exponentielles Backoff mit Jitter anstelle von festen Wiederholungsintervallen. Nutzungsspitzen sind zu erwarten und die Limits sind so ausgelegt, dass sie für normale Operationen großzügig sind.

Authentifizierung und Sicherheit

Sunshine Conversations unterstützt zwei Authentifizierungsmethoden, die jeweils für unterschiedliche Anwendungsfälle geeignet sind.

Basisauthentifizierung (Basic authentication)

Für Server-zu-Server-API-Aufrufe ist die Basisauthentifizierung der einfachste Ansatz. Sie verwenden Ihre API-Schlüssel-ID als Benutzernamen und das Geheimnis als Passwort im Standard-HTTP-Basisauthentifizierungsformat.

Diese Methode funktioniert gut für Backend-Integrationen, bei denen Sie Aufrufe von Ihrem Server an die Sunshine Conversations API tätigen. Sie ist einfach zu implementieren und zu debuggen.

JWT Authentifizierung

JSON Web Tokens (JWTs) bieten eine flexiblere Authentifizierungsoption, die besonders nützlich ist, wenn Sie den Zugriff eng begrenzen müssen oder wenn Sie Anmeldeinformationen über weniger sichere Kanäle weitergeben.

Um ein JWT zu generieren, benötigen Sie:

• Header mit Algorithmus (HS256) und Schlüssel-ID
• Payload mit Scope-Claim (Konto, App oder Integration)
• Signatur mit Ihrem API-Geheimnis

JWTs werden im Authorization Header mit dem Bearer Präfix übertragen: Authorization: Bearer your-jwt-token.

Autorisierungsbereiche (Authorization scopes)

Die API verwendet drei Hauptautorisierungsbereiche, die bestimmen, welche Operationen zulässig sind:

Scope	Zugriffsebene	Am besten geeignet für
Konto (account)	Alle Methoden einschließlich Kontobereitstellung	Multi-Tenant SaaS Anwendungen
App	Alle Kern-API-Methoden	Einzelanwendungsintegrationen
Integration	Benutzer, Konversationen, Anhänge, Webhooks	Begrenzte Drittanbieterintegrationen

API-Schlüssel folgen einer Namenskonvention, die ihren Scope angibt: Konto-Schlüssel beginnen mit act_, Servicekonto-Schlüssel mit svc_ und App-Schlüssel mit app_.

Unterstützte Messaging-Kanäle

Sunshine Conversations unterstützt die umfassendste Palette von Messaging-Kanälen in der Branche. Alle Kanäle sind über dieselbe API zugänglich, wobei die Plattform die Übersetzung zwischen kanalspezifischen Formaten und der einheitlichen API übernimmt.

Drittanbieter-Messaging-Apps

• WhatsApp Business API - Volle Unterstützung für Business Messaging, Vorlagen und Rich Media
• Facebook Messenger - Vollständige Integration mit Buttons, Schnellantworten und Webviews
• Instagram Direct - Messaging über Instagram Business Konten
• Apple Messages for Business - Integration mit Apples Business Messaging Plattform
• LINE, Telegram, Viber - Volle Unterstützung für wichtige asiatische und europäische Messaging-Plattformen
• Twitter DM - Direktnachrichten über Twitter
• WeChat - Unterstützung für Chinas dominierende Messaging-Plattform

SMS- und Sprachanbieter

• Twilio - SMS Integration über die Twilio Infrastruktur
• MessageBird - Alternative SMS Anbieter Integration

Von Zendesk entwickelte SDKs

• Web Messenger - Einbettbares Chat-Widget für Websites
• Android SDK - Natives Android In-App-Messaging
• iOS SDK - Natives iOS In-App-Messaging
• Unity SDK - Gaming- und 3D-Anwendungsintegration

Die Plattform unterstützt Rich-Messaging-Funktionen über Kanäle, wo verfügbar, einschließlich strukturierter Nachrichten, Schnellantworten, Karussells und Dateifreigabe. Wenn Kanäle neue Funktionen hinzufügen, aktualisiert Sunshine Conversations in der Regel, um diese zu unterstützen, wobei nur minimale Codeänderungen auf Ihrer Seite erforderlich sind.

Entwickler-Tools und SDKs

Während Sie direkt über HTTP mit der Sunshine Conversations API interagieren können, bietet Zendesk offizielle SDKs, die die API umschließen und Authentifizierung, Fehlerbehandlung und Anfrageformatierung übernehmen.

Offizielle SDKs

Sprache	Paket/Repository	Status
Java	sunshine-conversations-java	Aktiv gepflegt
Ruby	sunshine-conversations-ruby	Automatisch generiert aus OpenAPI
Python	sunshine-conversations-client	PyPI Paket, automatisch generiert
JavaScript	sunshine-conversations-javascript	Von der Community gepflegt

Das Java SDK erhält die aktivste Wartung von Zendesk. Die Ruby- und Python-SDKs werden automatisch aus der OpenAPI-Spezifikation generiert, wodurch sichergestellt wird, dass sie mit API-Änderungen auf dem neuesten Stand bleiben, aber möglicherweise keine handgefertigten Ergonomie aufweisen.

Entwicklungswerkzeuge

Für Tests und Erkundungen bietet Zendesk eine Postman Collection, die alle Endpunkte mit Beispielanfragen enthält. Die OpenAPI Spezifikation ist öffentlich verfügbar, um benutzerdefinierte Clients oder Dokumentationen zu generieren.

Webhook Integration

Echtzeit-Ereignisbehandlung erfolgt über Webhooks. Ihr Server stellt einen Endpunkt bereit, der POST-Anfragen empfängt, wenn Ereignisse auftreten, wie z. B. eingehende Nachrichten, Zustellbestätigungen oder Änderungen des Konversationsstatus.

Häufige Webhook-Trigger sind:

Trigger	Wann er ausgelöst wird
conversation:message	Kunde oder Agent sendet eine Nachricht
postback	Benutzer klickt auf eine Schaltfläche oder eine Schnellantwort
conversation:created	Neue Konversation beginnt
conversation:typing	Benutzer tippt eine Nachricht

Sie müssen Webhook-Signaturen mit dem gemeinsamen Geheimnis überprüfen, das bei der Erstellung der Webhook-Integration bereitgestellt wird, um sicherzustellen, dass Ereignisse tatsächlich von Sunshine Conversations stammen.

Integration mit dem Zendesk Ökosystem

Sunshine Conversations existiert nicht isoliert. Es ist tief in die breitere Zendesk Plattform integriert, was die Entwicklung beschleunigen oder alternative Ansätze bieten kann, je nach Ihrem Anwendungsfall.

Web Widget

Das Web Widget bietet eine kundenorientierte Chat-Oberfläche, die auf Ihrer Website oder Ihrem Hilfe-Center eingebettet ist. Es verwendet Sunshine Conversations im Hintergrund, sodass Konversationen, die über das Widget gestartet werden, über dieselbe API fließen, die Sie für andere Kanäle verwenden.

Agent Workspace

Wenn Konversationen menschliches Eingreifen erfordern, erscheinen sie im Zendesk Agent Workspace als Tickets. Agenten können direkt antworten und ihre Nachrichten fließen über Sunshine Conversations zurück zum Kunden auf seinem ursprünglichen Kanal. Dies bietet Ihnen eine einheitliche Agentenoberfläche, selbst wenn Kunden über ein Dutzend Messaging-Plattformen verteilt sind.

Switchboard

Das Switchboard steuert das Konversationsrouting zwischen Bots, KI-Systemen und menschlichen Agenten. Sie können die Steuerung zwischen Systemen programmgesteuert übergeben und gleichzeitig den Konversationskontext beibehalten. Dies ermöglicht ausgefeilte Workflows wie Bot-First-Triage mit nahtloser Eskalation zu Menschen.

Bei eesel AI nutzen wir diese Integrationspunkte, um KI-gestützten Kundenservice bereitzustellen, der nativ in Zendesk funktioniert. Unsere KI-Agenten können Konversationen über Sunshine Conversations abwickeln, bei Bedarf an menschliche Agenten eskalieren und den vollständigen Kontext während der gesamten Interaktion beibehalten.

Zendesk Suite Preise und Zugriff

Der Zugriff auf die Sunshine Conversations API erfordert bestimmte Zendesk Suite Pläne. Nicht alle Stufen beinhalten die vollen Plattformfunktionen.

Plan	Jahrespreis	Sunshine Conversations Zugriff	MAUs enthalten
Suite Team	55 $/Agent/Monat	Nur grundlegendes Messaging	N/A
Suite Growth	89 $/Agent/Monat	Nur grundlegendes Messaging	N/A
Suite Professional	115 $/Agent/Monat	Voller API Zugriff	1.000
Suite Enterprise	169 $/Agent/Monat	Voller API Zugriff	1.000

Wichtiger Unterschied: Suite Team und Growth beinhalten Messaging über das Web Widget, bieten aber keinen vollständigen API Zugriff für benutzerdefinierte Integrationen. Um Ihre eigenen Integrationen mit der Sunshine Conversations API zu erstellen, benötigen Sie Suite Professional oder Enterprise.

Monatlich aktive Benutzer (MAUs) stellen eindeutige Benutzer dar, die innerhalb eines Zeitraums von 30 Tagen Nachrichten senden oder empfangen. Wenn Sie Ihre enthaltenen MAUs überschreiten, sind zusätzliche Pakete für ca. 50 $ pro 2.500 MAUs erhältlich.

Quelle: Zendesk Preise

Erste Schritte mit der Sunshine Conversations Entwicklung

Wenn Sie bereit sind, mit Sunshine Conversations zu entwickeln, benötigen Sie Folgendes, um loszulegen.

Voraussetzungen

1. Zendesk Suite Professional oder Enterprise - Erforderlich für vollen API Zugriff
2. Admin Center Zugriff - Zum Generieren von API Schlüsseln und Konfigurieren von Kanälen
3. Entwicklungsumgebung - Ein Server oder eine Cloud-Funktion zum Empfangen von Webhooks
4. Grundlegendes Verständnis von REST APIs - Zum Tätigen von API Aufrufen und Verarbeiten von Antworten

Schnellstartschritte

1. API Schlüssel generieren - Navigieren Sie im Admin Center zu Apps und Integrationen > APIs > Conversations API. Erstellen Sie einen neuen Schlüssel und speichern Sie die App-ID, die Schlüssel-ID und das Geheimnis sicher.

2. Webhook Endpunkt einrichten - Erstellen Sie einen öffentlich zugänglichen HTTPS Endpunkt, der POST Anfragen empfangen kann. Für die lokale Entwicklung können Tools wie ngrok Tunnel zu Ihrem Rechner erstellen.

3. Ersten Kanal konfigurieren - Aktivieren Sie im Admin Center einen Messaging-Kanal (Web Widget ist am einfachsten, um zu beginnen) und verbinden Sie ihn mit Ihrer Sunshine Conversations App.

4. Integration testen - Senden Sie eine Nachricht über Ihren gewählten Kanal und überprüfen Sie, ob sie Ihren Webhook Endpunkt erreicht. Versuchen Sie dann, eine Antwort über die API zurückzusenden.

Für eine detailliertere Anleitung lesen Sie unseren vollständigen Leitfaden für die ersten Schritte.

eesel AI: KI-gestütztes Messaging ohne benutzerdefinierte Entwicklung

Das Erstellen benutzerdefinierter Integrationen mit Sunshine Conversations erfordert erhebliche Entwicklungsressourcen. Wenn Ihr Ziel KI-gestützter Kundenservice ist und nicht der Aufbau einer benutzerdefinierten Messaging-Plattform, sollten Sie überlegen, ob Sie überhaupt entwickeln müssen.

Bei eesel AI bieten wir KI-Agenten, die sich direkt in Zendesk integrieren und die Komplexität von Sunshine Conversations, Switchboard Orchestrierung und Multi-Channel-Messaging bewältigen, ohne dass eine benutzerdefinierte Entwicklung erforderlich ist. Sie erhalten KI-gestützten Kundenservice, der über alle Messaging-Kanäle hinweg funktioniert, mit menschlicher Eskalation und vollständiger Zendesk Integration, ohne Code zu schreiben.

Für Teams, die ihren bestehenden Helpdesk um KI-Chat-Funktionen erweitern möchten, funktioniert unser KI Chatbot über Messaging-Kanäle mit dem gleichen einheitlichen Ansatz wie Sunshine Conversations, jedoch ohne den Entwicklungsaufwand. Wenn Sie Hilfe bei der Verwaltung des Ticketvolumens benötigen, leitet, taggt und priorisiert KI Triage Tickets automatisch, bevor sie Ihre Agenten erreichen.