Options Reference
Every option createQafka() (and <Qafka />, with the same names as props) accepts.
Core
| Option | Type | Description |
|---|---|---|
publishableKey | string | Required. Your project’s Web key. |
apiUrl | string | Overrides the backend URL. Defaults to https://api.qafka.com. |
subProjectId | string | Routes the conversation to a specific sub-project instead of the parent. See Sub-Projects. |
mode | 'floating' | 'inline' | floating (default) shows a chat bubble that opens a panel. inline renders the widget directly into a container you provide — no bubble. |
container | HTMLElement | string | Required when mode: 'inline'. An element, or a CSS selector resolved at mount. |
Visitor identity & tools on web
Every web session is minted at the anonymous trust tier server-side — neither of these options changes that, and neither unlocks tools. Tool availability on web is controlled separately, in the dashboard’s tool editor (Platform must include Web, Web access must be “Open on web (incl. anonymous)”) — see Web SDK Overview › Visitor identity & tools on web.
| Option | Type | Description |
|---|---|---|
endUserId | string | A client-supplied grouping id for the conversation — not a verified identity. Throws if passed as an empty or whitespace-only string. |
endUserData | Record<string, unknown> | Extra data alongside endUserId, never sent to the LLM (unlike context) unless a tool’s Description references it with {{endUser.*}}. |
isAuthenticated | boolean | Whether your own app considers the visitor signed in — gates which navigation screens the assistant may suggest. Does not affect tool availability or identify the visitor to the backend. See Navigation › Filtering by Auth State. |
Context
| Option | Type | Description |
|---|---|---|
context | object | () => object | Facts the assistant may use to personalize answers, flattened into the prompt as key: value lines and available to tool templates as {{user.<key>}}. Pass a function to have it re-read on every request. The reserved key navigation feeds the navigation entity catalog instead of the prompt. See Context. |
contextDescription | string | One sentence describing the screen the visitor is currently on (e.g. "User is viewing the pricing page"). Shown to the model above the rest of the context, not flattened into it. |
locale | string | Explicit reply language ('tr' or 'en'). Also sets the widget’s UI-chrome language; omit to auto-detect the UI language from the browser (the reply language is only ever set when you pass this explicitly). |
Appearance
| Option | Type | Description |
|---|---|---|
theme | Partial<WebThemeTokens> | Overrides individual theme tokens on top of the project’s configured chat theme. |
assistantName | string | Overrides the assistant’s display name for this mount. |
logoUrl | string | Overrides the assistant’s avatar/logo for this mount. |
greetingMessage | string | Overrides the greeting message shown when the chat opens. |
placeholder | string | Overrides the message composer’s placeholder text. |
All appearance options override the project’s dashboard-configured theme/branding for this mount only — they don’t change the project’s saved settings.
Voice (advanced)
| Option | Type | Description |
|---|---|---|
workletUrl | string | Overrides where voice mode’s AudioWorklet asset is loaded from — only needed for unusual CSP or self-hosting setups. |
Agent cursor
| Option | Type | Description |
|---|---|---|
agentCursor | boolean | Opt-in, default false. See Web SDK Overview › Agent cursor. |
Callbacks
| Callback | Fires when |
|---|---|
onReady | The widget has finished mounting. |
onError | A mount or theme-fetch failure occurs — and separately, for a message/stream failure, a tool error, or calling openVoice() when voice isn’t enabled for the project. Not called for the unavailable status (suspended project). |
onStatusChange | Lifecycle status changes — see Status below. Fires when the initial config fetch settles (never with loading). Captured once, at mount — update() doesn’t replace it, and in the React wrapper a new function passed on a later render has no effect. |
onMessageSent | The visitor sends a message. |
onResponseReceived | A response arrives. |
onToolSuggested | The assistant suggests one or more tools. |
onToolDataRequested | A tool needs host-supplied data to run; return it (sync or async) from this callback. |
onNavigationSuggest | The assistant suggests a navigation destination. |
onNavigationAction | The visitor acts on a navigation suggestion. Supplying this replaces the SDK’s own default web navigator entirely. |
onExternalSuggestion | The assistant suggests an external destination (WhatsApp, phone, a link, …). Not called for media cards (embed/document) — the widget draws those itself. |
onActionResult | One or more triggered actions finish, with their success/failure. |
onStepCompleted | A multi-step tool completes a step. |
onClose | The visitor closes the widget (floating mode only). |
Status
getStatus() and onStatusChange report one of:
| Status | Meaning |
|---|---|
loading | Initial state, until the chat-theme fetch settles. |
ready | Fully mounted. |
unavailable | The project is suspended. This is an expected, neutral state — it does not also fire onError. |
error | A mount or theme-fetch failure. onError also fires here, but it fires for other things too — see the callback table above. |
See Errors for the general error-handling model.
Last updated on