Chat SDK reference

The Chat SDK is a headless client for user-facing conversation UIs. Use it when your app should show conversation history and let a signed-in user reply from your own UI.

If you're setting up for the first time, start with the React Chat SDK guide or JavaScript Chat SDK guide.

Packages

Authentication

Every request needs a JWT bearer token created by your app. Configure your backend or auth provider to issue a token for the signed-in user with this audience:

aud: https://getuserfeedback.com/v1/apps/{appId}sub: your user id

If your getuserfeedback.com app uses a custom JWT claim mapping, include exactly one claim that maps to userId. The examples use sub, which is the default.

Pass that token to the SDK. The SDK sends it as a bearer token:

Authorization: Bearer <token>

getuserfeedback.com verifies the token and uses the signed user id to decide which conversations the user can read or reply to.

createChatClient(options)

import { createChatClient } from "@getuserfeedback/chat";const chat = createChatClient({auth: {jwt: {token,},},});

Options

baseUrl must be absolute. If you proxy through your backend, include the full path your proxy expects:

createChatClient({baseUrl: "https://app.example.com/api/chat/v1",auth: { jwt: { token: appSessionToken } },});

In proxy mode, auth.jwt.token is the bearer token your backend expects. Your backend should authenticate that token, then call getuserfeedback.com with a JWT minted for your getuserfeedback.com app and that user.

chat.configure(updates)

Update auth after the client has been created.

await chat.configure({auth: {jwt: {token: refreshedToken,},},});

Clear auth on logout:

await chat.configure({auth: {jwt: null,},});

After auth is cleared, SDK requests fail with missing_auth_jwt until a new token is configured.

chat.conversations.list(input?)

Lists conversations visible to the signed user.

const page = await chat.conversations.list({limit: 25,});

Input

Response

type ChatConversationListResponse = {conversations: ChatConversation[];limit: number;nextCursor: string | null;};

chat.messages.list(input)

Lists messages in one conversation.

const page = await chat.messages.list({conversationId: "conv_123",limit: 50,});

Input

Response

type ChatMessageListResponse = {conversationId: string;limit: number;messages: ChatMessage[];nextCursor: string | null;};

chat.messages.send(input)

Sends a message from the signed user into an existing conversation.

const { message } = await chat.messages.send({conversationId: "conv_123",text: "Thanks — that helps.",});

Input

Response

type ChatMessageSendResponse = {message: ChatMessage;};

Message shape

type ChatMessage = {author: "system" | "team" | "unknown" | "user";content:| { type: "text"; text: string }| { type: "flow_response"; responseId: string }| { type: "unsupported" };conversationId: string;id: string;receivedAt: string;sentAt: string;timestamp: string;};

Render unsupported with a quiet fallback. It means the conversation contains a message type this SDK version doesn't know how to display yet.

React provider

import { GetUserFeedbackChatProvider } from "@getuserfeedback/chat-react";<GetUserFeedbackChatProviderclientOptions={{auth: {jwt: {token,},},}}><App /></GetUserFeedbackChatProvider>

The provider creates the chat client and owns an in-memory store for the hooks below it. When clientOptions.auth.jwt.token changes, the provider updates auth and resets the store so the next user doesn't see the previous user's cached conversations.

Props

Use clientOptions.baseUrl when proxying through your backend:

<GetUserFeedbackChatProviderclientOptions={{baseUrl: "https://app.example.com/api/chat/v1",auth: { jwt: { token: appSessionToken } },}}><App /></GetUserFeedbackChatProvider>

useConversationList(options?)

Loads conversations on mount by default.

const { conversations, error, hasMore, loadMore, refresh, status } =useConversationList({ limit: 25 });

Options

Return value

useConversation(options)

Loads one conversation's messages on mount by default.

const {error,hasMore,loadMore,messages,refresh,send,sendError,sendStatus,status,} = useConversation({ conversationId: "conv_123" });

Options

Return value

Errors

Failed API responses throw ChatApiError.

import { ChatApiError } from "@getuserfeedback/chat";try {await chat.conversations.list();} catch (error) {if (error instanceof ChatApiError) {console.log(error.status, error.code, error.message);}}

Common codes:

Current limits

• You can list conversations and send messages into them.
• Realtime updates, typing indicators, and read receipts are not exposed in the SDK yet.