Chat SDK API reference

Reference for @typewise/chat-sdk. For a guided introduction, start with Getting started.

createClient

import { createClient } from "@typewise/chat-sdk";

const chat = createClient(options);

Creates a client for one visitor. It does no network work until you call a method.

Options

string

required

Your Typewise client ID, from Behavior → Channels → Chat → Installation.

string

default:"Default workspace"

Workspace to load configuration and the Domain allowlist from.

string

default:"Runtime locale, then en"

Language short code, such as de.

object | () => object

Context variables for new conversations. Pass a function to read fresh values each time a conversation starts. See Share page context.

string | () => string | Promise<string>

A JWT signed by your backend, or a function returning one. The SDK calls the function each time it authenticates. See Identify signed-in users.

string[]

default:"Platform configuration"

Greetings shown before a conversation starts.

StorageAdapter

default:"localStorage, otherwise in-memory"

Where the visitor session is kept. Any object with getItem, setItem, and removeItem works, sync or async, such as React Native’s AsyncStorage.

string

default:"tw-client-sdk:<clientId>"

Storage key for the visitor session.

string

default:"https://platform-api.typewise.app"

API origin.

function

default:"globalThis.fetch"

Custom fetch implementation.

State

ChatState

Returns the current state snapshot.

Calls listener with the new state after every change. Returns a function that unsubscribes.

() => void

Listens to one event. Returns a function that unsubscribes.

Promise<ChatConfig>

Loads and caches the chat configuration, including greetings. resume() calls it for you.

Conversation

Promise<Conversation | null>

Restores the stored conversation and connects to real-time updates. Resolves to null when there is none.

Promise<Message>

Sends a message, starting a conversation first if needed. Messages sent while it starts are merged into one. Pass a string, or an object:

Show input

string

required

The message text. Can be empty when attachments has files.

Attachment[]

Files returned by uploadFiles.

Promise<Conversation>

Closes the current conversation and starts a new one.

Promise<void>

Closes the conversation. It’s removed locally at once, and the request survives page unloads.

void

Lets the visitor keep writing after the conversation was closed on the server. Check conversation.canReopen first.

Promise<void>

Shows the visitor’s typing state to Human Agents.

Promise<SetVariablesResult>

Updates context on the open conversation, or holds it for the next one.

Show input

object

Unverified values: strings, numbers, or booleans.

string

A JWT signed by your backend.

Show result

string[]

Names not declared in Context Variables.

string[]

Unsigned values that couldn’t overwrite a value that arrived verified.

Attachments, surveys, and verification

See Attachments, surveys, and verification for how these fit together.

Promise<UploadResult[]>

Uploads Files, Blobs, or { name, type, data } objects. Resolves to one result per file: { ok: true, name, attachment } or { ok: false, name, error }.

Show options

({ index, name, loaded, total }) => void

Called as bytes are sent. Needs XMLHttpRequest (browsers and React Native). Elsewhere it fires only when each file completes.

Promise<string>

Returns a short-lived download URL. Fails for messages that are still sending.

Promise<CsatConfig>

Loads the survey prompt (csatMessage) and any previous lastRating and lastComment.

Promise<void>

Submits a rating from 1 to 5 and an optional comment.

Promise<void>

Sends a verification code to the email.

Promise<{ success, reason }>

Checks the code. When success is false, reason is invalid_code, max_attempts, or expired.

Promise<VerificationStatus>

Returns state (none, awaiting_email, awaiting_code, or verified), email, and attemptsRemaining.

Promise<string>

Returns a short-lived ElevenLabs key for speech-to-text.

Session

Promise<void>

Records a product analytics event for this visitor. Does nothing before the visitor has a session.

Promise<void>

Forgets the visitor and disconnects, for example on logout.

Promise<void>

Disconnects and releases the client. It can’t be used afterwards.

Events

Listen with chat.on(event, listener). For the fields of Message, Conversation, and Activity, see Render messages and activity.

Message

A new message arrived or was sent.

{ message, previousId }

A message changed, for example when the server confirmed a sent message and its id changed from previousId.

Conversation | null

The conversation started, changed status, or closed.

Activity

The typing indicator changed.

string

The real-time connection state changed.

TypewiseError

A background task failed, such as a history refresh after a reconnect.

Errors

Methods reject with a TypewiseError. HTTP failures also carry a status. Failures in the background are emitted on chat.on("error", listener) instead.

`code`	Meaning
`invalid_input`	The call’s arguments are invalid, such as an empty message
`http`	The API returned an error. Check `status`: `404` means the client or workspace ID doesn’t exist
`network`	The request didn’t reach the API
`auth`	The API rejected the visitor’s session (HTTP 401 or 403)
`realtime`	The real-time connection failed
`upload`	A file upload failed
`no_conversation`	The method needs an open conversation
`destroyed`	The client was destroyed

import { TypewiseError } from "@typewise/chat-sdk";

try {
  await chat.sendMessage(text);
} catch (error) {
  if (error instanceof TypewiseError && error.code === "network") {
    showOfflineBanner();
  }
}

Other exports

StorageAdapter

In-memory storage adapter, for servers and tests.

class

The error class methods reject with.

TypeScript

ChatState, Message, Conversation, Activity, ChatConfig, TypewiseClient, and more. Types are bundled with the package.

Migrate to Typewise

Channels

Integrations

Best practices

createClient

Options

State

Conversation

Attachments, surveys, and verification

Session

Events

Errors

Other exports

​createClient

​Options

​State

​Conversation

​Attachments, surveys, and verification

​Session

​Events

​Errors

​Other exports

createClient

Options

State

Conversation

Attachments, surveys, and verification

Session

Events

Errors

Other exports