React Native

The public API of the React Native, generated from release 1.0.1

Classes

KindlyWebViewError

class

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

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<void>	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<void>	Dismisses the chat. The conversation stays alive; sendMessage and triggerDialogue keep working.
deauthenticate	static deauthenticate(): Promise<void>	Makes the chat anonymous without ending it.
displayChat	static displayChat(displayOptions?: KindlyWebViewDisplayOptions): Promise<void>	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<void>	Ends the conversation; the next display starts a new one.
getState	static getState(): Promise<KindlyWebViewState>	The current state.
isSupported	static isSupported(): Promise<boolean>	Whether this device and app can run the web chat. When false, the chat shows an update screen.
kill	static kill(): Promise<void>	Ends the conversation and stops the SDK. Call start again before anything else.
launchChat	static launchChat(displayOptions?: KindlyWebViewDisplayOptions): Promise<void>	The same as displayChat; kept for the native SDKs' Android name.
sendMessage	static sendMessage( message: string, sendOptions?: KindlyWebViewSendMessageOptions ): Promise<void>	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<void>	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<void>	Starts a dialogue in the live chat (without opening it while the chat is hidden).

Interfaces

KindlyWebViewAttachment

interface

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

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

interface KindlyWebViewButton

Member	Declaration	Description
context	readonly context: Readonly<Record<string, string \| number \| boolean \| null>> \| 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

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

interface KindlyWebViewButtonClickEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewButtonClickDetail
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

interface KindlyWebViewDelegate

Member	Declaration	Description
shouldHandleLink	shouldHandleLink?: KindlyWebViewLinkCallback

KindlyWebViewDisplayOptions

interface

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

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

interface KindlyWebViewGlobalIconDetail

Member	Declaration	Description
icon	readonly icon: KindlyWebViewGlobalIcon \| null
type	readonly type: string

KindlyWebViewGlobalIconEvent

interface

interface KindlyWebViewGlobalIconEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewGlobalIconDetail
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

interface KindlyWebViewImage

Member	Declaration	Description
altText	readonly altText: string \| null
id	readonly id: string \| null
url	readonly url: string	Query removed.

KindlyWebViewLanguage

interface

interface KindlyWebViewLanguage

Member	Declaration	Description
code	readonly code: string
isDefault	readonly isDefault: boolean
name	readonly name: string

KindlyWebViewLoadEvent

interface

interface KindlyWebViewLoadEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewSettings
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

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

interface KindlyWebViewMessageDetail

Member	Declaration	Description
chatLog	readonly chatLog: readonly KindlyWebViewMessage[]	The last 50 messages.
newMessage	readonly newMessage: KindlyWebViewMessage \| null

KindlyWebViewMessageEvent

interface

interface KindlyWebViewMessageEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewMessageDetail
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

interface KindlyWebViewSendMessageOptions

Member	Declaration	Description
newContext	newContext?: { [key: string]: string }	Context attached to this message only.

KindlyWebViewSettings

interface

interface KindlyWebViewSettings

Member	Declaration	Description
id	readonly id: string
languages	readonly languages: readonly KindlyWebViewLanguage[]
name	readonly name: string
style	readonly style: Readonly<Record<string, string \| null>>	Hex colours: background, buttonBackground, buttonText, headerBackground, headerText, inputBackground, inputText, userMessageBackground, userMessageTextColor, botMessageBackground, botMessageTextColor.

KindlyWebViewStartOptions

interface

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

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<Record<string, unknown>>	Every field native sent, including ones this version does not know.

KindlyWebViewStateEvent

interface

interface KindlyWebViewStateEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewState
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

interface KindlyWebViewSubscription

Member	Declaration	Description
remove	remove(): void

KindlyWebViewUIDetail

interface

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<Record<string, unknown>> \| 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<Record<string, unknown>> \| null

KindlyWebViewUIEvent

interface

interface KindlyWebViewUIEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: KindlyWebViewUIDetail
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

interface KindlyWebViewUnknownEvent extends KindlyWebViewEventBase

Member	Declaration	Description
detail	readonly detail: Readonly<Record<string, unknown>>
rawDetail	readonly rawDetail: Readonly<Record<string, unknown>>	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

type KindlyWebViewAuthCredentialsCallback = (chatId: string) => Promise<KindlyWebViewAuthCredentials | null | undefined> | KindlyWebViewAuthCredentials | null | undefined

Like KindlyWebViewAuthTokenCallback, for full credentials. Wins over the token callback when both are given.

KindlyWebViewAuthTokenCallback

type

type KindlyWebViewAuthTokenCallback = (chatId: string) => Promise<string | null | undefined> | 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

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

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

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

type KindlyWebViewEventListener = (event: KindlyWebViewEvent) => void

KindlyWebViewEventType

type

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

type KindlyWebViewLinkCallback = (url: string) => Promise<boolean> | 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

type KindlyWebViewMessageSender =
  | "USER"
  | "BOT"
  | "AGENT"
  | "SYSTEM"
  | "UNKNOWN"

KindlyWebViewStateListener

type

type KindlyWebViewStateListener = (state: KindlyWebViewState) => void

KindlyWebViewUIActionType

type

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.