Widget-JavaScript-API

Sobald das SilentChat-Skript geladen ist, steht auf der Seite das globale Objekt window.SilentChat zur Verfügung. Darüber steuern Sie das Widget programmatisch.

Das Skript wird mit async eingebunden und ist deshalb nicht sofort da. Rufen Sie Methoden entweder nach dem load-Ereignis des Skripts auf oder warten Sie auf das ready-Ereignis. Aufrufe vor dem Laden gehen verloren — es gibt keine Befehlsschlange, die sie nachholt.

window.SilentChat.on('ready', function () {
  window.SilentChat.open();
});

open()

Öffnet das Chat-Fenster. Nützlich, um den Chat über eine eigene Schaltfläche auszulösen.

SilentChat.open();

<button onclick="SilentChat.open()">Chat with us</button>

close()

Schließt das Chat-Fenster.

SilentChat.close();

toggle()

Schaltet zwischen geöffnet und geschlossen um.

SilentChat.toggle();

sendMessage(text)

Sendet eine Nachricht im Namen des Besuchers — als hätte er sie selbst getippt. Öffnet den Chat nicht von sich aus.

SilentChat.sendMessage('Ich habe eine Frage zur Rechnung.');

setVisitorInfo(info)

Ordnet dem laufenden Besuch einen Namen und eine E-Mail-Adresse zu. Rufen Sie das auf, wenn ein Nutzer bei Ihnen angemeldet ist — dann muss er die Angaben im Chat nicht noch einmal machen.

SilentChat.setVisitorInfo({
  name: 'Jane Doe',
  email: 'jane@example.com',
});

In jedem Tarif verfügbar: Dieselben beiden Felder erhebt das Vor-Chat-Formular ohnehin. Andere Schlüssel werden übergangen — für eigene Merkmale gibt es setCustomData.

setCustomData(data)

Übermittelt frei wählbare Merkmale zum Besucher, zum Beispiel den gebuchten Tarif oder die Mitarbeiterzahl. Sie erscheinen in der Besucheransicht und lassen sich für Segmente und Auslöser verwenden. Ein Wert von null entfernt das Merkmal wieder.

SilentChat.setCustomData({
  plan: 'premium',
  mitarbeiter: 42,
});

// Ein einzelnes Merkmal wieder entfernen:
SilentChat.setCustomData({ plan: null });

Ab Professional. In kleineren Tarifen antwortet die Schnittstelle mit dem Grund für die Ablehnung; das Widget schreibt ihn in die Browser-Konsole — auch in der Produktivumgebung.

Bitte keine personenbezogenen Daten in Merkmale schreiben. Werte, die wie eine E-Mail-Adresse oder Telefonnummer aussehen, speichern wir maskiert — das ist eine Notbremse, kein Ersatz für Datensparsamkeit. Für Name und E-Mail gibt es setVisitorInfo.

track(name, properties)

Meldet ein eigenes Ereignis: was auf Ihrer Seite gerade passiert ist. Ereignisse erscheinen in der Zeitleiste des Besuchers und lassen sich in Segmenten und als Auslöser-Bedingung verwenden.

SilentChat.track('warenkorb_gefuellt', { wert: 249.90 });

Der Name wird vereinheitlicht: Groß-/Kleinschreibung, Leerzeichen, Binde- und Schrägstriche fallen zusammen, Umlaute werden ausgeschrieben. „Warenkorb gefüllt“, „warenkorb-gefuellt“ und „WARENKORB_GEFUELLT“ sind damit dasselbe Ereignis und nicht drei.

Grenzen je Mandant: 50 verschiedene Ereignisnamen, danach werden weitere unter _other geführt. Je Sitzung 200 Ereignisse. Ab Professional, wie setCustomData — beides hängt am selben Tarif-Merkmal.

show() / hide()

Blendet den Launcher aus beziehungsweise wieder ein. Die Sitzung bleibt dabei bestehen.

SilentChat.hide();  // Launcher ausblenden, Sitzung bleibt bestehen
SilentChat.show();  // wieder einblenden

Ereignisse

Mit on(name, callback) hören Sie auf Widget-Ereignisse, mit off(name, callback) melden Sie sich wieder ab.

function onOpen() {
  console.log('Chat window opened');
}

SilentChat.on('open', onOpen);
SilentChat.off('open', onOpen);

Mehr Ereignisse gibt es derzeit nicht. Ein Name, den das Widget nicht sendet, wird stillschweigend nie ausgelöst — prüfen Sie die Schreibweise gegen diese Tabelle.

Einwilligung

Wenn Sie ein eigenes Consent-Tool einsetzen (etwa Cookiebot oder Usercentrics), reichen Sie die Entscheidung des Besuchers hierüber an das Widget weiter.

// Einwilligung aus einem eigenen Consent-Tool durchreichen
SilentChat.setConsent('presence_tracking', true);

// Aktuellen Stand lesen: 'granted' | 'declined' | 'unknown'
SilentChat.getConsent('presence_tracking');

// Widerrufen
SilentChat.revokeConsent('presence_tracking');

// Auf Änderungen hören (gibt eine Abmeldefunktion zurück)
const unsubscribe = SilentChat.onConsentChange(function (type, granted) {
  console.log(type, granted);
});

Derzeit gibt es genau eine Einwilligungsart: presence_tracking. Andere Werte werden abgelehnt.

Öffentliche HTTP-Endpunkte (Fortgeschritten)

Die folgenden Endpunkte ruft das Widget-Skript intern auf. Sie sind unauthentifiziert (rate-limited auf 30 Anfragen/Minute/IP) und für eigene Widget-Implementierungen dokumentiert.

GET /api/v1/public/widget/:public_key/meta

Aggregiert für den Launcher: durchschnittliche Antwortzeit (7 Tage), Anzahl online verfügbarer Agents und (falls aktiviert) Vornamen/Avatare. Cache: 60 Sekunden.

curl https://api.silentchat.de/api/v1/public/widget/YOUR_PUBLIC_KEY/meta

{
  "avg_response_seconds": 280,
  "online_agent_count": 3,
  "online_agents": [
    { "first_name": "Marc", "avatar_url": "https://..." },
    { "first_name": "Lisa", "avatar_url": "https://..." }
  ]
}

Hinweis: Agent-Identitäten werden nur exponiert, wenn der Agent in seinem Profil public_display aktiviert hat. Ohne aktive Toggles liefert die Antwort ein leeres Feld.

POST /api/v1/public/widget/:public_key/resume

Tauscht entweder einen zuvor ausgestellten Token oder eine E-Mail gegen die letzten Konversationen und einen erneuerten Token (HMAC-SHA256, 30 Tage Hardcap, serverseitig signiert).

curl -X POST https://api.silentchat.de/api/v1/public/widget/YOUR_PUBLIC_KEY/resume \
  -H "Content-Type: application/json" \
  -d '{"token":"<previously-issued-token>"}'

{
  "token": "<renewed-token, 30-day cap>",
  "conversations": [
    { "id": "conv_01HXYZ", "last_message_at": "2026-05-18T14:32:00Z" }
  ]
}

Jeder Miss (unbekannter Token, abgelaufener Token, unbekannte E-Mail, Feature aus) gibt einen uniformen 404 zurück, damit Angreifer nicht herausfinden können, welche E-Mail-Adressen existieren.

POST /api/v1/widget/resume-attach

Hängt eine E-Mail-Adresse an die laufende Besuchersitzung und gibt einen Resume-Token zurück, mit dem der Besuch später auf einem anderen Gerät fortgesetzt werden kann.

curl -X POST https://api.silentchat.de/api/v1/widget/resume-attach \
  -H "Content-Type: application/json" \
  -H "X-Session-Token: <visitor-session-token>" \
  -d '{"email":"visitor@example.com"}'

Vollständiges Beispiel

<script
  src="https://cdn.silentchat.de/silentchat.min.js"
  data-widget-key="YOUR_PUBLIC_KEY"
  async
></script>
<script>
  // Das Skript lädt asynchron — window.SilentChat steht erst danach bereit.
  // Deshalb auf das load-Ereignis des Skripts warten, nicht sofort aufrufen.
  document.currentScript.previousElementSibling.addEventListener('load', function () {
    SilentChat.on('ready', function () {
      // Angemeldeten Nutzer zuordnen
      SilentChat.setVisitorInfo({
        name: 'Jane Doe',
        email: 'jane@example.com',
      });
    });
  });
</script>