Widget events

Set callbacks during initialization and attach page event handlers before the action whose result you need.

Callbacks and Events

SenlerWidget.init accepts:

• contextProvider() — synchronously returns persistent page context; Promises are not supported;
• resolveRuntime(context) — synchronously selects settings based on visitor and dialog state;
• onCollapse(detail) — reports a click on shell.collapse_button.
• onReady(detail) — reports successful chat initialization and authentication once. detail contains channel_id, display_mode, and button_only. In button_only mode, this means the button is ready without loading a chat.
• onError(error) — reports the first startup failure for the instance; message failures and reconnects after readiness do not trigger it.

SenlerWidget.init({
  channel_id: "CHANNEL_ID",
  onReady(detail) {
    console.log("Widget ready", detail);
  },
  onError(error) {
    console.error(error.code, error.message, error.retryable);
  },
});

error is an Error named SenlerWidgetInitializationError. Its code is invalid_config, iframe_load_failed, startup_failed, authentication_failed, init_failed, init_timeout, or protocol_mismatch. retryable indicates whether retrying without changing configuration may help. Startup without a result times out with init_timeout after 90 seconds; a specific failure may arrive earlier. Invalid configuration also throws the same error synchronously from init.

With direct init, existing load retries continue after onError: if startup recovers, onReady follows. Each callback runs at most once per instance. After destroy() or replacement through init, that instance's delayed callbacks are suppressed. Exceptions inside callbacks do not interrupt the widget.

In the SDK, createSenlerWidgetSession(...).ready waits for chat readiness. The first failure rejects the Promise and destroys the instance; create a new session or change React's retryKey to retry. Destroying a pending session rejects with AbortError. Failure to load the script itself rejects the loader/session Promise before init runs.

customActions buttons use each action's handler, not a shared callback.

Page events

window event	When it is dispatched
senler-widget:collapse-request	The user clicked the collapse button.
senler-widget:mobile-edge-swipe	The user completed an enabled left-edge swipe.
senler-widget:credit-purchase-requested	The user requested additional credits; detail contains channel_id and lead_id.
senler-widget:runtime-message-result	A runtime message was accepted, completed, or failed.
senler-widget:stage	A diagnostic loading, connection, sending, history, or file stage changed. Use it for observability, not business logic.

senler-widget:stage always includes area, phase, and timestamp in detail; it may also include attempt, duration_ms, and a final result: "success" | "error" | "timeout".

area	Possible phase values
loader	instance-created, iframe-created, iframe-loading, iframe-loaded, app-mounted, ready-timeout, error
bootstrap	loading, success, error, timeout, interactive
dialogs	idle, loading, refetching, success, empty, error
history	idle, loading, refetching, loading-more, success, empty, error
realtime	disabled, token-loading, connecting, connected, reconnecting, disconnected, error
message	optimistic, sending, queued, sent, failed, waiting, typing, streaming, done, error
upload	requesting-url, uploading, confirming, ready, error

This is a diagnostic stream, not the final state machine of a business process. The stage set may expand and individual phases may repeat or be skipped, so business logic must not depend on their exact sequence.

See embedding in a container for collapse and swipe handling, and sending messages from a website for sending statuses.