Web SDK configuration

Everything that shapes what the widget shows goes in config, passed to the Runbear constructor next to assistantId and auth. Every option is optional; leave config out and the widget uses the defaults below.

const client = new Runbear({
  assistantId: "…",
  auth: { mode: "session", fetchSessionToken },
  config: {
    chatInput: { placeholder: "Ask about your order…" },
    assistant: { name: "Acme Support", avatarUrl: "https://example.com/bot.png", showName: true },
    welcomeMessage: "Hi! How can I help you today?",
    userContext: { plan: "pro", locale: "en-US" },
  },
})

Options#

suggestions#

suggestions: { enabled: true } asks the agent for follow-up questions after each reply and shows them under a "Suggested Questions" heading. Clicking one sends it as the visitor's message. The widget skips suggestions after a reply that rendered a confirm or select response component, or showed a component as its plain-text summary, because they would repeat the component's own options. A reply whose only components are cards, lists, tables or charts keeps its suggestions. On 0.3.x to 0.5.x any rendered component skips them.

Suggestions use POST /v1/chat/suggestions, which a session pass can't call, so the option has no effect in session mode.

thinking#

thinking: { enabled: false } hides the agent's thinking while a reply streams. Thinking only appears for agents whose model streams it, which are Anthropic and Claude Agent SDK agents; for other agents the option changes nothing.

toolProgress#

toolProgress: { enabled: false } hides the inline progress lines the widget shows while the agent calls a tool.

userContext#

userContext is sent with every message as config.userContext, so the agent can take it into account: a plan, a locale, an account id. See Chat for how the API passes it on.

chatInput.placeholder#

The text shown in the empty message box.

assistant#

Identity shown on the agent's messages:

• name: shown above each agent message when showName is true, and used for the avatar's initials.
• avatarUrl: an image you host. It must be an https: URL; any other URL, or an image that fails to load, falls back to the initials from name, or to the default avatar icon.
• showName: false by default, so the name isn't shown unless you opt in. The avatar shows whenever avatarUrl is valid.

The widget doesn't read the agent's name or avatar from Runbear; these options are the only source.

welcomeMessage#

A greeting shown as the first agent message before the visitor types. It is rendered in the browser only: no thread is created for it, the agent isn't called, and it costs no credits. It shows on a new conversation, including after reset(), and never on a conversation reopened with startWithThread() or createChat(threadId), whose saved transcript is shown as it is.

Component labels#

components.labels replaces the strings the widget adds to response components: the confirm and select captions, and from 0.6.0 the pager, table and chart strings. Each label is optional, and a partial override replaces only what it names. Customizing the rendered strings lists every key with its default, when it shows, and the release that added it.

components.disabled#

components: { disabled: ["chart"] } shows each named component as its plain-text fallbackText instead of rendering it, live and after a reload. It takes component names — confirm, select, card, list, table and chart — not the agent's switch names, and it changes only what this widget renders: the agent still produces the component. To stop the agent producing a component, turn its switch off in the agent's Response components settings. The list is read once, when the chat is created; a name it does not recognize is ignored. Older SDKs ignore the option.

Attachments#

The widget has an attachment button, and visitors can also paste files into the message box. Each file can be up to 50 MB and must be one of the supported file types. Empty files are ignored, and a file already attached isn't added twice.

Attachments are available in proxy and direct mode. In session mode the attachment button is hidden, because a session pass can't upload files.

Which strings you can change#

Only the input placeholder and the component labels are configurable. Other widget strings are fixed in this release, including the "Suggested Questions" heading and the "An unknown error occurred" message shown when a reply fails.

Related#

• Authentication: the auth option
• Theming: colors, dark mode and CSS hooks
• Chat API: methods and events