Zendesk Integration | Kundendaten, Chat und Tickets

Einleitung

Zendesk Integration verbindet deinen Shopware-Shop mit Zendesk. Dein Support-Team sieht Kunde, Bestellungen, Sendungsnummern und Rechnungen direkt neben dem Ticket, deine Besucher erreichen dich über den Zendesk-Chat, und Nachrichten aus dem Kontaktformular landen als Ticket in Zendesk.

Was du mit diesem Plugin erreichst

• Antworten ohne Fensterwechsel: Neben jedem Ticket in Zendesk steht der passende Shopware-Kunde mit seinen Bestellungen, dem Zahlungs- und Versandstatus, den Sendungsnummern und den Dokumenten wie Rechnungen oder Lieferscheinen.
• Bestelldaten mit einem Klick in der Antwort: „In Antwort einfügen“ schreibt Bestellnummer, Bestelldatum, Status und Sendungsverfolgung in den Antworttext.
• Chat im Shop, der deine Cookie-Einstellungen respektiert: Der Zendesk-Chat lädt auf Wunsch erst, wenn der Besucher zugestimmt hat.
• Kontaktanfragen als Ticket: Jede Nachricht aus dem Kontaktformular wird im Namen des Kunden zum Zendesk-Ticket, auf Wunsch mit Tags, Priorität und einer internen Notiz mit Kundendaten.
• Für jeden Verkaufskanal einzeln steuerbar: Du entscheidest je Verkaufskanal, welche der drei Funktionen aktiv ist.

Die drei Teile — Seitenleiste in Zendesk, Chat im Shop und Tickets aus dem Kontaktformular — sind voneinander unabhängig. Du kannst mit einem davon anfangen und die anderen später dazunehmen.

Für wen ist dieses Plugin?

Für Shop-Betreiber, die ihren Kundenservice mit Zendesk machen, und für die Support-Teams, die dort Tickets beantworten.

Voraussetzungen

• Ein eigenes Zendesk-Konto.
• Für die Seitenleiste: einen Zendesk-Tarif, der private Apps erlaubt. Das sind Suite Growth oder höher bzw. Support Professional oder höher. Chat und Tickets aus dem Kontaktformular brauchen keine private App.
• Für die Seitenleiste: Dein Shop muss aus dem Internet über https:// erreichbar sein. Zendesk ruft die Daten direkt bei deinem Shop ab. Ein Verzeichnisschutz (Passwortabfrage vor dem Shop) oder ein Shop, der nur im Firmennetz erreichbar ist, sperrt die Seitenleiste aus.
• Für Tickets aus dem Kontaktformular: ein API-Token aus deinem Zendesk-Konto und die E-Mail-Adresse des Zendesk-Benutzers, zu dem das Token gehört.
• Für den Chat: den Schlüssel deines Zendesk-Web-Widgets (Messaging oder Classic).

Installation

Nach dem Kauf steht dir das Plugin direkt in deiner Administration zur Verfügung — du musst nichts herunterladen.

1. Melde dich in deiner Shopware-Administration an (DeinShop.de/admin).
2. Öffne Erweiterungen → Meine Erweiterungen.
3. Klicke neben Zendesk Integration | Kundendaten, Chat und Tickets auf Installieren.
4. Aktiviere das Plugin über den Schalter neben dem Eintrag — fertig.

Abb. 1: Das Plugin ist installiert und aktiv. Über „Konfigurieren“ öffnest du die Einstellungen.

Taucht Zendesk Integration nicht in der Liste auf, ist dein Shopware-Account noch nicht mit dem Shop verbunden. Das erledigst du unter Erweiterungen → Meine Erweiterungen über die Anmeldung mit deinem Shopware-Konto.

Erste Schritte

1. Einstellungen öffnen: Gehe zu Erweiterungen → Meine Erweiterungen und klicke beim Plugin auf Konfigurieren.
2. Verkaufskanal wählen: Ganz oben wählst du unter Verkaufskanal, für welchen Shop du gerade einstellst. Mit Alle Verkaufskanäle legst du die Grundeinstellung für alle fest.
3. Funktion auswählen: Entscheide, womit du anfängst:
   • Kundendaten in Zendesk anzeigen → So richtest du die Zendesk-App ein
   • Chat im Shop einblenden → So bindest du den Zendesk-Chat in deinen Shop ein
   • Kontaktanfragen als Ticket anlegen → So werden Kontaktanfragen zu Zendesk-Tickets
4. Speichern: Klicke oben rechts auf Speichern.
5. Ergebnis prüfen: Öffne in Zendesk ein Ticket eines Shop-Kunden, rufe deinen Shop auf oder schicke eine Testnachricht über das Kontaktformular — je nachdem, welche Funktion du eingerichtet hast.

Einstellungen

Die Einstellungen findest du unter Erweiterungen → Meine Erweiterungen → Konfigurieren beim Plugin. Sie sind in fünf Karten gegliedert:

Karte	Wofür	Beschrieben in
Allgemein	Plugin je Verkaufskanal ein- und ausschalten, Dokumentation öffnen	diesem Kapitel
Zendesk-App (Ticket-Seitenleiste)	Kundendaten und Bestellungen in Zendesk anzeigen	So richtest du die Zendesk-App ein
Chat- und Hilfe-Widget	Zendesk-Chat im Shop einblenden	So bindest du den Zendesk-Chat in deinen Shop ein
Messaging-Authentifizierung	Angemeldete Kunden im Chat als verifiziert erkennen	So erkennt Zendesk angemeldete Kunden
Zendesk-API (Tickets aus dem Kontaktformular)	Kontaktanfragen als Zendesk-Ticket anlegen	So werden Kontaktanfragen zu Zendesk-Tickets

Nach jeder Änderung klickst du oben rechts auf Speichern.

Einstellungen je Verkaufskanal

Über die Auswahl Verkaufskanal oben auf der Seite legst du fest, für welchen Shop deine Einstellungen gelten. Unter Alle Verkaufskanäle stellst du die Grundwerte ein. Wählst du einen einzelnen Verkaufskanal, kannst du dort abweichende Werte eintragen — alles, was du dort nicht änderst, übernimmt er aus Alle Verkaufskanäle.

So betreibst du zum Beispiel deinen B2C-Shop mit Chat und Seitenleiste, während dein B2B-Kanal nur Tickets aus dem Kontaktformular an ein anderes Zendesk-Konto schickt.

Eine Ausnahme: Der Zugangsschlüssel für die Zendesk-App gilt immer für den ganzen Shop, egal welcher Verkaufskanal oben gewählt ist. Welche Verkaufskanäle Daten an Zendesk liefern, steuerst du je Verkaufskanal mit einem eigenen Schalter (siehe So richtest du die Zendesk-App ein).

Karte „Allgemein“

Abb. 2: Karte „Allgemein“ mit dem Button zur Dokumentation und dem Hauptschalter

Dokumentation öffnen bringt dich direkt zu dieser Anleitung.

Mit dem Schalter Plugin für diesen Verkaufskanal aktivieren legst du fest, ob das Plugin im gewählten Verkaufskanal überhaupt etwas tut. Schaltest du ihn aus, sind dort alle Zendesk-Funktionen abgeschaltet: das Widget, die Kundendaten in der Zendesk-Seitenleiste und die Tickets aus dem Kontaktformular. Standardmäßig ist er eingeschaltet.

Wozu das gut ist: Du legst einen Verkaufskanal still, ohne die Einstellungen der einzelnen Funktionen anzufassen — zum Beispiel einen Testkanal oder einen Shop, den ein anderes Team betreut.

So richtest du die Zendesk-App ein

Was dir das bringt: Deine Agenten sehen neben jedem Ticket in Zendesk den passenden Shopware-Kunden: Kontaktdaten, Rechnungsadresse, Kennzahlen und alle Bestellungen mit Status, Sendungsnummern und Dokumenten. Die Zendesk-App dafür erzeugt das Plugin selbst — mit deiner Shop-Adresse vorbelegt.

Die Daten bleiben in deinem Shop. Die App holt sie nur dann ab, wenn ein Agent ein Ticket oder einen Benutzer in Zendesk öffnet. Dafür nutzt sie einen Zugangsschlüssel, den du im Shop erzeugst und jederzeit widerrufen kannst.

Wichtig: Für diesen Teil brauchst du einen Zendesk-Tarif mit privaten Apps, und dein Shop muss aus dem Internet über https:// erreichbar sein (siehe Voraussetzungen).

Schritt für Schritt

Alle Schritte im Shop machst du in der Karte Zendesk-App (Ticket-Seitenleiste) unter Verbindung zur Zendesk-App. Dieselben Schritte stehen dort auch in Kurzform unter So richtest du die App in Zendesk ein.

1. Zugangsschlüssel erzeugen. Klicke auf Zugangsschlüssel erzeugen. Der neue Schlüssel erscheint im Feld Neuer Zugangsschlüssel.

2. Schlüssel sofort kopieren. Klicke auf das Kopier-Symbol rechts im Feld und lege den Schlüssel kurz bereit, bis du ihn in Zendesk eingetragen hast. Der Schlüssel wird nur dieses eine Mal angezeigt — Shopware speichert ihn nicht im Klartext. Geht er verloren, erzeugst du einfach einen neuen.

   Abb. 3: Der neue Zugangsschlüssel wird einmalig angezeigt und lässt sich über das Kopier-Symbol kopieren.

3. Shop-Adresse prüfen. Im Feld Shop-Adresse für Zendesk steht bereits die Adresse deines Shops. Sie muss die öffentliche Adresse sein, unter der Zendesk deinen Shop erreicht, und mit https:// beginnen. Passe sie an, wenn du die Administration über eine andere Adresse aufrufst als deine Kunden den Shop.

4. Zendesk-App herunterladen. Klicke auf Zendesk-App herunterladen (ZIP). Dein Browser speichert eine ZIP-Datei — entpacke sie nicht, Zendesk braucht sie genau so.

   Abb. 4: Shop-Adresse, Download der Zendesk-App und die Einrichtungsschritte in Kurzform

5. Admin Center in Zendesk öffnen. Melde dich in Zendesk an und öffne das Admin Center: Apps und Integrationen → Zendesk Support-Apps.

6. Private App hochladen. Wähle Private App hochladen, wähle die ZIP-Datei aus und lade sie hoch.

7. Shop-Adresse und Zugangsschlüssel eintragen. Bei der Installation fragt Zendesk nach zwei Angaben:

   • Shop-Adresse: ist mit der Adresse aus Schritt 3 vorbelegt.
   • Zugangsschlüssel: füge hier den kopierten Schlüssel ein. Er beginnt mit swpzd_.

   Installiere dann die App.

8. Ticket öffnen. Öffne in Zendesk ein Ticket eines Shop-Kunden. In der Seitenleiste erscheint die App Shopware Kunden & Bestellungen und zeigt den Kunden zur E-Mail-Adresse des Anfragenden.

9. Verbindung prüfen. Zurück im Shop zeigt die Karte jetzt den Status Eingerichtet. Unter Letzter Zugriff aus Zendesk siehst du, wann die App zuletzt Daten abgerufen hat. Der Wert wird höchstens alle fünf Minuten aktualisiert.

   Abb. 5: Die Verbindung steht: Status, Ende des Zugangsschlüssels, Erstellungsdatum und letzter Zugriff aus Zendesk

Tipp: Zum Erzeugen des Schlüssels braucht dein Benutzer in der Administration die Berechtigungen, Einstellungen zu bearbeiten sowie Kunden, Bestellungen und Dokumente anzusehen. Fehlen sie, ist der Button ausgegraut und darunter steht ein entsprechender Hinweis.

Welche Verkaufskanäle Daten an Zendesk liefern

Der Zugangsschlüssel gilt für den ganzen Shop. Ob die Kunden und Bestellungen eines Verkaufskanals in Zendesk erscheinen, entscheidest du je Verkaufskanal mit dem Schalter Daten dieses Verkaufskanals in Zendesk anzeigen. Er ist standardmäßig eingeschaltet. Schalte ihn zum Beispiel für einen B2B-Kanal aus, den ein anderes Zendesk-Konto betreut. Ist in einem Verkaufskanal der Hauptschalter Plugin für diesen Verkaufskanal aktivieren aus, liefert dieser Kanal ebenfalls keine Daten.

Was die Seitenleiste zeigen soll

Diese Einstellungen in derselben Karte stellst du ebenfalls je Verkaufskanal ein. Sie gelten für die Kunden und Bestellungen des jeweiligen Kanals.

Zusatzfelder (technische Namen, kommagetrennt): Hier wählst du Kunden-Zusatzfelder aus, die zusätzlich in der Seitenleiste erscheinen, etwa ein VIP-Kennzeichen oder einen Servicehinweis. Trage die technischen Namen der Felder durch Kommas getrennt ein, zum Beispiel custom_customer_vip,custom_customer_note. Den technischen Namen findest du unter Einstellungen → System → Zusatzfelder. In der Seitenleiste erscheint das Feld dann mit seiner Beschriftung.

Angezeigte Bestellungen je Kunde: Legt fest, wie viele Bestellungen die Seitenleiste je Kunde auflistet, neueste zuerst. Möglich sind 1 bis 50, standardmäßig 10. Die Anzahl der Bestellungen und der Umsatz in den Kennzahlen berücksichtigen trotzdem alle Bestellungen, nicht nur die aufgelisteten.

Bestellpositionen anzeigen: Zeigt in jeder Bestellung die bestellten Artikel mit Menge, Artikelnummer und Preis. Standardmäßig eingeschaltet.

Dokumente anzeigen (Rechnungen, Lieferscheine, Gutschriften): Zeigt die Dokumente einer Bestellung. Deine Agenten öffnen das PDF über einen Link, der fünf Minuten gültig ist. Standardmäßig eingeschaltet. Schalte es aus, wenn dein Support keine Rechnungen sehen soll.

So arbeitest du mit der Seitenleiste in Zendesk

Was dir das bringt: Dein Team beantwortet Fragen wie „Wo bleibt mein Paket?“ oder „Schicken Sie mir bitte die Rechnung noch einmal“, ohne die Shopware-Administration zu öffnen.

Die App Shopware Kunden & Bestellungen erscheint in Zendesk in der Seitenleiste von Tickets, neuen Tickets und Benutzern. Sie spricht die Sprache, die der Agent in Zendesk eingestellt hat (Deutsch, Englisch oder Niederländisch, sonst Englisch).

Kunde und Kennzahlen

Beim Öffnen eines Tickets sucht die App automatisch nach der E-Mail-Adresse des Anfragenden, auf einer Benutzerseite nach der E-Mail-Adresse des Benutzers. Änderst du im Ticket den Anfragenden, lädt sie den passenden Kunden neu.

Abb. 6: Seitenleiste mit Kundendaten, Kennzahlen und Bestellungen

Oben siehst du den Kunden mit Kundengruppe und Verkaufskanal, darunter Kundennummer, Kunde seit, E-Mail, Telefon, Firma und USt-IdNr. (falls vorhanden), Sprache, Letzte Anmeldung, die Rechnungsadresse und die Zusatzfelder, die du in den Einstellungen ausgewählt hast. Kennzeichen wie Gast, Bestellung ohne Konto, Newsletter oder Inaktiv zeigen auf einen Blick, mit wem du es zu tun hast.

Unter Kennzahlen stehen Bestellungen (Anzahl), Umsatz (ohne stornierte Bestellungen), Durchschnittlicher Bestellwert und Letzte Bestellung (Datum).

Bestellungen, Sendungsverfolgung und Dokumente

Unter Bestellungen stehen die Bestellungen des Kunden, neueste zuerst, mit Bestellnummer, Datum, Betrag und Status. Rechts oben zeigt „3 von 3“, wie viele Bestellungen aufgelistet sind und wie viele es insgesamt gibt. Klicke auf eine Bestellung, um sie aufzuklappen.

Abb. 7: Aufgeklappte Bestellung mit Status, Sendungsnummer, Positionen und Dokumenten

In der aufgeklappten Bestellung siehst du:

• den Status von Bestellung, Zahlung und Versand,
• Verkaufskanal, Zahlungsart und Versandart,
• die Sendungsnummern — hat die Versandart in Shopware einen Link zur Sendungsverfolgung, ist die Nummer anklickbar,
• die Lieferadresse,
• die Positionen mit Menge, Artikel und Gesamtpreis (falls eingeschaltet),
• die Dokumente wie Lieferschein oder Rechnung (falls eingeschaltet).

Dokument öffnen: Klicke auf ein Dokument. Das PDF öffnet sich in einem neuen Tab. Der Link dahinter gilt aus Sicherheitsgründen nur fünf Minuten. Brauchst du das Dokument später noch einmal, klicke es einfach erneut in der Seitenleiste an. Blockiert dein Browser das neue Fenster, zeigt die App stattdessen einen Link PDF öffnen.

Bestelldaten in die Antwort einfügen

Klicke in einer aufgeklappten Bestellung auf In Antwort einfügen. Die App schreibt Bestellnummer, Bestelldatum, Status, Zahlung, Versand und die Sendungsnummern mit Link in deinen Antworttext. Danach erscheint der Hinweis „In die Antwort eingefügt.“

Den Button gibt es nur in Tickets. Auf einer Benutzerseite gibt es keine Antwort, in die etwas eingefügt werden könnte.

In die Administration springen

Mit Kunde in Shopware öffnen und Bestellung in Shopware öffnen springst du direkt zum Kunden bzw. zur Bestellung in deiner Shopware-Administration. Dafür musst du in der Administration angemeldet sein. Die Seitenleiste selbst zeigt Daten nur an — Änderungen an Bestellungen machst du weiterhin in der Administration.

Nach E-Mail-Adresse, Bestell- oder Kundennummer suchen

Oben in der Seitenleiste steht ein Suchfeld. Gib eine E-Mail-Adresse, eine Bestellnummer oder eine Kundennummer ein und klicke auf die Lupe daneben (Suchen) oder drücke die Eingabetaste. Das hilft zum Beispiel, wenn der Kunde von einer anderen E-Mail-Adresse schreibt als der, mit der er bestellt hat.

Suchst du nach einer Bestellnummer, zeigt die Seitenleiste den Kunden zu dieser Bestellung und öffnet die passende Bestellung gleich mit — du musst sie nicht erst in der Liste suchen.

Abb. 8: Suche nach Bestellnummer öffnet die passende Bestellung

Mehrere Treffer

Gibt es mehrere passende Kunden — etwa ein Kundenkonto in zwei Verkaufskanälen oder ein Kundenkonto und frühere Gastbestellungen —, erscheint oben eine Auswahl Treffer. Damit schaltest du zwischen den Kunden um. Die Seitenleiste zeigt höchstens zehn Treffer. Gibt es mehr, erscheint der Hinweis „Es gibt weitere Treffer. Bitte die Suche verfeinern.“ Suche dann zum Beispiel nach der Bestell- oder Kundennummer.

Tipp: Die Seitenleiste zeigt nur Kunden und Bestellungen aus Verkaufskanälen, für die Daten dieses Verkaufskanals in Zendesk anzeigen eingeschaltet ist.

So erneuerst oder widerrufst du den Zugangsschlüssel

Was dir das bringt: Du behältst die Kontrolle darüber, wer aus Zendesk auf deine Kundendaten zugreift. Ist ein Schlüssel in falsche Hände geraten oder beendest du die Zusammenarbeit mit Zendesk, sperrst du den Zugriff sofort.

Schlüssel erneuern

1. Klicke in der Karte Zendesk-App (Ticket-Seitenleiste) auf Zugangsschlüssel erneuern.

2. Bestätige die Rückfrage mit Schlüssel erneuern.

   Abb. 9: Rückfrage vor dem Erneuern des Zugangsschlüssels

3. Kopiere den neuen Schlüssel aus dem Feld Neuer Zugangsschlüssel — er wird auch diesmal nur einmal angezeigt.

4. Öffne in Zendesk die Einstellungen der App Shopware Kunden & Bestellungen und ersetze dort den alten Schlüssel durch den neuen.

Wichtig: Der bisherige Schlüssel ist sofort ungültig. Bis du den neuen Schlüssel in den Einstellungen der Zendesk-App einträgst, zeigt die App keine Daten an.

Schlüssel widerrufen

1. Klicke auf Zugangsschlüssel widerrufen.
2. Bestätige die Rückfrage mit Schlüssel widerrufen.

Die Zendesk-App verliert sofort den Zugriff auf Kunden-, Bestell- und Dokumentdaten. Auch bereits erzeugte Dokument-Links werden ungültig. Der Status springt auf Nicht eingerichtet. Willst du die Seitenleiste später wieder nutzen, erzeugst du einen neuen Schlüssel und trägst ihn in Zendesk ein.

So bindest du den Zendesk-Chat in deinen Shop ein

Was dir das bringt: Deine Besucher erreichen deinen Kundenservice direkt im Shop über den Chat von Zendesk. Das Plugin unterstützt Zendesk Messaging und das Classic Web Widget, lädt den Chat auf Wunsch erst nach Cookie-Zustimmung und blendet ihn auf Seiten aus, auf denen er stören würde.

Alle Einstellungen findest du in der Karte Chat- und Hilfe-Widget. Sie gelten je Verkaufskanal.

Abb. 10: Karte „Chat- und Hilfe-Widget“

Schritt für Schritt

1. Schlüssel aus Zendesk holen. Öffne im Zendesk Admin Center Kanäle → Messaging (beim Classic Web Widget Classic → Web Widget) und kopiere den Schlüssel oder gleich das komplette Code-Snippet.
2. Chat einschalten. Schalte Zendesk-Widget im Shop anzeigen ein. Standardmäßig ist der Chat aus.
3. Schlüssel einfügen. Füge im Feld Zendesk-Schlüssel oder Snippet den Schlüssel oder das komplette Snippet ein. Das Plugin übernimmt daraus nur den Schlüssel und lädt das Zendesk-Script selbst. So landet kein fremder Code aus der Konfiguration in deinem Shop.
4. Widget-Art wählen. Wähle unter Widget-Art entweder Messaging (Web Widget) oder Classic Web Widget. Die Auswahl muss zur Widget-Art des Schlüssels in Zendesk passen.
5. Speichern und den Shop in einem neuen Browserfenster aufrufen.

Wichtig: Erkennt das Plugin im Feld Zendesk-Schlüssel oder Snippet keinen gültigen Schlüssel, zeigt der Shop keinen Chat an.

Seiten ausschließen

Unter Nicht anzeigen auf wählst du Seiten aus, auf denen der Chat nicht erscheinen soll: Startseite, Kategorieseiten, Produktseiten, Suchergebnisse, Warenkorb und Kasse, Kundenkonto und Landingpages. Lässt du die Auswahl leer, erscheint der Chat auf allen Seiten.

Wozu das gut ist: Viele Shops blenden den Chat in Warenkorb und Kasse aus, damit nichts vom Bestellabschluss ablenkt.

Cookie-Zustimmung und Hilfe-Button

Mit Erst nach Cookie-Zustimmung laden (standardmäßig eingeschaltet) erscheint in den Cookie-Einstellungen deines Shops unter Komfortfunktionen ein eigener Eintrag Zendesk-Chat. Das Zendesk-Script lädt erst, wenn der Besucher dort zugestimmt hat. Nimmt er die Zustimmung später zurück, blendet der Shop den Chat wieder aus.

Abb. 11: Eintrag „Zendesk-Chat“ in den Cookie-Einstellungen unter „Komfortfunktionen“

Mit Hilfe-Button bis zur Zustimmung zeigen (standardmäßig eingeschaltet) sehen Besucher ohne Zustimmung unten rechts trotzdem einen Chat-Button. So geht kein Kontakt verloren, nur weil jemand den Cookie-Hinweis weggeklickt hat.

Abb. 12: Hilfe-Button unten rechts, solange keine Zustimmung vorliegt

Ein Klick auf den Button öffnet einen Hinweis Kundenservice-Chat. Er erklärt, dass für den Chat eine Verbindung zu Zendesk aufgebaut wird. Mit Chat laden stimmt der Besucher zu, und der Chat öffnet sich. Cookie-Einstellungen führt zu den Cookie-Einstellungen des Shops.

Abb. 13: Hinweis mit „Chat laden“ und „Cookie-Einstellungen“

Der Hilfe-Button wirkt nur, solange Erst nach Cookie-Zustimmung laden eingeschaltet ist.

Wichtig: Schaltest du Erst nach Cookie-Zustimmung laden aus, lädt das Zendesk-Script sofort auf jeder Seite, auf der der Chat erscheint. Kläre vorher, ob das für deinen Shop zulässig ist.

Sprache

Der Chat erscheint in der Sprache, in der der Besucher deinen Shop gerade nutzt. Du musst dafür nichts einstellen.

Name und E-Mail vorausfüllen (nur Classic)

Mit Name und E-Mail angemeldeter Kunden vorausfüllen (Classic) trägt das Classic Web Widget Name und E-Mail-Adresse eines angemeldeten Kunden schon ein. Der Kunde muss sie nicht noch einmal tippen. Standardmäßig ist das aus. Bei Messaging wirkt der Schalter nicht — dort nutzt du stattdessen die Messaging-Authentifizierung.

Gesprächs-Tags (nur Messaging)

Im Feld Gesprächs-Tags (kommagetrennt, Messaging) trägst du Tags ein, die Zendesk an jedes Gespräch hängt, das in diesem Verkaufskanal beginnt, zum Beispiel shop-de. Damit sortierst du Chats in Zendesk nach Shop oder Land.

So erkennt Zendesk angemeldete Kunden

Was dir das bringt: Ist ein Kunde in deinem Shop angemeldet, bestätigt der Shop Zendesk seine Identität. Deine Agenten sehen das Gespräch dann beim richtigen Kunden — mit Name und E-Mail-Adresse, die aus dem Kundenkonto stammen und nicht frei eingetippt wurden.

Diese Funktion gibt es nur für die Widget-Art Messaging (Web Widget).

Abb. 14: Karte „Messaging-Authentifizierung“

Schritt für Schritt

1. In Zendesk vorbereiten. Richte im Zendesk Admin Center unter Konto → Sicherheit die Endbenutzer-Authentifizierung für Messaging ein und lege dort einen Schlüssel an. Zendesk zeigt dir dazu eine Schlüssel-ID und ein gemeinsames Geheimnis.
2. Schalter einschalten. Schalte in der Karte Messaging-Authentifizierung den Schalter Angemeldete Kunden in Zendesk verifizieren ein.
3. Schlüssel-ID eintragen. Trage die Schlüssel-ID aus Zendesk unter Schlüssel-ID (kid) ein.
4. Geheimnis eintragen. Trage das Geheimnis aus Zendesk unter Gemeinsames Geheimnis ein.
5. Speichern.

Ab jetzt meldet der Shop angemeldete Kunden beim Chat an. Meldet sich ein Kunde im Shop ab, meldet ihn der Shop auch im Chat wieder ab. Besucher ohne Anmeldung chatten wie bisher als Gast.

Wichtig: Die Funktion greift nur, wenn der Schalter an ist und Schlüssel-ID und Geheimnis eingetragen sind. Fehlt eines davon, läuft der Chat ohne Verifizierung weiter.

So werden Kontaktanfragen zu Zendesk-Tickets

Was dir das bringt: Jede Nachricht, die ein Kunde über das Kontaktformular deines Shops schickt, landet als Ticket in Zendesk — dort, wo dein Support ohnehin arbeitet. Das Ticket steht im Namen des Kunden, sodass deine Antwort direkt an ihn geht.

Alle Einstellungen findest du in der Karte Zendesk-API (Tickets aus dem Kontaktformular). Sie gelten je Verkaufskanal. So kann jeder Verkaufskanal seine Anfragen auch an ein eigenes Zendesk-Konto schicken.

Abb. 15: Karte „Zendesk-API“ mit Verbindungstest — hier mit unvollständigen Zugangsdaten

Schritt für Schritt

1. API-Token in Zendesk anlegen. Öffne im Zendesk Admin Center Apps und Integrationen → APIs → Zendesk-API und wähle API-Token hinzufügen. Kopiere das Token.
2. Zendesk-Subdomain eintragen. Trage unter Zendesk-Subdomain den Namen deines Zendesk-Kontos ein, zum Beispiel meinefirma aus meinefirma.zendesk.com. Die vollständige Adresse wird ebenfalls angenommen.
3. E-Mail-Adresse eintragen. Trage unter E-Mail-Adresse des API-Benutzers die E-Mail-Adresse des Agenten- oder Admin-Kontos ein, zu dem das API-Token gehört.
4. Token eintragen. Füge das Token unter API-Token ein.
5. Verbindung testen. Klicke auf Verbindung testen. Geprüft werden die gerade eingetragenen Werte des gewählten Verkaufskanals, auch wenn du sie noch nicht gespeichert hast. Klappt es, erscheint Verbindung erfolgreich mit dem Namen und der Rolle des Zendesk-Benutzers. Andernfalls erscheint Verbindung fehlgeschlagen mit dem Grund (siehe Fehlerbehebung).
6. Tickets einschalten. Schalte Kontaktanfragen als Zendesk-Ticket anlegen ein. Standardmäßig ist das aus.
7. Speichern und eine Testnachricht über das Kontaktformular deines Shops schicken.

Was im Ticket steht

Zendesk legt das Ticket im Namen des Kunden an. Übertragen werden Name, E-Mail-Adresse, Betreff und Nachricht. Hat der Kunde eine Telefonnummer angegeben, steht sie unter der Nachricht. Kennt Zendesk die E-Mail-Adresse schon, landet das Ticket bei diesem Benutzer, sonst legt Zendesk ihn neu an.

Die gewohnte E-Mail aus dem Kontaktformular verschickt Shopware weiterhin unverändert.

Tags, Priorität und interne Notiz

Ticket-Tags (kommagetrennt): Diese Tags bekommt jedes Ticket aus dem Kontaktformular. Voreingestellt sind shopware, kontaktformular. Damit filterst du die Anfragen in Zendesk in eine eigene Ansicht. Tags kommen in Kleinbuchstaben bei Zendesk an; Leerzeichen innerhalb eines Tags werden zu Unterstrichen.

Ticket-Priorität: Wähle Niedrig, Normal, Hoch oder Dringend, wenn Tickets aus dem Kontaktformular eine feste Priorität bekommen sollen. Mit Nicht setzen (Standard) bleibt die Priorität so, wie Zendesk sie vergibt.

Interne Notiz mit Kundendaten anhängen: Hängt an jedes Ticket eine Notiz, die nur deine Agenten sehen — nicht der Kunde. Sie nennt den Verkaufskanal, die Kundennummer, die Anzahl der Bestellungen, den Umsatz ohne Stornierungen und einen Link zum Kunden in der Administration. Gibt es zu der E-Mail-Adresse kein Kundenkonto in diesem Verkaufskanal, steht das in der Notiz. Standardmäßig eingeschaltet.

Was bei einer Störung bei Zendesk passiert

Die Anfrage geht im Hintergrund an Zendesk — das Kontaktformular wird für deine Kunden also nicht langsamer, und der Kunde merkt von einer Störung nichts.

• Vorübergehende Störung (Zendesk nicht erreichbar, überlastet oder begrenzt gerade die Anfragen): Das Plugin versucht es automatisch erneut, in wachsenden Abständen über rund acht Stunden. Nennt Zendesk eine Wartezeit, hält sich das Plugin daran. Ein Kennzeichen, das Zendesk wiedererkennt, schützt dabei vor doppelten Tickets.
• Dauerhafter Fehler (zum Beispiel ein ungültiges API-Token oder eine falsche Subdomain): Das Plugin versucht es nicht erneut, weil ein neuer Versuch am Ergebnis nichts ändern würde.

Klappt es auch nach dem letzten Versuch nicht, oder liegt ein dauerhafter Fehler vor, legt Shopware die Anfrage in seinem Speicher für fehlgeschlagene Nachrichten ab. Von dort kann dein technischer Administrator sie erneut senden, sobald die Ursache behoben ist (siehe Technische Details). Die Kontaktformular-E-Mail an dich ist davon nicht betroffen.

Wichtig: Tickets verschickt das Plugin über die Hintergrundverarbeitung von Shopware. Läuft sie nicht, kommen keine Tickets in Zendesk an (siehe Fehlerbehebung).

Datenschutz

An Zendesk gehen nur Daten der Funktionen, die du einschaltest. Ohne eingeschaltete Funktion überträgt das Plugin nichts.

Funktion	Welche Daten	Wann
Seitenleiste in Zendesk	Kundendaten (Name, Kontaktdaten, Rechnungsadresse, Kundengruppe, ausgewählte Zusatzfelder, Kennzahlen) und Bestelldaten (Status, Zahlungs- und Versandart, Sendungsnummern, Lieferadresse, Positionen, Dokumente)	nur wenn ein Agent in Zendesk ein Ticket oder einen Benutzer öffnet oder sucht; nichts wird auf Vorrat übertragen
Chat im Shop	technische Daten wie die IP-Adresse des Besuchers	sobald das Zendesk-Script im Browser lädt — standardmäßig erst nach Zustimmung
Chat mit Vorausfüllen (Classic) oder Messaging-Authentifizierung	Name und E-Mail-Adresse angemeldeter Kunden, bei der Authentifizierung zusätzlich eine Kunden-Kennung	wenn ein angemeldeter Kunde den Chat nutzt
Tickets aus dem Kontaktformular	Name, E-Mail-Adresse, Telefonnummer, Betreff und Nachricht; mit interner Notiz zusätzlich Verkaufskanal, Kundennummer, Anzahl der Bestellungen und Umsatz	wenn ein Kunde das Kontaktformular abschickt

Cookie-Zustimmung: Mit Erst nach Cookie-Zustimmung laden erscheint der Chat als Zendesk-Chat in der Gruppe Komfortfunktionen der Cookie-Einstellungen. Die Entscheidung des Besuchers bleibt 30 Tage gespeichert.

Was du selbst erledigen musst:

• Nenne Zendesk in deiner Datenschutzerklärung, mit den Funktionen, die du nutzt.
• Für die Übermittlung an Zendesk brauchst du die übliche Grundlage, in der Regel einen Vertrag zur Auftragsverarbeitung mit Zendesk.

Diese Hinweise sind keine Rechtsberatung. Bitte prüfe die Nutzung in Abstimmung mit einem qualifizierten Rechtsbeistand.

Fehlerbehebung

Meldungen in der Zendesk-Seitenleiste

„App nicht eingerichtet“ In den Einstellungen der App in Zendesk fehlt die Shop-Adresse. Trage sie dort ein, beginnend mit https://.

„Kein Zugangsschlüssel im Shop“ Im Shop wurde noch kein Zugangsschlüssel erzeugt oder er wurde widerrufen. Erzeuge ihn wie in So richtest du die Zendesk-App ein beschrieben und trage ihn in den Einstellungen der App in Zendesk ein.

„Zugangsschlüssel ungültig“ Der Schlüssel wurde in Shopware erneuert oder widerrufen. Trage den aktuellen Schlüssel in den Einstellungen der App in Zendesk ein. Diese Meldung erscheint auch, wenn dein Shop hinter einem Verzeichnisschutz liegt und eine Passwortabfrage die Anfrage aus Zendesk abweist — dann hilft ein neuer Schlüssel nicht, sondern nur ein Shop ohne Passwortabfrage.

„Shop nicht erreichbar“ Shopware hat nicht geantwortet. Prüfe die Shop-Adresse in den App-Einstellungen in Zendesk: Sie muss die öffentliche Adresse deines Shops sein, mit https://. Prüfe auch, ob das Plugin im Shop installiert und aktiv ist. Klicke dann auf Erneut versuchen.

„Anfrage fehlgeschlagen“ Die Daten konnten nicht geladen werden. Klicke auf Erneut versuchen. Tritt der Fehler dauerhaft auf, wende dich an deinen technischen Administrator.

„Kein Kunde gefunden“ Zur gesuchten E-Mail-Adresse oder Nummer gibt es in den freigegebenen Verkaufskanälen keinen Kunden und keine Bestellung. Prüfe:

• Ist im Verkaufskanal des Kunden Daten dieses Verkaufskanals in Zendesk anzeigen eingeschaltet — und dort auch Plugin für diesen Verkaufskanal aktivieren?
• Schreibt der Kunde von einer anderen E-Mail-Adresse? Hat ein Kunde seine E-Mail-Adresse im Shop geändert, findet die Seitenleiste ihn nur noch über die neue Adresse. Schreibt er von der alten Adresse, suche im Suchfeld nach seiner Kundennummer oder einer Bestellnummer.

„Dieses Ticket hat noch keine E-Mail-Adresse des Anfragenden.“ Das Ticket hat noch keinen Anfragenden mit E-Mail-Adresse. Suche im Suchfeld nach E-Mail, Bestell- oder Kundennummer.

„Diese App-Version (…) passt nicht zum Plugin (…).“ Das Plugin wurde aktualisiert, die App in Zendesk aber nicht. Lade die App in Shopware über Zendesk-App herunterladen (ZIP) neu herunter und lade sie in Zendesk als Update der bestehenden privaten App hoch.

„Das Dokument konnte nicht geöffnet werden.“ Klicke das Dokument in der Seitenleiste erneut an — die App holt dabei einen frischen Link. Hilft das nicht, prüfe, ob das Dokument in der Bestellung in der Administration noch vorhanden ist.

„Der Text konnte nicht in die Antwort eingefügt werden.“ Klicke in das Antwortfeld des Tickets und versuche es erneut.

Meldungen beim Einrichten im Shop

Der Button „Zugangsschlüssel erzeugen“ ist ausgegraut. Deinem Benutzer fehlen Berechtigungen. Zum Erzeugen des Schlüssels brauchst du die Berechtigungen, Einstellungen zu bearbeiten sowie Kunden, Bestellungen und Dokumente anzusehen. Ein Administrator kann sie dir über deine Benutzerrolle geben.

„Dir fehlt die Berechtigung, Einstellungen anzusehen. Die Zendesk-App kannst du deshalb nicht einrichten.“ Auch hier fehlt deinem Benutzer eine Berechtigung. Wende dich an einen Administrator.

„Die Shop-Adresse muss mit https:// beginnen und darf keine Parameter enthalten.“ Korrigiere die Shop-Adresse für Zendesk: mit https:// am Anfang und ohne ? oder # dahinter. Erst dann lässt sich die App herunterladen.

„Das Zendesk-App-Paket konnte nicht erstellt werden.“ Beim Erzeugen der ZIP-Datei ist ein Fehler aufgetreten. Die Details stehen im Plugin-Log — gib diese Meldung an deinen technischen Administrator weiter.

Fehlermeldungen beim Verbindungstest

„Bitte Zendesk-Subdomain, E-Mail-Adresse und API-Token eintragen.“ Eines der drei Felder ist leer. Fülle alle drei aus.

„Die Zendesk-Subdomain ist ungültig. Beispiel: meinefirma oder meinefirma.zendesk.com.“ Prüfe die Schreibweise der Zendesk-Subdomain.

„Unter dieser Subdomain gibt es kein Zendesk-Konto.“ Die Subdomain ist falsch geschrieben oder gehört zu keinem Zendesk-Konto. Vergleiche sie mit der Adresse, unter der du Zendesk aufrufst.

„Zendesk hat die Anmeldung abgelehnt. Bitte E-Mail-Adresse und API-Token prüfen.“ Die E-Mail-Adresse gehört nicht zum Benutzer des API-Tokens, das Token ist falsch kopiert oder wurde in Zendesk gelöscht. Lege bei Bedarf ein neues Token an.

„Zendesk begrenzt gerade die Anfragen. Bitte in einer Minute erneut versuchen.“ Warte eine Minute und teste dann erneut.

„Zendesk ist nicht erreichbar. Bitte später erneut versuchen.“ Zendesk oder die Verbindung dorthin ist gerade gestört. Teste später erneut.

Der Chat erscheint nicht im Shop

Woran es liegen kann und was du prüfst:

1. Ist im Verkaufskanal Plugin für diesen Verkaufskanal aktivieren und Zendesk-Widget im Shop anzeigen eingeschaltet?
2. Steht im Feld Zendesk-Schlüssel oder Snippet ein gültiger Schlüssel? Kopiere ihn bei Zweifel erneut aus Zendesk.
3. Passt die Widget-Art zum Schlüssel in Zendesk?
4. Ist die aktuelle Seite unter Nicht anzeigen auf ausgewählt?
5. Ist Erst nach Cookie-Zustimmung laden eingeschaltet und hast du der Gruppe Komfortfunktionen bzw. dem Zendesk-Chat noch nicht zugestimmt? Dann erscheint nur der Hilfe-Button — oder gar nichts, wenn Hilfe-Button bis zur Zustimmung zeigen ausgeschaltet ist.
6. Leere den Cache: Einstellungen → System → Caches & Indizes → Cache leeren.

Kontaktanfragen kommen nicht als Ticket in Zendesk an

1. Ist im Verkaufskanal Plugin für diesen Verkaufskanal aktivieren und Kontaktanfragen als Zendesk-Ticket anlegen eingeschaltet?
2. Meldet Verbindung testen im gleichen Verkaufskanal Verbindung erfolgreich?
3. Läuft die Hintergrundverarbeitung deines Shops? Tickets werden über die Nachrichten-Warteschlange von Shopware verschickt. Wie in jedem Shopware-Shop muss dafür die Hintergrundverarbeitung laufen — entweder über die Administration (Admin-Worker) oder über einen eigenen Prozess auf dem Server. Läuft sie nicht, bleiben die Anfragen in der Warteschlange liegen. Frag im Zweifel deinen technischen Administrator oder Hoster.
4. Gab es eine Störung bei Zendesk? Dann versucht das Plugin es noch über mehrere Stunden erneut (siehe Was bei einer Störung bei Zendesk passiert).
5. Ist die Warteschlange in deinem Shop auf sofortige (synchrone) Verarbeitung gestellt, versucht das Plugin es bei einer Zendesk-Störung höchstens zweimal und schreibt einen Hinweis ins Plugin-Log. Die Kontaktanfrage selbst kommt trotzdem wie gewohnt per E-Mail bei dir an, und dein Kunde sieht keine Fehlermeldung. Für die automatische Wiederholung über mehrere Stunden braucht es die übliche Hintergrundverarbeitung — sprich das mit deinem technischen Administrator ab.

Das Plugin erscheint nicht unter Meine Erweiterungen oder ist nicht aktiv

1. Öffne Erweiterungen → Meine Erweiterungen.
2. Prüfe, ob das Plugin installiert ist und der Schalter neben dem Eintrag eingeschaltet ist.
3. Leere den Cache: Einstellungen → System → Caches & Indizes → Cache leeren.

FAQ

F: Welchen Zendesk-Tarif brauche ich?

A: Für die Seitenleiste einen Tarif mit privaten Apps, also Suite Growth oder höher bzw. Support Professional oder höher. Chat und Tickets aus dem Kontaktformular brauchen keine private App.

F: Funktioniert die Seitenleiste, wenn mein Shop hinter einem Verzeichnisschutz liegt?

A: Nein. Zendesk ruft die Daten über das Internet bei deinem Shop ab, eine Passwortabfrage blockiert das. Chat und Tickets aus dem Kontaktformular funktionieren trotzdem.

F: Kann ich Bestellungen direkt aus Zendesk ändern?

A: Nein. Die Seitenleiste zeigt Daten nur an. Mit Bestellung in Shopware öffnen springst du zur Bestellung in der Administration.

F: Findet die Seitenleiste auch Gastbestellungen?

A: Ja. Gastkonten sind mit Gast gekennzeichnet, Bestellungen ohne Kundenkonto mit Bestellung ohne Konto.

F: Ein Kunde hat seine E-Mail-Adresse geändert und schreibt von der alten. Warum findet die Seitenleiste ihn nicht?

A: Die Seitenleiste sucht über die E-Mail-Adresse, die aktuell im Kundenkonto steht. Suche in diesem Fall nach seiner Kundennummer oder einer Bestellnummer.

F: Gilt der Zugangsschlüssel für alle Verkaufskanäle?

A: Ja, es gibt genau einen Zugangsschlüssel für den ganzen Shop. Welche Verkaufskanäle Daten liefern, legst du je Verkaufskanal mit Daten dieses Verkaufskanals in Zendesk anzeigen fest.

F: Kann ich mehrere Zendesk-Konten anbinden?

A: Für die Tickets aus dem Kontaktformular ja: Trage im jeweiligen Verkaufskanal eigene Zugangsdaten ein. Die Seitenleiste nutzt einen Zugangsschlüssel für den ganzen Shop; schalte dort für jeden Verkaufskanal einzeln, ob seine Daten erscheinen.

F: Mein Shop ist umgezogen und hat eine neue Adresse. Was muss ich tun?

A: Trage die neue Adresse in der Karte Zendesk-App (Ticket-Seitenleiste) unter Shop-Adresse für Zendesk ein, lade die App neu herunter und lade sie in Zendesk als Update hoch. Trage die neue Adresse auch in den Einstellungen der App in Zendesk ein.

F: Muss ich die Zendesk-App nach einem Plugin-Update neu hochladen?

A: Wenn die Seitenleiste meldet, dass die App-Version nicht zum Plugin passt, ja: neu herunterladen und in Zendesk als Update hochladen.

F: Bekomme ich die E-Mail aus dem Kontaktformular weiterhin?

A: Ja. Das Plugin legt das Ticket zusätzlich an. Die gewohnte E-Mail verschickt Shopware unverändert.

F: Kann ich den Chat nur in einem Verkaufskanal anzeigen?

A: Ja. Schalte Zendesk-Widget im Shop anzeigen nur in diesem Verkaufskanal ein.

F: Macht der Chat meinen Shop langsamer?

A: Das Zendesk-Script bringt sein eigenes Gewicht mit. Es lädt deshalb nur, wenn du das Widget einschaltest — und standardmäßig erst nach Zustimmung des Besuchers.

F: Was passiert mit meinen Daten, wenn ich das Plugin deinstalliere?

A: Das Plugin legt keine eigenen Tabellen an. Entfernst du bei der Deinstallation auch die Plugin-Daten, löscht es den Zugangsschlüssel, und die Zendesk-App verliert sofort den Zugriff. Tickets und Gespräche in Zendesk bleiben dort erhalten.

Für Administratoren / Technische Details

Dieser Abschnitt richtet sich an technische Administratoren. Für die normale Nutzung brauchst du ihn nicht.

Systemanforderungen

• Shopware: 6.7, ab Version 6.7.3 (der Eintrag in den Cookie-Einstellungen nutzt eine Schnittstelle, die es erst ab 6.7.3 gibt)
• PHP: 8.2 oder neuer
• Seitenleiste: Shop öffentlich per https:// erreichbar, ohne Verzeichnisschutz
• Tickets aus dem Kontaktformular: laufende Hintergrundverarbeitung (Admin-Worker oder messenger:consume)

Installation über die Kommandozeile

php bin/console plugin:refresh
php bin/console plugin:install --activate SwpZenDeskSix
php bin/console cache:clear

Zendesk-App und Zugangsschlüssel

• Die App ist eine private Zendesk-App (Zendesk Apps Framework 2.0) für die Seitenleiste von Tickets, neuen Tickets und Benutzern. Das Paket enthält die Shop-Adresse als Vorbelegung und erlaubt Anfragen nur an den Host dieser Adresse.
• Der Zugangsschlüssel beginnt mit swpzd_ und wird nur einmal angezeigt. Gespeichert werden ausschließlich ein SHA-256-Hash, die letzten Zeichen als Hinweis, das Erstellungsdatum und der letzte Zugriff — im Key-Value-Speicher von Shopware, nicht in der Systemkonfiguration. Der letzte Zugriff wird höchstens alle fünf Minuten geschrieben.
• Zendesk schickt den Schlüssel über seinen Anfrage-Proxy im Header X-Swp-Zendesk-Key. Der Agent sieht ihn nie im Klartext.
• Dokument-Links sind mit HMAC-SHA256 signiert und 300 Sekunden gültig. Widerrufen des Schlüssels macht bestehende Links ungültig.
• Die Seitenleiste liefert nur Datensätze aus Verkaufskanälen, in denen der Hauptschalter und „Daten dieses Verkaufskanals in Zendesk anzeigen“ eingeschaltet sind. Je Suche höchstens zehn Treffer.

Methode	Route	Zugriff
GET	/api/swp-zendesk/sidebar/ping	Zugangsschlüssel
GET	/api/swp-zendesk/sidebar/lookup	Zugangsschlüssel
GET	/api/swp-zendesk/sidebar/document-link	Zugangsschlüssel
GET	/api/swp-zendesk/document/{documentId}	signierter Link
GET	/api/_action/swp-zendesk/sidebar/status	Admin, Einstellungen lesen
POST	/api/_action/swp-zendesk/sidebar/token	Admin, Einstellungen bearbeiten + Kunden, Bestellungen, Dokumente lesen
DELETE	/api/_action/swp-zendesk/sidebar/token	Admin, Einstellungen bearbeiten
POST	/api/_action/swp-zendesk/sidebar/app-package	Admin, Einstellungen lesen
POST	/api/_action/swp-zendesk/api-test	Admin, Einstellungen lesen

Die Seitenleisten-Routen liegen unter /api, brauchen aber keine Admin-Anmeldung: Sie prüfen ausschließlich den Zugangsschlüssel bzw. die Signatur und antworten mit Cache-Control: no-store.

Tickets aus dem Kontaktformular

• Beim Absenden des Kontaktformulars legt das Plugin eine Nachricht in die Message Queue; im Kundenaufruf selbst findet kein Aufruf bei Zendesk statt.
• Der Handler ruft die Zendesk-API unter https://<subdomain>.zendesk.com/api/v2/ auf (Benutzer suchen bzw. anlegen, Ticket anlegen, interne Notiz). Der Verbindungstest nutzt GET /api/v2/users/me.json.
• Jedes Ticket trägt einen Idempotency-Key, der über alle Versuche gleich bleibt. Existiert das Ticket schon, ergänzt ein weiterer Versuch nur noch die Notiz. Zendesk erkennt den Schlüssel zwei Stunden lang wieder: Ging die Antwort auf ein erfolgreiches Anlegen verloren und scheitern alle Versuche danach länger als zwei Stunden, kann in seltenen Fällen ein zweites Ticket entstehen.
• Wiederholung bei vorübergehenden Fehlern (HTTP 429, 5xx, Netzwerkfehler): bis zu acht weitere Versuche nach 1, 2, 5, 10 und 30 Minuten sowie 1, 2 und 4 Stunden. Bei 429 gilt die Wartezeit aus Retry-After, begrenzt auf 30 Sekunden bis 1 Stunde.
• Keine Wiederholung bei dauerhaften Fehlern (HTTP 400, 401, 403, 404, 422).
• Synchrone Verarbeitung: Ist die Message Queue auf synchrone Verarbeitung gestellt (Transport sync://), greifen die Wartezeiten nicht. Das Plugin versucht es dann bei einer Zendesk-Störung höchstens zweimal und schreibt ins Plugin-Log: Message transport ignores delays; ticket retries stop — configure an asynchronous transport. Stelle in diesem Fall auf einen asynchronen Transport um.
• Nach dem letzten Versuch bzw. bei dauerhaften Fehlern landet die Nachricht im Transport für fehlgeschlagene Nachrichten:

php bin/console messenger:failed:show
php bin/console messenger:failed:retry

• Hintergrundverarbeitung starten, falls kein Admin-Worker läuft:

php bin/console messenger:consume async

Chat-Widget

• Das Plugin lädt https://static.zdassets.com/ekr/snippet.js?key=<Schlüssel> selbst; aus dem eingefügten Snippet wird nur der Schlüssel übernommen.
• Konfiguration und Kundendaten stehen nie im gecachten HTML. Name, E-Mail und das Token für die Messaging-Authentifizierung holt das Storefront-Script per eigener Anfrage (Storefront-Route /swp-zendesk/widget-identity, ohne HTTP-Cache).
• Messaging-Authentifizierung: JSON Web Token (HS256) mit der Schlüssel-ID im Kopf, 15 Minuten gültig, Kunden-ID als external_id.
• Cookie für die Zustimmung: swp-zendesk-widget, 30 Tage, Gruppe Komfortfunktionen.

Headless / Store API

Das Plugin liefert keine CMS-Bausteine. Für eigene Frontends (z. B. Composable Frontends) stehen die Widget-Daten über die Store API bereit — dieselben Routen nutzt auch die Storefront:

Methode	Route	Zweck
GET	/store-api/swp-zendesk/widget-config	Widget-Einstellungen des Verkaufskanals (Schlüssel, Script-Adresse, Widget-Art, Sprache, ausgeschlossene Seiten, Zustimmung, Tags); ohne HTTP-Cache
POST	/store-api/swp-zendesk/widget-identity	Identität des angemeldeten Kunden, bei Messaging-Authentifizierung mit frischem Token (15 Minuten)

Ablauf im eigenen Frontend: widget-config abrufen; bei aktivem Widget das Script mit id="ze-snippet" laden — bei Zustimmungspflicht erst nach Zustimmung zum genannten Cookie. Danach Sprache und Tags setzen; bei Messaging-Authentifizierung zE('messenger', 'loginUser', …) mit dem Token aus widget-identity, nach dem Abmelden zE('messenger', 'logoutUser'). Kundendaten liefert ausschließlich die POST-Route.

Logdatei

Das Plugin schreibt in eine eigene Logdatei im Log-Verzeichnis von Shopware: var/log/SwpZenDeskSix-<Datum>.log. Sie enthält keine personenbezogenen Daten. Hinweise zu Tickets aus dem Kontaktformular (angelegt, wird wiederholt, endgültig fehlgeschlagen) findest du dort ebenso wie Fehler beim Erzeugen des App-Pakets.

Deinstallation

Das Plugin legt keine eigenen Tabellen und keine Migrationen an. Entfernst du beim Deinstallieren auch die Plugin-Daten, löscht es Hash, Hinweis und Zeitstempel des Zugangsschlüssels aus dem Key-Value-Speicher. Behältst du die Daten, bleibt der Schlüssel für eine spätere Neuinstallation gültig.

---

Diese Anleitung wurde für Zendesk Integration Version 6.7.0 erstellt.