--- title: React Native slug: sdk/web-view-sdk-api-reference-react-native createdAt: 2026-11-04T11:39:38.074Z --- The public API of the React Native, generated from release 1.0.1 # Classes ## KindlyWebViewError `class` ```typescript class KindlyWebViewError extends Error ``` The error every `KindlyWebViewSDK` call rejects (or throws) with. `code` is one of the protocol codes; the message names the failing call or argument and never contains a value you passed. | Member | Declaration | Description | | ------------- | ------------------------------------------------------------ | ----------- | | `constructor` | `constructor(code: KindlyWebViewErrorCode, message: string)` | | | `code` | `readonly code: KindlyWebViewErrorCode` | | ## KindlyWebViewSDK `class` ```typescript class KindlyWebViewSDK ``` The Kindly web-view chat SDK. Every member is static. Calls that return a promise reject with `KindlyWebViewError`; the setters throw it for an invalid argument. | Member | Declaration | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authCallbackTimeoutMs` | `static readonly authCallbackTimeoutMs: 12000 = 12_000` | How long the SDK waits for an auth callback before answering "no token". Native gives up at 15 s. | | `linkCallbackTimeoutMs` | `static readonly linkCallbackTimeoutMs: 4000 = 4_000` | How long the SDK waits for `shouldHandleLink` before opening the link. Native opens it at 5 s. | | `addEventListener` | `static addEventListener( listener: KindlyWebViewEventListener ): KindlyWebViewSubscription` | Every event from the chat, from now on (events are not replayed). | | `addStateListener` | `static addStateListener( listener: KindlyWebViewStateListener ): KindlyWebViewSubscription` | State changes. The new listener first receives the current state. | | `authenticate` | `static authenticate(): Promise` | Re-authenticates the chat with the callback given to `start`, for example after sign-in. | | `clearNewContext` | `static clearNewContext(): void` | Withdraws context set with `setNewContext`. | | `closeChat` | `static closeChat(): Promise` | Dismisses the chat. The conversation stays alive; sendMessage and triggerDialogue keep working. | | `deauthenticate` | `static deauthenticate(): Promise` | Makes the chat anonymous without ending it. | | `displayChat` | `static displayChat(displayOptions?: KindlyWebViewDisplayOptions): Promise` | Presents the chat. The first call loads the widget; later calls reopen the live chat with the conversation intact. Rejects with NOT\_STARTED before `start`. | | `endChat` | `static endChat(): Promise` | Ends the conversation; the next display starts a new one. | | `getState` | `static getState(): Promise` | The current state. | | `isSupported` | `static isSupported(): Promise` | Whether this device and app can run the web chat. When false, the chat shows an update screen. | | `kill` | `static kill(): Promise` | Ends the conversation and stops the SDK. Call `start` again before anything else. | | `launchChat` | `static launchChat(displayOptions?: KindlyWebViewDisplayOptions): Promise` | The same as `displayChat`; kept for the native SDKs' Android name. | | `sendMessage` | `static sendMessage( message: string, sendOptions?: KindlyWebViewSendMessageOptions ): Promise` | Sends a message as the user. Needs a chat page: rejects with CHAT\_NOT\_READY before the first display. `newContext` goes with this message only. | | `setCrashReporting` | `static setCrashReporting(enabled: boolean): void` | Whether the native SDK reports its own errors to Kindly. On by default. | | `setDelegate` | `static setDelegate(delegate: KindlyWebViewDelegate \| null): void` | Sets or clears the link delegate. Without one (or with `null`) the SDK opens links outside the app without asking. | | `setNewContext` | `static setNewContext(context: { [key: string]: string }): void` | Context for the next message, button click or trigger. | | `setVerboseLogging` | `static setVerboseLogging(enabled: boolean): void` | Debug-level native logs. Off by default; they never contain chat content or tokens. | | `start` | `static start(startOptions: KindlyWebViewStartOptions): Promise` | Starts the SDK for a bot. The chat page is created on the first display, but the usage metrics start here, and the error reports unless `setCrashReporting(false)` turned them off, so an app that asks for the user's consent calls `start` after it. Calling it again with the same bot key and market keeps the live chat and replaces the language and the auth callbacks. Another bot or market closes the chat and starts over. | | `triggerDialogue` | `static triggerDialogue(dialogueId: string): Promise` | Starts a dialogue in the live chat (without opening it while the chat is hidden). | # Interfaces ## KindlyWebViewAttachment `interface` ```typescript interface KindlyWebViewAttachment ``` An attachment. Its download URL carries a session token and is never forwarded; `storagePath` identifies the file. | Member | Declaration | Description | | ------------- | ------------------------------ | ----------- | | `format` | `readonly format: string` | | | `id` | `readonly id: string` | | | `name` | `readonly name: string` | | | `sender` | `readonly sender: string` | | | `status` | `readonly status: string` | | | `storagePath` | `readonly storagePath: string` | | ## KindlyWebViewAuthCredentials `interface` ```typescript interface KindlyWebViewAuthCredentials ``` Credentials for an authenticated chat, for identity providers that issue more than one token. Set at least one of `idToken` and `accessToken`. The native SDK sends the `idToken` as the bearer token when there is one and the `accessToken` otherwise, so a provider that issues only an access token works. Credentials with neither count as none: the chat stays anonymous and the SDK logs one warning. Put an opaque token in either field and set `issuer`. | Member | Declaration | Description | | ------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `accessToken` | `accessToken?: string \| null` | The access token from your identity provider: the bearer token when there is no `idToken`, otherwise its companion token, sent as `X-Access-Token`. | | `expiresAt` | `expiresAt?: number \| null` | When the credentials expire, in Unix **seconds**. Worth setting for opaque tokens. | | `idToken` | `idToken?: string \| null` | The OIDC id token, a JWT your backend signs, or an opaque token. The preferred bearer token. | | `issuer` | `issuer?: string \| null` | The identity provider's issuer. Required for opaque tokens and for bots with several providers. | ## KindlyWebViewButton `interface` ```typescript interface KindlyWebViewButton ``` | Member | Declaration | Description | | ----------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `context` | `readonly context: Readonly> \| null` | Flat context, at most 20 primitive values. | | `hasBeenSelected` | `readonly hasBeenSelected: boolean` | | | `id` | `readonly id: string \| null` | | | `index` | `readonly index: number \| null` | | | `label` | `readonly label: string` | | | `type` | `readonly type: string` | | | `value` | `readonly value: string \| null` | An absolute URL value has lost its query and fragment. | ## KindlyWebViewButtonClickDetail `interface` ```typescript interface KindlyWebViewButtonClickDetail ``` | Member | Declaration | Description | | ------------- | ---------------------------------------------------- | ----------- | | `button` | `readonly button: KindlyWebViewButton \| null` | | | `buttonType` | `readonly buttonType: string` | | | `chatLog` | `readonly chatLog: readonly KindlyWebViewMessage[]` | | | `lastMessage` | `readonly lastMessage: KindlyWebViewMessage \| null` | | ## KindlyWebViewButtonClickEvent `interface` ```typescript interface KindlyWebViewButtonClickEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewButtonClickDetail` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "buttonClick"` | | ## KindlyWebViewDelegate `interface` ```typescript interface KindlyWebViewDelegate ``` | Member | Declaration | Description | | ------------------ | ---------------------------------------------- | ----------- | | `shouldHandleLink` | `shouldHandleLink?: KindlyWebViewLinkCallback` | | ## KindlyWebViewDisplayOptions `interface` ```typescript interface KindlyWebViewDisplayOptions ``` | Member | Declaration | Description | | ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ | | `languageCode` | `languageCode?: string` | A language for this display. A language other than the live chat's renders the chat again in it. | | `triggerDialogueId` | `triggerDialogueId?: string` | A dialogue to start as the chat opens. | ## KindlyWebViewGlobalIcon `interface` ```typescript interface KindlyWebViewGlobalIcon ``` | Member | Declaration | Description | | ---------- | ----------------------------------- | ----------- | | `action` | `readonly action: string \| null` | | | `altText` | `readonly altText: string \| null` | | | `id` | `readonly id: string \| null` | | | `imageUrl` | `readonly imageUrl: string \| null` | | | `title` | `readonly title: string \| null` | | | `type` | `readonly type: string \| null` | | ## KindlyWebViewGlobalIconDetail `interface` ```typescript interface KindlyWebViewGlobalIconDetail ``` | Member | Declaration | Description | | ------ | ------------------------------------------------ | ----------- | | `icon` | `readonly icon: KindlyWebViewGlobalIcon \| null` | | | `type` | `readonly type: string` | | ## KindlyWebViewGlobalIconEvent `interface` ```typescript interface KindlyWebViewGlobalIconEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewGlobalIconDetail` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "globalIcon"` | | ## KindlyWebViewImage `interface` ```typescript interface KindlyWebViewImage ``` | Member | Declaration | Description | | --------- | ---------------------------------- | -------------- | | `altText` | `readonly altText: string \| null` | | | `id` | `readonly id: string \| null` | | | `url` | `readonly url: string` | Query removed. | ## KindlyWebViewLanguage `interface` ```typescript interface KindlyWebViewLanguage ``` | Member | Declaration | Description | | ----------- | ----------------------------- | ----------- | | `code` | `readonly code: string` | | | `isDefault` | `readonly isDefault: boolean` | | | `name` | `readonly name: string` | | ## KindlyWebViewLoadEvent `interface` ```typescript interface KindlyWebViewLoadEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewSettings` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "load"` | | ## KindlyWebViewMessage `interface` ```typescript interface KindlyWebViewMessage ``` | Member | Declaration | Description | | -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `attachments` | `readonly attachments: readonly KindlyWebViewAttachment[]` | | | `buttons` | `readonly buttons: readonly KindlyWebViewButton[]` | | | `chatId` | `readonly chatId: string \| null` | | | `created` | `readonly created: string \| null` | ISO 8601 text, or null. | | `exchangeId` | `readonly exchangeId: string \| null` | | | `exchangeType` | `readonly exchangeType: string \| null` | | | `fromBot` | `readonly fromBot: boolean` | | | `id` | `readonly id: string` | A message the user just typed carries a `tempId-...` id until the server confirms it. | | `images` | `readonly images: readonly KindlyWebViewImage[]` | | | `sender` | `readonly sender: KindlyWebViewMessageSender` | | | `text` | `readonly text: string \| null` | | | `videoSource` | `readonly videoSource: string \| null` | | ## KindlyWebViewMessageDetail `interface` ```typescript interface KindlyWebViewMessageDetail ``` | Member | Declaration | Description | | ------------ | --------------------------------------------------- | --------------------- | | `chatLog` | `readonly chatLog: readonly KindlyWebViewMessage[]` | The last 50 messages. | | `newMessage` | `readonly newMessage: KindlyWebViewMessage \| null` | | ## KindlyWebViewMessageEvent `interface` ```typescript interface KindlyWebViewMessageEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewMessageDetail` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "message"` | | ## KindlyWebViewSendMessageOptions `interface` ```typescript interface KindlyWebViewSendMessageOptions ``` | Member | Declaration | Description | | ------------ | ---------------------------------------- | -------------------------------------- | | `newContext` | `newContext?: { [key: string]: string }` | Context attached to this message only. | ## KindlyWebViewSettings `interface` ```typescript interface KindlyWebViewSettings ``` | Member | Declaration | Description | | ----------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `readonly id: string` | | | `languages` | `readonly languages: readonly KindlyWebViewLanguage[]` | | | `name` | `readonly name: string` | | | `style` | `readonly style: Readonly>` | Hex colours: background, buttonBackground, buttonText, headerBackground, headerText, inputBackground, inputText, userMessageBackground, userMessageTextColor, botMessageBackground, botMessageTextColor. | ## KindlyWebViewStartOptions `interface` ```typescript interface KindlyWebViewStartOptions ``` | Member | Declaration | Description | | ------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authCredentialsCallback` | `authCredentialsCallback?: KindlyWebViewAuthCredentialsCallback` | | | `authTokenCallback` | `authTokenCallback?: KindlyWebViewAuthTokenCallback` | | | `botKey` | `botKey: string` | The bot key from the Kindly platform. | | `languageCode` | `languageCode?: string` | The chat language, for example `en` or `nb`. Defaults to `en`. | | `market` | `market: string` | **Required** market slug, as configured for the bot (Settings, General, Details & markets). The widget loads that market's settings; there is no fallback to another market. | ## KindlyWebViewState `interface` ```typescript interface KindlyWebViewState ``` The SDK state. The field names match the native SDK; in the web-view SDK `isSocketConnected` and `isConnected` both mean "the chat page has loaded the widget", also while it is hidden. | Member | Declaration | Description | | ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | | `connectionState` | `readonly connectionState: KindlyWebViewConnectionState` | | | `isChatDisplayed` | `readonly isChatDisplayed: boolean` | | | `isConnected` | `readonly isConnected: boolean` | | | `isSocketConnected` | `readonly isSocketConnected: boolean` | | | `isStarted` | `readonly isStarted: boolean` | | | `raw` | `readonly raw: Readonly>` | Every field native sent, including ones this version does not know. | ## KindlyWebViewStateEvent `interface` ```typescript interface KindlyWebViewStateEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewState` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "state"` | | ## KindlyWebViewSubscription `interface` ```typescript interface KindlyWebViewSubscription ``` | Member | Declaration | Description | | -------- | ---------------- | ----------- | | `remove` | `remove(): void` | | ## KindlyWebViewUIDetail `interface` ```typescript interface KindlyWebViewUIDetail ``` | Member | Declaration | Description | | ---------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | | `action` | `readonly action: KindlyWebViewUIActionType` | | | `chatId` | `readonly chatId: string` | Empty when the widget had no chat yet. | | `feedbackType` | `readonly feedbackType: string \| null` | show-feedback, submit-feedback, dismiss-feedback | | `feedbackValue` | `readonly feedbackValue: Readonly> \| null` | | | `languageCode` | `readonly languageCode: string \| null` | change-language | | `languageName` | `readonly languageName: string \| null` | | | `nextPage` | `readonly nextPage: string \| null` | open-chatbubble: `chat` or `welcome-page` | | `previousLanguageCode` | `readonly previousLanguageCode: string \| null` | | | `previousLanguageName` | `readonly previousLanguageName: string \| null` | | | `rawType` | `readonly rawType: string` | The widget's ui type as sent, for example `close-chatbubble`. | | `source` | `readonly source: string` | `user` or `programmatic`. | | `value` | `readonly value: Readonly> \| null` | | ## KindlyWebViewUIEvent `interface` ```typescript interface KindlyWebViewUIEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: KindlyWebViewUIDetail` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "ui"` | | | `uiAction` | `readonly uiAction: KindlyWebViewUIActionType` | | ## KindlyWebViewUnknownEvent `interface` ```typescript interface KindlyWebViewUnknownEvent extends KindlyWebViewEventBase ``` | Member | Declaration | Description | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `detail` | `readonly detail: Readonly>` | | | `rawDetail` | `readonly rawDetail: Readonly>` | The detail exactly as native sent it (parsed JSON), with every field, known or not. | | `rawType` | `readonly rawType: string` | The `kindly:*` name native sent, for example `kindly:message`. | | `timestamp` | `readonly timestamp: number` | When native emitted the event, in epoch milliseconds. | | `type` | `readonly type: "unknown"` | | # Type Aliases ## KindlyWebViewAuthCredentialsCallback `type` ```typescript type KindlyWebViewAuthCredentialsCallback = (chatId: string) => Promise | KindlyWebViewAuthCredentials | null | undefined ``` Like `KindlyWebViewAuthTokenCallback`, for full credentials. Wins over the token callback when both are given. ## KindlyWebViewAuthTokenCallback `type` ```typescript type KindlyWebViewAuthTokenCallback = (chatId: string) => Promise | string | null | undefined ``` Called with the widget's chat id when the chat needs a token: after it connects, on `authenticate()` and before the previous token expires. Resolve with the JWT, or with null to leave the chat anonymous. Answers after 12 seconds are ignored. ## KindlyWebViewConnectionState `type` ```typescript type KindlyWebViewConnectionState = | "none" | "loading" | "connected" | "failed" | "unsupported" | "disconnected" | "unknown" ``` **Values** - `"unknown"`: A value this version of the package does not know; `raw.connectionState` keeps it. ## KindlyWebViewErrorCode `type` ```typescript type KindlyWebViewErrorCode = | "INVALID_ARGUMENT" | "NOT_STARTED" | "NO_ACTIVITY" | "CHAT_NOT_READY" | "UNSUPPORTED" | "NATIVE_ERROR" ``` The error codes native calls reject with (shared/wrapper-protocol.json `errorCodes`). ## KindlyWebViewEvent `type` ```typescript type KindlyWebViewEvent = | KindlyWebViewLoadEvent | KindlyWebViewMessageEvent | KindlyWebViewButtonClickEvent | KindlyWebViewUIEvent | KindlyWebViewGlobalIconEvent | KindlyWebViewStateEvent | KindlyWebViewUnknownEvent ``` An event from the chat. Switch on `type` for the typed `detail`; `rawType` and `rawDetail` always carry what native sent, so nothing is lost for a type this version does not know. ## KindlyWebViewEventListener `type` ```typescript type KindlyWebViewEventListener = (event: KindlyWebViewEvent) => void ``` ## KindlyWebViewEventType `type` ```typescript type KindlyWebViewEventType = | "load" | "message" | "buttonClick" | "ui" | "globalIcon" | "state" | "unknown" ``` **Values** - `"unknown"`: A `kindly:*` type this version of the package does not know; `rawType` keeps it. ## KindlyWebViewLinkCallback `type` ```typescript type KindlyWebViewLinkCallback = (url: string) => Promise | boolean ``` Asked before the chat opens a link outside the app (http, https, mailto, tel and sms links the user taps). Return `true` to let the SDK open it, `false` to handle it yourself. No answer within 4 seconds, or a thrown error, counts as `true`. ## KindlyWebViewMessageSender `type` ```typescript type KindlyWebViewMessageSender = | "USER" | "BOT" | "AGENT" | "SYSTEM" | "UNKNOWN" ``` ## KindlyWebViewStateListener `type` ```typescript type KindlyWebViewStateListener = (state: KindlyWebViewState) => void ``` ## KindlyWebViewUIActionType `type` ```typescript type KindlyWebViewUIActionType = | "open-chatbubble" | "close-chatbubble" | "end-chat" | "restart-chat" | "download-chat" | "delete-chat" | "change-language" | "show-feedback" | "submit-feedback" | "dismiss-feedback" | "welcome-page-start-chat" | "unknown" ``` **Values** - `"unknown"`: A ui type this version does not know; the event's `detail.rawType` keeps it.