Widget JavaScript API

Once the SilentChat script has loaded, the global object window.SilentChat is available on the page. Use it to control the widget programmatically.

The script is embedded with async and is therefore not available immediately. Call methods either after the script's load event or wait for the ready event. Calls made before the script loads are lost — there is no command queue that replays them.

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

open()

Opens the chat window. Useful for triggering the chat from your own button.

SilentChat.open();

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

close()

Closes the chat window.

SilentChat.close();

toggle()

Toggles the chat window between open and closed.

SilentChat.toggle();

sendMessage(text)

Sends a message on the visitor's behalf, as if they had typed it. Does not open the chat by itself.

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

setVisitorInfo(info)

Attaches a name and email address to the current visit. Call this when a user is signed in on your site so they do not have to enter the details again in the chat.

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

Available on every plan: the pre-chat form collects the same two fields anyway. Other keys are ignored — use setCustomData for custom attributes.

setCustomData(data)

Sends freely chosen attributes about the visitor, for example their plan or company size. They appear in the visitor view and can be used in segments and triggers. A value of null removes the attribute again.

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

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

Professional and above. On smaller plans the endpoint responds with the reason for the rejection, and the widget writes it to the browser console — in production too.

Please do not put personal data into attributes. Values that look like an email address or phone number are stored masked — that is an emergency brake, not a substitute for data minimisation. For name and email there is setVisitorInfo.

track(name, properties)

Reports a custom event: something that just happened on your site. Events appear in the visitor's timeline and can be used in segments and as a trigger condition.

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

The name is normalised: case, spaces, hyphens and slashes collapse, and umlauts are spelled out. "Cart filled", "cart-filled" and "CART_FILLED" are therefore one event, not three.

Per-tenant limits: 50 distinct event names, beyond which further names are recorded as _other. 200 events per session. Professional and above, same as setCustomData — both hang off the same plan feature.

show() / hide()

Hides or re-shows the launcher. The session stays intact either way.

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

Events

Use on(name, callback) to listen for widget events and off(name, callback) to stop listening.

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

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

There are no other events at the moment. A name the widget does not emit will simply never fire — check the spelling against this table.

Consent

If you use your own consent tool (such as Cookiebot or Usercentrics), pass the visitor's decision through to the widget here.

// 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);
});

There is currently exactly one consent type: presence_tracking. Other values are rejected.

Public HTTP endpoints (advanced)

The widget script calls the following endpoints internally. They are unauthenticated (rate-limited to 30 requests/minute/IP) and documented for custom widget implementations.

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

Aggregated for the launcher: average response time (7 days), number of agents online and (if enabled) first names/avatars. Cache: 60 seconds.

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://..." }
  ]
}

Note: agent identities are only exposed when the agent has enabled public_display in their profile. Without active toggles the response returns an empty field.

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

Exchanges either a previously issued token or an email for the most recent conversations and a renewed token (HMAC-SHA256, 30-day hard cap, signed server-side).

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" }
  ]
}

Every miss (unknown token, expired token, unknown email, feature off) returns a uniform 404 so attackers cannot find out which email addresses exist.

POST /api/v1/widget/resume-attach

Attaches an email address to the running visitor session and returns a resume token so the visit can be continued later on another device.

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"}'

Full example

<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>