Widget Public API methods

When Public API Is Needed

Use Website Widget for ordinary connection and channel settings. Public API is needed after installation when the site must open chat itself, change context, select a dialog, send a prepared question, or react to widget events.

The Public API does not require a separate cabinet switch. Its methods appear on window.SenlerWidget after the channel code loads. The linked setup guide shows cabinet actions with screenshots; this page covers only actions performed by site code.

Initialization

The examples use SDK v3. On the production host, use https://widget.senler.io/v3/widget-loader.js; for a local or test environment, use its /v3/widget-loader.js URL. The loader and iframe must support protocol 10, and the API must support v3.

For plain JavaScript, load the script through <script>: it provides window.SenlerWidget without installing a package. For TypeScript or React imports, install the stable @senlerio/widget@3.0.0 package. Both approaches use the same widget API. Installing the package does not update the servers.

Create a channel with the screenshot guide, then copy the loader script and channel_id from Embed Code. Call SenlerWidget.init(config) once per page:

<script src="URL_FROM_GENERATED_CODE" crossorigin="anonymous"></script>
<script>
  SenlerWidget.init({
    channel_id: "xxx",
  });
</script>

Replace both placeholders with cabinet values; do not reuse a loader URL from another project's or environment's example. See Initialization Parameters for init, placement modes, visitor data, and theme. Initialization creates one instance. A successful repeated init replaces the current instance with a new one, so after startup use SenlerWidget methods without recreating the iframe or losing dialog state.

Methods

Method	Returns	Result
`SenlerWidget.open()`	`undefined`	Shows the widget without sending a message or changing settings.
`SenlerWidget.close()`	`undefined`	Hides the widget while preserving the iframe and dialog state.
`SenlerWidget.toggle()`	`undefined`	Toggles visibility.
`SenlerWidget.isOpen()`	`boolean`	Reports whether the widget is visible.
`SenlerWidget.selectDialog(dialogId)`	`undefined`	Selects an existing dialog without sending a message or automatically showing a hidden widget.
`SenlerWidget.setPageContext(items)`	`undefined`	Replaces persistent page context.
`SenlerWidget.configure(settings)`	`undefined`	Changes instance settings without saving them to channel settings.
`SenlerWidget.refreshRuntime()`	`undefined`	Re-evaluates settings through `resolveRuntime`, for example after navigating to another website page. Example.
`SenlerWidget.createTextEdit(config)`	controller	Requests and applies text edits after confirmation.
`SenlerWidget.create(config)`	instance	Creates an independent widget; multiple embedded instances need separate containers.
`SenlerWidget.uploadFile(file, options)`	attachment Promise	Uploads a file to the specified dialog without sending a message.
`SenlerWidget.updateLead(profile)`	Promise	Saves the current lead’s contact details without reinitialization.
`SenlerWidget.setDraft(options)`	Promise	Fills the composer without sending; protects existing text by default.
`SenlerWidget.resetSession()`	Promise	Clears authentication and destroys the instance, retaining server-side history.
`SenlerWidget.ask(options)`	result Promise	Sends a question and returns answers and statuses.
`SenlerWidget.getOrCreateDialog(options)`	dialog Promise	Finds or creates a visitor dialog by `ref`.
`SenlerWidget.startNewDialog(options?)`	ID Promise	Creates and selects an empty dialog without sending a message.
`SenlerWidget.setContext(context)`	`undefined`	Replaces the site's JSON context; each `ask` captures a snapshot.
`SenlerWidget.setAnalytics(analytics)`	Promise	Supplies analytics identifiers and visit data.
`SenlerWidget.registerAction(name, definition)`	removal function	Adds a site action without replacing others.
`SenlerWidget.on(event, handler)`	unsubscribe function	Subscribes to instance events.
`SenlerWidget.destroy()`	`undefined`	Removes the iframe, button, and handlers. A site-provided embedded container remains in the page.

Use close() rather than destroy() for normal hiding. After close(), call open(); after destroy(), call SenlerWidget.init(...) again.

Before the instance is ready, isOpen() returns false. In button_only and headless modes, open and close methods display nothing; see settings.

After the loader is available, SenlerWidget.runtimeProtocolVersion contains the current protocol number (number). It is a diagnostic compatibility value; do not tie site business logic to a particular number.

Data for a custom chat

These methods are available on a ready instance with the built-in interface or with headless: true. In the table, options is a parameter object and ? marks an optional field. The step-by-step example covers selecting a dialog, history, sending, and subscriptions.

Method	Returns	Parameters and result
`SenlerWidget.getSettings(options?)`	settings Promise	Chat features, agent and credit availability, greeting, and starter texts.
`SenlerWidget.getDialogs(options?)`	page Promise	`limit?`, `before?`, `query?`, `offset?`: the visitor's visible dialogs.
`SenlerWidget.getMessages(options)`	page Promise	`dialogId`, `limit?`, `before?` or `after?`: messages ordered oldest first.
`SenlerWidget.getDialogState(options)`	state Promise	`dialogId`, `ref?`: unread count, typing, question queue, and pause reason.
`SenlerWidget.getWelcome(options?)`	greeting Promise	A greeting preview without creating a dialog.
`SenlerWidget.subscribeDialog(options)`	unsubscribe function	`dialogId`, `ref?`, `limit?`, `onUpdate`, `onError`: initial history and subsequent dialog changes.
`SenlerWidget.markRead(options)`	`Promise<void>`	`dialogId`: marks current messages read when the site actually displays them to the visitor.
`SenlerWidget.setTyping(options)`	`Promise<void>`	`dialogId`, `typing`: starts or stops the typing indicator.
`SenlerWidget.clickButton(options)`	`Promise<void>`	`dialogId`, `eventId`, `button`, `pollSelectedInstanceIds?`: dispatches a button returned by the server.
`SenlerWidget.updateQueuedQuestion(options)`	`Promise<void>`	`dialogId`, `questionId`, `revision`, `text`: updates a pending question with a version check.
`SenlerWidget.cancelQueuedQuestion(options)`	`Promise<void>`	`dialogId`, `questionId`: removes a question that has not started sending.
`SenlerWidget.sendQueuedQuestion(options)`	`Promise<void>`	`dialogId`, `questionId`: applies “Send now” to a queued question.
`SenlerWidget.getScheduledActions(options)`	page Promise	`dialogId`, `cursor?`: scheduled actions available to the visitor.
`SenlerWidget.cancelScheduledAction(options)`	`Promise<void>`	`dialogId`, `actionId`: cancels a pending scheduled action when permitted by the server.

Every method in this table accepts signal to cancel waiting and timeoutMs: 30,000 ms by default, up to 300,000 ms. For subscribeDialog, the timeout covers initial synchronization; the subscription then stays active until unsubscribe, abort, session reset, or instance destruction. Stopping the wait does not guarantee cancellation of an action already accepted by the server. The timeout for awaiting ask answers is documented separately.

Configuration and events

Runtime configuration: parameters for configure.
Widget events: readiness, errors, and callbacks.
Sending messages from a website: text preparation, sending, and result status.
Custom chat interface: headless, history pages, streaming, and the queue.
Embedding in a container: collapsing chat and handling the mobile gesture.

Initialization Parameters — placement mode, user data, theme, and features.
Page Context — persistent and one-time message data.
Custom Actions — site actions triggered by buttons or agent calls that return a result.
Inline Edits — AI text editing with a preview.
TypeScript and React: Use the official widget types, React component, and hooks from the @senlerio/widget package.
Visitor credit top-up: Connect a credit top-up request from the widget to checkout on your website.
Widget in an embedded page: Connect widget actions to an embedded application page so the assistant can find the relevant elements.