@getuserfeedback/chat

Headless TypeScript client for the getuserfeedback.com Chat API.

Use this package when you want to build your own user-facing conversation UI while getuserfeedback.com keeps the conversation history.

Install

npm install @getuserfeedback/chat

Create a client

import { createChatClient } from "@getuserfeedback/chat";

export const chat = createChatClient({
  auth: {
    jwt: {
      token: await fetchGetUserFeedbackChatToken(),
    },
  },
  realtime: true,
});

auth.jwt.token is sent as the Authorization: Bearer ... credential. Your backend or auth provider should mint this JWT for getuserfeedback.com with:

protected alg: the asymmetric signing algorithm selected in Widget settings
protected typ: gx-widget+jwt
aud: copy the Audience shown in Widget settings
sub: the stable identity for this user in your app
exp: the token expiration time as a Unix timestamp

See the identity verification guide for issuer, JWKS, signature, claim, and rollout setup.

The chat client does not accept a separate identify() call or per-request identity. getuserfeedback.com uses the signed app identity in the bearer token to decide which conversations the user can read or reply to.

In proxy mode, send the bearer credential your backend expects. Your backend should authenticate it, then call getuserfeedback.com with a JWT minted for your getuserfeedback.com app.

export const chat = createChatClient({
  baseUrl: "https://app.example.com/api/chat/v1",
  auth: {
    jwt: {
      token: await fetchBackendBearerCredential(),
    },
  },
});

Custom baseUrl values are used exactly, including any path prefix.

Realtime is opt-in. With the default API, set realtime: true and subscribe to conversation invalidations. Reload the conversation data held by your app when the listener runs:

const unsubscribe = chat.realtime.subscribe(() => {
  refreshConversationData();
});

Realtime currently connects directly to getuserfeedback.com and is unavailable when baseUrl points at a custom backend. Proxy mode continues to support explicit refreshes through the HTTP client. Browser Content Security Policies must allow wss://realtime.getuserfeedback.com in connect-src.

Refresh or clear auth

The auth shape matches the widget SDK.

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

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

List conversations

const { conversations, nextCursor } = await chat.conversations.list();

List messages

const { conversations } = await chat.conversations.list();

const { messages, nextCursor } = await chat.messages.list({
  conversationId: conversations[0].id,
});

Send a user message

const { conversations } = await chat.conversations.list();

const { message } = await chat.messages.send({
  conversationId: conversations[0].id,
  text: "Hello from my app.",
});

Errors

Failed API responses throw ChatApiError.

import { ChatApiError } from "@getuserfeedback/chat";

try {
  await chat.conversations.list();
} catch (error) {
  if (error instanceof ChatApiError) {
    console.error(error.status, error.code, error.message);
  }
}