Widget JavaScript API

Once the SilentChat widget script has loaded, a global sc() function is available on window. You can use it to control the widget programmatically — open or close the chat, identify logged-in users, listen to events, and more.

Commands called before the script finishes loading are queued automatically and executed once the widget is ready.

sc('init', options)

Manually initialise the widget with a configuration object. This is only required if you did not use the data-widget-key attribute on the script tag.

sc('init', {
  widgetKey: 'YOUR_PUBLIC_KEY',
  locale: 'en',
  position: 'bottom-right',
});

Options

Property	Type	Description
`widgetKey`	`string`	Your widget’s public key (required).
`locale`	`string`	ISO 639-1 language code. Defaults to the browser locale.
`position`	`string`	`bottom-right` or `bottom-left`.

sc('open')

Opens the chat window.

sc('open');

Useful for triggering the chat from a custom button or CTA:

<button onclick="sc('open')">Chat with us</button>

sc('close')

Closes the chat window (minimises it back to the bubble).

sc('close');

sc('identify', user)

Associates the current visitor with a known user. This lets agents see the visitor’s name, email, and any custom attributes alongside the conversation.

sc('identify', {
  userId: '9f2c4e1a-8d7b-4f3e-a6c5-1b2d3e4f5a6b',
  name: 'Jane Doe',
  email: '[email protected]',
  plan: 'pro',           // custom attribute
  signedUpAt: '2025-01-15',  // custom attribute
});

Properties

Property	Type	Description
`userId`	`string`	A unique, stable identifier for the user (required).
`name`	`string`	Display name.
`email`	`string`	Email address.
`*`	`any`	Any additional key-value pairs are stored as custom attributes.

sc('setLocale', locale)

Changes the widget’s display language at runtime.

sc('setLocale', 'fr');

Accepted values are any ISO 639-1 code for which translations have been configured in your widget settings.

sc('on', event, callback)

Registers a callback for a widget lifecycle event.

sc('on', 'chat:opened', () => {
  console.log('Chat window opened');
});

sc('on', 'message:received', (message) => {
  console.log('New message:', message.text);
});

Available Events

Event	Payload	Description
`ready`	—	Widget has finished loading and is ready.
`chat:opened`	—	Chat window was opened.
`chat:closed`	—	Chat window was closed.
`message:sent`	`{ text, timestamp }`	Visitor sent a message.
`message:received`	`{ text, timestamp, agentName }`	Agent message was received.
`unread:count`	`{ count }`	Unread message count changed.

sc('destroy')

Removes the widget from the page entirely. This tears down event listeners, closes the WebSocket connection, and removes all injected DOM elements.

sc('destroy');

After calling destroy you can re-initialise the widget by calling sc('init', ...) again.

Full Example

<script
  src="https://cdn.silentchat.de/silentchat.min.js"
  data-widget-key="YOUR_PUBLIC_KEY"
  async
></script>
<script>
  // Queue commands before the script loads
  window.sc = window.sc || function() {
    (window.sc.q = window.sc.q || []).push(arguments);
  };

  sc('on', 'ready', function() {
    console.log('SilentChat is ready');
  });

  // Identify a logged-in user
  sc('identify', {
    userId: 'user_123',
    name: 'Jane Doe',
    email: '[email protected]',
  });
</script>