Render messages and activity

Everything you render comes from one immutable state snapshot. This page explains each part and how to handle common cases: quick actions, Human Agent handoff, and closed conversations.

The state snapshot

chat.getState() returns the current snapshot. It changes identity only when something changed, so it works directly with React’s useSyncExternalStore, Svelte stores, and Vue refs.

Message[]

Greetings, history, live messages, and messages still sending, in order.

Show Message

string

Server ID, or local:… for greetings and messages not yet confirmed.

string

Stays the same when id changes. Use dedupeKey ?? id as a render key.

string

user (the visitor), assistant (the AI Agent), agent (a Human Agent), or system.

string

text, csat_request, email_verification_requested, email_verification_verified, or error. See Render by kind.

string

The body with component tags removed, for plain-text interfaces.

string

The body as authored: markdown that may contain components such as <QuickActions>.

string

sending, sent, or failed. Failed messages also have error.

string

The Human Agent’s display name, for role: "agent".

Attachment[]

{ name, path, type, size } for each file. See Attachments.

string

ISO timestamp.

Activity

What to show as a typing indicator.

Show activity.kind values

kind

The AI Agent is working. activity.text may carry progress, such as “Checking your order”.

kind

A Human Agent is typing.

kind

A Human Agent is reviewing the AI Agent’s reply before it’s sent.

kind

Nothing to show.

Conversation | null

The open conversation, or null before the first message.

Show Conversation

string

The conversation ID. It’s the ticket ID in Typewise.

boolean

A Human Agent has taken over.

boolean

The conversation has ended.

boolean

The visitor can keep writing in this conversation with reopen().

string

The detailed ticket status, such as ai_agent_processing or done.

string

idle, connecting, connected, disconnected, suspended, failed, or closed. Show a “Reconnecting…” hint for disconnected and suspended.

ChatConfig | null

Your chat configuration from the platform. null until it loads: resume() loads it, or call chat.getConfig().

Show ChatConfig

string[]

Greetings. They already appear in messages before a conversation.

string[]

Conversation starters to show before the first message.

string

The name to show on AI Agent messages.

string

The chat title.

string

Logo URL.

string

Brand color.

string[]

Enabled features: file-upload, emoji, and transcription.

boolean

true while the stored conversation loads. Show a skeleton instead of an empty list.

chat.subscribe(listener) fires after every change with the new snapshot. To react to one kind of change, use chat.on(event, listener):

const unsubscribe = chat.on("message", (message) => {
  if (message.role !== "user") playNotificationSound();
});

Both return a function that unsubscribes. For every event, see the API reference.

Render by kind

Most messages are text. Handle the other kinds so the visitor sees the right prompt:

`kind`	Render
`text`	The message
`csat_request`	A rating prompt. See Satisfaction surveys
`email_verification_requested`	An email and code form. See Email verification
`email_verification_verified`	A confirmation that the email is verified
`error`	A short notice that something went wrong

content is markdown. To show formatting and links, render it with a markdown library and sanitize the HTML. If you only need plain text, render text.

Sending and failed messages

When the visitor sends a message, it appears at once with status: "sending". When the server confirms it, its id changes and messageUpdated fires with the old id as previousId. Render with dedupeKey ?? id as the key so the element isn’t recreated.

The SDK never retries a failed send, because sending isn’t idempotent. A failed message stays in messages with status: "failed". Show that it wasn’t delivered and let the visitor send it again.

Quick actions

AI Agent messages can offer buttons, written as tags in content. To answer one, send its message (or its label, if there’s no message) with sendMessage.

<QuickActions>
  <QuickActions.Item label="Track my order" message="Where is my order?" />
</QuickActions>

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

const itemPattern = /<QuickActions\.Item((?:\s+[\w-]+="[^"]*")*)\s*\/>/g;
const attributePattern = /([\w-]+)="([^"]+)"/g;

export function quickActionsOf(message: Message) {
  return [...(message.content ?? "").matchAll(itemPattern)].flatMap(
    ([, attributes = ""]) => {
      const values = new Map(
        [...attributes.matchAll(attributePattern)].map(
          ([, key = "", value = ""]) => [key, value],
        ),
      );
      const label = values.get("label");
      return label ? [{ label, message: values.get("message") ?? label }] : [];
    },
  );
}

import type { Message } from "@typewise/chat-sdk";
import { chat } from "./chat";
import { quickActionsOf } from "./quick-actions";

export function QuickActionButtons({ messages }: { messages: Message[] }) {
  const last = messages.at(-1);
  const actions = last && last.role !== "user" ? quickActionsOf(last) : [];

  return actions.map((action) => (
    <button key={action.label} onClick={() => chat.sendMessage(action.message)}>
      {action.label}
    </button>
  ));
}

Show the buttons only for the latest message, and only when it isn’t from the visitor. Selection lists and forms work the same way: send the chosen option’s text.

Typing indicators

Show activity below the last message, and send the visitor’s own typing state to Human Agents:

function activityLabel(activity: Activity) {
  if (activity.kind === "ai_thinking") return activity.text ?? "Thinking…";
  if (activity.kind === "agent_typing") return "Typing…";
  if (activity.kind === "waiting_for_agent") return "Reviewing…";
  return null;
}

input.addEventListener("input", () => chat.setTyping(input.value.length > 0));
form.addEventListener("submit", () => chat.setTyping(false));

Handoff and closed conversations

A Human Agent joined. When conversation.isHandledByHuman is true, show it in the header. activity stays idle until they start typing. Their messages have role: "agent" and an authorName.
The conversation closed. When conversation.isClosed is true, replace the composer with one of these:
- chat.reopen() lets the visitor keep writing in the same conversation, when canReopen is true.
- chat.startNewConversation() closes it and starts a fresh one.
The visitor ends it. For a close button, call chat.close().

Suggestions before the first message

Show config.suggestions as buttons while there’s no conversation yet:

Suggestions.tsx

export function Suggestions() {
  const { conversation, config } = useChat();
  if (conversation) return null;

  return config?.suggestions.map((suggestion) => (
    <button key={suggestion} onClick={() => chat.sendMessage(suggestion)}>
      {suggestion}
    </button>
  ));
}

Attachments, surveys, and verification
API reference
Chat configuration: greetings, suggestions, and branding in the platform

Migrate to Typewise

Channels

Integrations

Best practices

The state snapshot

Render by kind

Sending and failed messages

Quick actions

Typing indicators

Handoff and closed conversations

Suggestions before the first message

​The state snapshot

​Subscribe to changes

​Render by kind

​Sending and failed messages

​Quick actions

​Typing indicators

​Handoff and closed conversations

​Suggestions before the first message

​Related

The state snapshot

Subscribe to changes

Render by kind

Sending and failed messages

Quick actions

Typing indicators

Handoff and closed conversations

Suggestions before the first message

Related