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 response component, because they would repeat the component's own options.

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 confirm and select components show. Each label is optional, and a partial override replaces only what it names:

Customizing the rendered strings says when each one shows.

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