Configuration Reference

init(container, config) and el.setConfig(config) take the same shape. Partial setConfig() calls merge into prior values for strings, settings, and theme. Optional locale and getHeaders apply when those keys are present on the patch (each call can replace the previous programmatic value).

In React, this is the object you pass to the config prop.

Updating config

You can call setConfig() at any time after setup, passing only the keys that changed. In React, passing a new config prop does the same. Typical reasons are the visitor switching your site to dark mode, or your app refreshing the login token.

The widget only updates what those keys affect. Calling setConfig() again with the same values does nothing, so it's safe to call often, for example on every render.

When you change	What the visitor sees
theme, themePreset	The colours and sizes change straight away. Nothing else changes: an open chat keeps its scroll position, the message the visitor is typing, and keyboard focus.
getHeaders, apiUrlTrailingSlash	Nothing. The widget uses the new values from its next request, and checks for new messages straight away, so a refreshed token takes effect immediately.
strings, locale, settings, accountNumber, userHandle, apiUrl	The chat window is redrawn with the new values. A message the visitor has typed but not sent is cleared, and the list scrolls to the latest message. Changing apiUrl also forgets the saved conversation, because it belongs to the previous backend.
onClose	Nothing. The new callback is used from then on.

:::tip Keep getHeaders the same function The widget treats a different getHeaders function as new headers, even when it returns the same values, and checks for messages again each time it changes. If you create the function inside a React component, wrap it in useCallback so it only changes when it has to. See React. :::

Required

Property	Type	Description
apiUrl	string	Absolute GraphQL endpoint URL. Must use https: except local dev (http://127.0.0.1:PORT/… or http://localhost:PORT/…). Trailing slash is stripped by default (see apiUrlTrailingSlash).
accountNumber	string	Account identifier, e.g. A-B280147D.
userHandle	string	Identifies the visitor as the sender of their messages (sent as fromHandle). Usually the user's email address, but any handle your backend accepts works.

Optional

Property	Type	Description
apiUrlTrailingSlash	boolean	When true, keep or add a trailing slash on apiUrl before each request. Default false (slash stripped).
getHeaders	() => HeadersInit | Promise<HeadersInit>	Per-request headers (e.g. Authorization). Called before every GraphQL request. Omit when using a same-origin proxy that attaches the token server-side — see Authentication.
locale	string	BCP 47 tag for message date/time (en-GB, es-ES, …). Omit for browser default.
strings	InkLiveChatWidgetStrings	All user-facing copy. See Strings.
themePreset	"dark" | "light"	Built-in base palette. Default "dark". Individual theme keys override on top. See Theme.
theme	InkLiveChatWidgetTheme	Colours, fonts, trigger position, sizing — override individual values on top of the preset. See Theme.
settings	InkLiveChatWidgetSettings	Poll intervals and page size. See Settings.
onClose	() => void	Called when the header X closes the panel: after the user confirms ending an active chat, or straight away when there's no active chat. Not called on minimize or Escape.

Behaviour summary

What the widget handles for you once configured:

• Keeps the conversation — the current chat is remembered per account in sessionStorage, so a reload in the same tab shows the same thread.
• One chat per account — the chat is shared by every tab and device. A tab picks up a chat already in progress elsewhere, and when the chat ends elsewhere the history stays visible, read-only, with a Start a new conversation button. See Polling.
• New messages by polling — about every 5 s while the panel is open. While it's minimized, the launcher badge shows the unread count. See Polling.
• Message history — scrolling up loads older messages, and a floating button jumps back to the latest (with a new-message count).
• Errors — a failed send keeps the message and shows an alert; a failed load shows a Try again button.
• Ending a chat — the header X asks for confirmation before ending the chat. Minimize, or Escape, only hides the panel.
• Accessibility — ARIA roles and keyboard support (Enter to send, Shift+Enter for newline, Escape to dismiss).

Teardown

Removing the element from the DOM cleans up automatically. Call destroy() for explicit teardown — it returns a Promise.

Call	Behaviour
await el.destroy()	Removes the widget and stops polling. The conversation saved in sessionStorage is kept, so a new mount resumes it.
await el.destroy({ closeConversation: true })	Same, plus ends the chat on the server if there is one, without the in-widget confirmation. The saved conversation is cleared only if that succeeds.