Eigenes Widget in Zoho CRM entwickeln, Schritt für Schritt

Ein eigenes Widget in Zoho CRM entwickeln Sie in fünf Schritten. Sie legen den Einsatzort fest, setzen das Projekt mit dem JS SDK auf und binden die Seitendaten an. Danach testen Sie das Widget und laden das Paket unter Setup > Developer Hub > Widgets hoch. Zum Schluss verknüpfen Sie es mit der Stelle im CRM, an der Ihr Team es braucht.

Ein Widget in Zoho CRM ist eine eigene Oberfläche aus HTML, CSS und JavaScript, die innerhalb des CRM angezeigt wird und mit den CRM-Daten arbeitet. Laut Zoho lassen sich Widgets mit jedem clientseitigen Framework bauen, auch mit React JS. Ein Widget füllt damit Lücken, die Standardfelder, Layouts und Workflows nicht schließen.

Das JS SDK ist die JavaScript-Bibliothek von Zoho, über die ein Widget mit dem CRM spricht. Es liefert Seitendaten, öffnet und schließt Pop-ups und gibt Daten an andere Bausteine weiter. Ohne das SDK wäre ein Widget nur eine Webseite ohne Verbindung zum CRM.

Dieser Leitfaden richtet sich an Geschäftsführer, Vertriebsleiter und interne Administratoren. Sie sollen beurteilen können, ob sich ein Widget lohnt und was dabei zu beachten ist. Die Fakten stammen aus den Entwicklerbeiträgen von Zoho, vor allem aus den häufigen Fragen zu Zoho-CRM-Widgets (Kaizen #147).

Ein Widget kann in Zoho CRM an vielen Stellen erscheinen, und der Einsatzort bestimmt den Aufbau. Zoho nennt in seinen häufigen Fragen zu Widgets unter anderem diese Orte:

• als Web-Tab, also als eigener Reiter in der CRM-Navigation
• nach dem Klick auf eine Schaltfläche
• als benutzerdefinierte Bezugsliste in einem Datensatz
• als Element eines Dashboards
• auf der Einstellungsseite
• während der Übergänge in einem Blueprint
• als Bestandteil eines Assistenten
• für Benachrichtigungen zu Vertriebssignalen
• für Telefonie-Erweiterungen
• in Pop-ups und Call-outs

Der Blueprint ist das Prozesswerkzeug von Zoho CRM, das einen Datensatz durch feste Phasen führt. Ein Widget im Blueprint-Übergang eignet sich, wenn Mitarbeiter in genau diesem Schritt zusätzliche Angaben erfassen sollen. Wie Blueprint und Workflow-Regeln zusammenspielen, beschreibt unser Beitrag zu Workflows und Blueprint in Zoho CRM.

Ein Web-Tab passt für eigenständige Übersichten. Zoho zeigt in Kaizen #256 ein solches Web-Tab-Widget für die Hotellerie. Damit erkennt das Empfangspersonal Probleme vor der Ankunft der Gäste und löst sie rechtzeitig. Für Telefonie gibt es eigene Listener, die wir im Abschnitt zu Seitendaten erläutern.

Die Planung entscheidet mehr über den Erfolg eines Zoho-CRM-Widgets als der Code. Klären Sie vor der ersten Zeile drei Fragen. Welches Problem löst das Widget? An welcher Stelle im CRM erscheint es? Welche Module und Felder liest oder schreibt es?

Ein gutes Beispiel für die erste Frage liefert Zoho selbst. In Kaizen #187 begründet Zoho ein Zeiterfassungs-Widget damit, dass Zeitstempel im CRM nur festhalten, wann sich etwas ändert. Wie lange jemand aktiv an einem Fall gearbeitet hat, zeigen sie nicht. Einen Fall bei jeder kurzen Unterbrechung auf „On Hold“ zu setzen, wäre unpraktisch und würde die tatsächliche Arbeitszeit zu niedrig ausweisen.

Bei Svennis legen wir vor der ersten Codezeile schriftlich fest, wo das Widget im Layout erscheint und welche Felder es lesen oder schreiben darf. Fehlt diese Festlegung, sehen wir in Kundenprojekten später fast immer Umbauten am Layout oder an den Rechten.

Prüfen Sie außerdem, ob ein Widget überhaupt nötig ist. Oft reichen ein Feld, eine Workflow-Regel oder eine Deluge-Funktion. Deluge ist die Skriptsprache von Zoho, mit der Sie benutzerdefinierten Funktionen Geschäftslogik hinzufügen. Wenn das Datenmodell noch nicht steht, hilft unsere Checkliste für Datenmodell, Rechte und Import zuerst weiter.

Für ein Zoho-CRM-Widget brauchen Sie das JS SDK, einen Editor und optional ein Framework. Die CLI (Command Line Interface) ist ein Programm, das Sie über Befehle in der Eingabeaufforderung steuern. Zoho bietet dafür das Werkzeug „zet“ an, mit dem Sie Widget-Projekte anlegen und verpacken.

Laut einem Beitrag in der Zoho-Community gibt es CLI-Befehle für das zet-SDK, aber nicht für andere Frameworks. Wer mit React arbeitet, muss den Build daher selbst in die Projektstruktur von zet überführen. Die Community-Frage zu React.js und dem zet-SDK zeigt, dass genau dieser Schritt oft unklar ist.

Die folgende Zeile bindet das JS SDK ein. Fügen Sie sie in den head-Bereich der HTML-Startdatei Ihres Widgets ein, so wie Zoho es in den häufigen Fragen beschreibt.

<script src="https://live.zwidgets.com/js-sdk/1.2/ZohoEmbededAppSDK.min.js"></script>

An dieser Zeile ändern Sie nichts. Die Zahl im Pfad ist die SDK-Version, die Zoho in seinen häufigen Fragen angibt. Wichtig ist nur der Ort: Die Zeile steht im head-Bereich, damit das SDK geladen ist, bevor Ihr eigenes Skript läuft.

Zoho hat zudem eine zoho-crm-Skill-Datei (SKILL.md) vorgestellt. Sie soll die Arbeit mit APIs, Funktionen, Widgets und Client Scripts in KI-Werkzeugen wie Claude Code, Cursor oder VSCode erleichtern. Wer Entwicklung mit KI-Automatisierung verbindet, prüft den erzeugten Code trotzdem Zeile für Zeile gegen die Zoho-Dokumentation.

Ein Zoho-CRM-Widget erhält Daten von der CRM-Seite über sogenannte Listener. Ein Listener ist eine Funktion, die auf ein bestimmtes Ereignis wartet und dann ausgeführt wird. Das JS SDK stellt dafür mehrere Listener und Methoden bereit.

Diese Bausteine nennt Zoho in den häufigen Fragen zu Widgets:

• PageLoad: liefert die Daten der aktuellen Seite als Parameter an das Widget.
• ZOHO.embeddedApp.on("NotifyAndWait"): übergibt Daten aus dem Widget an ein Client Script.
• ZOHO.CRM.UI.Popup.close(): schließt das Widget über eine Schaltfläche im Widget selbst.
• Dial und DialerActive: laden eine Telefonie-App eines Drittanbieters in das Widget.

Client Script ist JavaScript, das direkt in der Oberfläche von Zoho CRM läuft, etwa beim Öffnen eines Datensatzes. Laut Zoho können Sie Widgets über Client Script in Pop-ups und Call-outs anzeigen. In Client Script lassen sich außerdem die Methoden von ZRC nutzen, dem Zoho Request Client für Anfragen an das CRM.

Der Listener DialerActive greift, wenn ein Nutzer auf das Telefonsymbol neben einer Telefonnummer klickt. Er lädt die Nummer dann in das Wählfeld der Drittanbieter-App im Widget. Zoho empfiehlt diesen Weg für Organisationen ohne native Telefonie-Erweiterung. Mehr zur Planung lesen Sie in unserem Beitrag zur Telefonie-Integration in Zoho CRM.

Das Timer-Widget aus Kaizen #187 zeigt den Aufbau eines Zoho-CRM-Widgets an einem echten Fall. Es misst die aktive Arbeitszeit und protokolliert Unterbrechungen. Dafür kombiniert es CRM-APIs, Client Script, Funktionen und Workflows. Zoho beschreibt das Vorhaben in Kaizen #187, Teil 1 der Reihe zum Timer- und Worklog-Widget.

Der Aufbau folgt diesen Schritten:

1. Legen Sie ein benutzerdefiniertes Modul „Timer Entries“ an. Jeder Start des Timers erzeugt dort einen neuen Datensatz.
2. Ergänzen Sie das Formelfeld „Total Duration (in mins.)“ mit DateBetween(${Timer Entries.Start Time},${Timer Entries.End Time},'Minutes').
3. Erstellen Sie die benutzerdefinierte Ansicht „Active Timer Entry“. Sie zeigt Einträge des angemeldeten Nutzers, deren Feld „End Time“ leer ist.
4. Öffnen Sie Setup > Developer Hub > Widgets, klicken Sie auf „Create New Widget“ und wählen Sie den Typ „Button“.
5. Legen Sie ein Client Script der Kategorie „Command“ an. Es erzeugt ein Flyout und zeigt das Widget darin an.

Ein Flyout ist ein schwebendes Fenster, das über der CRM-Oberfläche liegt. Bemerkenswert ist eine Designentscheidung: Der Timer legt den Eintrag mit Startzeit auch dann an, wenn kein Fall gewählt und nichts eingetragen ist. Beim Stoppen sucht das Widget über die Ansicht den neuesten offenen Eintrag des Nutzers und ergänzt ihn.

Teil 2 der Reihe überträgt die Einträge per Workflow und Deluge-Funktion in das Unterformular „Work Log“ im Modul Cases. Die Auswertung für SLA und Produktivität läuft danach über die CRM-Berichte.

Ein fertiges Widget laden Sie in Zoho CRM unter Setup > Developer Hub > Widgets hoch. Dort vergeben Sie einen Namen, wählen den Typ und hinterlegen das Paket. Der Typ legt fest, wo das Widget erscheint, im Beispiel aus Kaizen #187 ist es „Button“.

Für das Paket gelten feste Grenzen. Laut Zoho darf ein Widget-Projekt höchstens 250 Dateien umfassen und insgesamt 25 MB groß sein. Jede einzelne Datei ist auf 5 MB begrenzt. Ein React-Build mit großen Bibliotheken oder eingebetteten Bildern stößt schneller an diese Werte, als viele erwarten.

Ein häufiger Stolperstein ist der Upload selbst. Ein Nutzer berichtete in der Zoho-Community, er habe ein Widget in HTML, CSS und JavaScript gebaut und Pfad und ZIP-Datei angegeben. Trotzdem meldete das CRM, die Seite sei nicht verfügbar und womöglich entfernt, umbenannt oder verschoben. Der Community-Beitrag zum Upload-Fehler nennt keine abschließende Ursache. Vergleichen Sie bei dieser Meldung den hinterlegten Pfad Zeichen für Zeichen mit der Ordnerstruktur im Paket.

Nach dem Upload binden Sie das Widget an seinem Einsatzort ein: als Schaltfläche, Bezugsliste, Web-Tab oder über ein Client Script im Pop-up. Testen Sie danach mit einem Nutzer, der die Rechte eines normalen Teammitglieds hat, nicht nur als Administrator.

Die häufigsten Probleme bei Zoho-CRM-Widgets lassen sich vor dem Go-live mit wenigen Prüfpunkten abfangen. Die folgende Tabelle fasst sie zusammen, jeweils mit der Grundlage aus der Zoho-Dokumentation.

Prüfpunkt	Was Sie prüfen	Grundlage
Paketgröße	Höchstens 250 Dateien, 25 MB gesamt, 5 MB je Datei	Zoho, häufige Fragen zu Widgets
SDK-Einbindung	CDN-Zeile steht im head-Bereich der Startdatei	Zoho, häufige Fragen zu Widgets
Einsatzort	Typ im Developer Hub passt zum geplanten Ort	Kaizen #187
Datenübergabe	NotifyAndWait ist registriert, wenn Client Script Daten erwartet	Zoho, häufige Fragen zu Widgets
Upload-Pfad	Pfad und ZIP-Struktur stimmen überein	Community-Beitrag zum Upload-Fehler
Funktionsrechte	Nutzer mit „Workflow verwalten“ pflegen die Deluge-Funktionen	Zoho, Programmierung benutzerdefinierter Funktionen
Fehlerüberwachung	Eigene Kontrolle für Drittanbieter-Schnittstellen eingerichtet	Zoho, Programmierung benutzerdefinierter Funktionen

Der letzte Punkt verdient Aufmerksamkeit, wenn Ihr Widget mit Deluge-Funktionen arbeitet. Laut der Zoho-Hilfe zur Programmierung benutzerdefinierter Funktionen kommt keine E-Mail, wenn eine Integration wegen einer fehlerhaften Drittanbieter-API ausfällt. Bei Fehlern sendet das System eine erste Benachrichtigung und nach 15 Minuten eine zweite, danach keine mehr für diesen Auslöser. Für Schnittstellen nach außen lohnt unser Beitrag zur stabilen API-Anbindung von Zoho CRM.

Für Unternehmen im deutschsprachigen Raum ist ein eigenes Zoho-CRM-Widget vor allem eine Frage von Datenzugriff und Verantwortung. Ein Widget liest und schreibt Kundendaten mit den Rechten des angemeldeten Nutzers. Deshalb gehört es in dieselbe Dokumentation wie Felder, Rollen und Workflows.

Halten Sie für jedes Widget fest, welche personenbezogenen Daten es verarbeitet und wohin es sie überträgt. Das gilt besonders, wenn ein Widget eine Drittanbieter-Anwendung lädt, etwa eine Telefonie-App oder einen Kartendienst. Wie Sie Löschung, Auskunft und Zweckbindung im CRM umsetzen, zeigt unser Beitrag zur DSGVO in Zoho CRM.

Prüfen Sie außerdem, ob das Widget außerhalb des CRM laufen soll. In der Zoho-Community fragte ein Entwickler, ob sich ein Karten-Widget für mobile Nutzer außerhalb des CRM betreiben lässt, mit Anmeldung über das JS SDK. Eine andere Community-Frage lautete, ob ein extern bereitgestelltes Widget überhaupt auf CRM-APIs zugreifen kann. Beide Fragen zeigen: Ein Widget außerhalb des CRM ist ein eigenes Projekt mit eigener Anmeldung und eigener Rechteprüfung.

Für die meisten mittelständischen Unternehmen ist der Betrieb innerhalb des CRM der einfachere Weg. Rechte, Protokollierung und Anmeldung bleiben dann in einer Hand, und der interne Administrator behält den Überblick.

Beginnen Sie mit einem einzigen, klar umrissenen Anwendungsfall und nicht mit einem großen Funktionspaket. Diese Schritte haben sich als Reihenfolge bewährt:

1. Beschreiben Sie das Problem in zwei Sätzen und prüfen Sie, ob Feld, Workflow oder Deluge-Funktion ausreichen.
2. Wählen Sie den Einsatzort aus der Liste der von Zoho unterstützten Orte.
3. Listen Sie die Module und Felder auf, die das Widget liest und schreibt.
4. Bauen Sie einen ersten Entwurf mit dem JS SDK und dem Listener PageLoad.
5. Prüfen Sie das Paket gegen die Grenzen von 250 Dateien, 25 MB und 5 MB je Datei.
6. Laden Sie das Widget im Developer Hub hoch und testen Sie mit einem normalen Nutzerkonto.

Wer das Beispiel aus Kaizen #187 nachbaut, lernt dabei alle Bausteine in einem überschaubaren Projekt kennen. Dazu gehören ein benutzerdefiniertes Modul, eine Ansicht, ein Widget vom Typ „Button“ und ein Command-Client-Script mit Flyout.

Wenn Sie das Widget in eine größere Einführung einbetten möchten, finden Sie auf unserer Seite zur Implementierung von Zoho CRM den Ablauf eines Projekts. Dort sehen Sie auch, wie Datenmodell, Rechte und Erweiterungen zusammengehören.

• Zoho: Kaizen #147, Frequently Asked Questions on Zoho CRM Widgets
• Zoho: Kaizen #187, Building a Timer and Worklog Widget (Part 1)
• Zoho Community: Connect and create Zoho CRM widget using React.js and the zet SDK
• Zoho Community: How can I insert an External Widget in Zoho CRM?
• Zoho Community: Creating Zoho CRM Widget using React JS (SKILL.md, ZRC)
• Zoho Community: Mobile Optimised CRM Widgets
• Zoho CRM Online-Hilfe: Benutzerdefinierte Funktionen, Programmierung