Build your own chat interface.

Build a custom Stand chat experience for my website.
My idea: [the invitation, page context, where replies appear, and next step].
Match my website’s design. Start from the closest working example at
https://github.com/standchat/examples or the client source in this guide.
Contract: https://stand.chat/guide/custom-chat-ui (Beta).
Feature scope: https://stand.chat/features/custom-chat-ui.
Use siteId demo for a prototype; use [MY_SITE_ID] on my registered domain
for my responders. Never put account credentials in browser code.
First build one complete text conversation: discovery, one-time creation,
visitor-token HTTP sends, WebSocket receive, transcript reconciliation,
safe rendering, reload/reconnect recovery, and explicit end/new-chat.
Preserve AI/human identity, handoff, notices, attribution, link cards,
and the unanswered-chat email form when emitted.
Keep pending sends; reuse clientMessageId on retry. Do not automatically
replay ambiguous creates, confirm AI writes, or resend into a new chat.
Then add my visual experience, with keyboard, mobile, and reduced-motion
support. Run every applicable check in the guide’s launch checklist.

Replace the brackets with your idea and public Site ID. The examples are public-domain starting points; adapt their demo branding, content, and configuration before publishing.

// A small visitor client for the chapter 12 example. No widget globals or shared widget storage.
// REST sends provide an acknowledgement; the socket only receives live events.
export interface ChatMessage {
  messageId: string
  body: string
  type: string
  senderType: string
  seq: number
  clientMessageId?: string
}

export interface GuideChatState {
  phase: 'loading' | 'available' | 'unavailable' | 'active' | 'ended' | 'uncertain'
  connection: 'connecting' | 'online' | 'offline'
  busy: boolean
  error: string | null
  draft: string
  pending: { body: string; clientMessageId: string } | null
  messages: ChatMessage[]
  host: { name: string; kind: 'rep' | 'standin' | null; avatar?: string }
  notice: string
  poweredByUrl: string
  greeting: string
  followupOffered: boolean
}

export const INITIAL_CHAT_STATE: GuideChatState = {
  phase: 'loading', connection: 'offline', busy: false, error: null,
  draft: '', pending: null, messages: [],
  host: { name: 'Stand', kind: null }, notice: '', poweredByUrl: '',
  greeting: '', followupOffered: false,
}

interface StartFields { openingMessage?: string; prompt?: string; activationSource?: string; activationAnalyticsId?: string }

interface Config {
  apiBase: string
  wsBase: string
  siteId: string
  page: () => string
  storage?: Storage
  // Separate keys keep several clients on one site from sharing a saved chat.
  storageKey?: string
  // Optional session fields: a greeting recorded as the first message, hidden
  // context for the responder, and attribution for your own analytics. A
  // function is read when the conversation starts, so context can be current.
  start?: StartFields | (() => StartFields)
  // Optional: typing, standin.status and standin.delta frames, for a typing
  // indicator or streamed preview. They are never part of the transcript.
  onTransient?: (event: Record<string, unknown>) => void
}
type Json = Record<string, unknown>
const object = (value: unknown): Json => value && typeof value === 'object' ? value as Json : {}
const text = (value: unknown): string => typeof value === 'string' ? value : ''
const messages = (value: unknown): ChatMessage[] => (Array.isArray(value) ? value : []).filter(
  (item): item is ChatMessage => Boolean(item && typeof item.messageId === 'string'
    && typeof item.body === 'string' && typeof item.type === 'string'
    && typeof item.senderType === 'string' && Number.isFinite(item.seq)),
)
class HttpError extends Error {
  constructor(publicStatus: number) { super(`Request failed (${publicStatus}).`); this.status = publicStatus }
  status: number
}

export class GuideChatClient {
  private state = INITIAL_CHAT_STATE
  private session: { sessionId: string; visitorToken: string } | null = null
  private offer: Json = {}
  private listeners = new Set<() => void>()
  private mounted = false
  private initialized = false
  private epoch = 0
  private socket: WebSocket | null = null
  private timer: ReturnType<typeof setTimeout> | undefined
  private read: AbortController | null = null
  private retries = 0
  private uncertain = false
  private readonly key: string
  private readonly api: string

  constructor(private config: Config) {
    this.api = config.apiBase.replace(/\/$/, '')
    this.key = config.storageKey || `stand-guide-chapter-12:v1:${this.api}:${config.siteId}`
  }

  getSnapshot = (): GuideChatState => this.state
  subscribe = (listener: () => void): (() => void) => {
    this.listeners.add(listener)
    listener()
    return () => { this.listeners.delete(listener) }
  }

  private update(patch: Partial<GuideChatState>) {
    this.state = { ...this.state, ...patch }
    try {
      this.config.storage?.setItem(this.key, JSON.stringify({
        session: this.session, uncertain: this.uncertain, phase: this.state.phase,
        draft: this.state.draft, pending: this.state.pending,
        host: this.state.host, notice: this.state.notice,
        poweredByUrl: this.state.poweredByUrl, greeting: this.state.greeting,
        messages: this.state.messages.slice(-500),
      }))
    } catch { /* Storage can be denied or full; this client still works in memory. */ }
    this.listeners.forEach(listener => listener())
  }

  mount(): () => void {
    this.mounted = true
    if (!this.initialized) {
      this.initialized = true
      try {
        const saved = object(JSON.parse(this.config.storage?.getItem(this.key) || '{}'))
        const session = object(saved.session)
        if (text(session.sessionId) && text(session.visitorToken)) {
          this.session = { sessionId: text(session.sessionId), visitorToken: text(session.visitorToken) }
        }
        this.uncertain = saved.uncertain === true && !this.session
        const pending = object(saved.pending)
        const host = object(saved.host)
        this.state = { ...INITIAL_CHAT_STATE,
          phase: !this.session && saved.phase === 'ended' ? 'ended' : 'loading',
          draft: text(saved.draft), messages: messages(saved.messages),
          pending: (this.session || saved.phase === 'ended') && text(pending.body) && text(pending.clientMessageId)
            ? { body: text(pending.body), clientMessageId: text(pending.clientMessageId) } : null,
          host: { name: text(host.name) || 'Stand', avatar: text(host.avatar),
            kind: host.kind === 'rep' || host.kind === 'standin' ? host.kind : null },
          notice: text(saved.notice), poweredByUrl: text(saved.poweredByUrl), greeting: text(saved.greeting),
        }
      } catch { /* Ignore corrupt or unavailable storage. */ }
      this.update({})
    }
    const epoch = ++this.epoch
    if (!this.state.busy && this.state.phase !== 'ended') void this.retry()
    return () => {
      if (epoch !== this.epoch) return
      this.mounted = false
      ++this.epoch
      this.disconnect()
      this.read?.abort()
      // Mutations intentionally finish: a create response still needs saving.
    }
  }

  setDraft = (draft: string) => { this.update({ draft }) }

  private async request(path: string, body?: Json, method = body ? 'POST' : 'GET', signal?: AbortSignal): Promise<Json> {
    const timeout = new AbortController()
    const abort = () => timeout.abort()
    const timer = setTimeout(abort, 15000)
    signal?.addEventListener('abort', abort, { once: true })
    if (signal?.aborted) abort()
    try {
      const response = await fetch(this.api + path, {
        method, credentials: 'omit', signal: timeout.signal,
        headers: {
          ...(body ? { 'Content-Type': 'application/json' } : {}),
          ...(this.session ? { Authorization: `Bearer ${this.session.visitorToken}` } : {}),
        },
        ...(body ? { body: JSON.stringify(body) } : {}),
      })
      if (!response.ok) throw new HttpError(response.status)
      return object(await response.json())
    } finally {
      clearTimeout(timer)
      signal?.removeEventListener('abort', abort)
    }
  }

  private path(suffix = '') { return `/v1/sessions/${encodeURIComponent(this.session!.sessionId)}${suffix}` }

  private merge(incoming: ChatMessage[]) {
    const byId = new Map(this.state.messages.map(message => [message.messageId, message]))
    incoming.forEach(message => byId.set(message.messageId, message))
    const transcript = [...byId.values()].sort((a, b) => a.seq - b.seq)
    let host = this.state.host
    let followupOffered = false
    for (const message of transcript) {
      if (message.senderType === 'rep') followupOffered = false
      if (message.type !== 'system-card' && message.senderType !== 'system-card') continue
      try {
        const card = object(JSON.parse(message.body))
        if (card.cardType === 'handoff' || card.cardType === 'human-transfer') {
          host = { name: text(card.repName) || host.name, avatar: text(card.repAvatar), kind: 'rep' }
          followupOffered = false
        } else if (card.cardType === 'session-start' || card.cardType === 'standin-takeover') {
          host = { name: text(card.standinName) || host.name, avatar: text(card.standinAvatar) || host.avatar, kind: 'standin' }
          followupOffered = false
        } else if (card.cardType === 'rep-followup-offer') followupOffered = true
        else if (card.cardType === 'rep-followup-confirmation' || card.cardType === 'session-end') followupOffered = false
      } catch { /* Unknown/malformed cards never execute code. */ }
    }
    const pending = this.state.pending
    this.update({ messages: transcript, host, followupOffered,
      pending: pending && transcript.some(m => m.clientMessageId === pending.clientMessageId) ? null : pending })
  }

  private applySession(data: Json) {
    if (data.sessionId !== this.session?.sessionId) throw new Error('Unexpected session response')
    const participant = (Array.isArray(data.participants) ? data.participants : []).map(object).find(p => p.isRep === true)
    if (participant) this.update({ host: { ...this.state.host,
      name: text(participant.name) || this.state.host.name,
      avatar: text(participant.avatar) || this.state.host.avatar } })
    this.merge(messages(data.messages))
    if (data.status !== 'active') this.finish()
    else this.update({ phase: 'active', error: null })
  }

  private finish(error: string | null = null) {
    this.disconnect()
    this.read?.abort()
    this.session = null
    this.uncertain = false
    // Keep unresolved text and its ID: an in-flight HTTP response may still
    // confirm it after closure. Otherwise the visitor can copy or review it.
    this.update({ phase: 'ended', connection: 'offline', followupOffered: false, error })
  }

  private handleFailure(error: unknown, fallback: string) {
    if (error instanceof HttpError && [401, 403, 404].includes(error.status) && this.session) {
      this.finish('This conversation is no longer available. Start a new chat to continue.')
    } else this.update({ error: fallback })
  }

  retry = async () => {
    if (!this.mounted || this.state.busy || this.state.phase === 'ended') return
    this.disconnect()
    this.read?.abort()
    const read = new AbortController()
    this.read = read
    const epoch = this.epoch
    if (this.uncertain) {
      this.update({ phase: 'uncertain', error: 'The previous start could not be confirmed. It may have created a chat. Choose New chat to try again.' })
      return
    }
    this.update({ error: null, ...(this.session ? { connection: 'connecting' } : { phase: 'loading' }) })
    try {
      if (this.session) {
        const data = await this.request(this.path('?messageLimit=500'), undefined, 'GET', read.signal)
        if (!this.mounted || epoch !== this.epoch || read.signal.aborted) return
        this.applySession(data)
        if (this.session) this.connect(epoch)
      } else {
        const query = new URLSearchParams({ siteId: this.config.siteId, page: this.config.page(), greetingsEnabled: 'false' })
        const offer = await this.request(`/v1/reps/find?${query}`, undefined, 'GET', read.signal)
        if (!this.mounted || epoch !== this.epoch || read.signal.aborted) return
        this.offer = offer
        const available = offer.available === true && Boolean(text(offer.standinProfileId) || text(offer.repId))
        this.update({ phase: available ? 'available' : 'unavailable',
          host: { name: text(offer.repName) || 'Stand', avatar: text(offer.avatar), kind: offer.responderType === 'standin' ? 'standin' : offer.responderType === 'rep' ? 'rep' : null },
          notice: text(offer.sensitiveNoticeText), poweredByUrl: text(offer.poweredByUrl), greeting: '' })
      }
    } catch (error) {
      if (!this.mounted || epoch !== this.epoch || read.signal.aborted) return
      this.handleFailure(error, 'Could not connect. Your draft is saved; try again.')
      if (this.session) this.scheduleReconnect()
      else if (this.getSnapshot().phase !== 'ended') this.update({ phase: 'unavailable' })
    }
  }

  private disconnect() {
    clearTimeout(this.timer)
    this.timer = undefined
    if (this.socket) {
      this.socket.onclose = null
      this.socket.onmessage = null
      this.socket.onerror = null
      this.socket.close()
      this.socket = null
    }
  }

  private scheduleReconnect() {
    if (!this.mounted || !this.session || this.timer) return
    this.update({ connection: 'offline' })
    if (this.retries >= 5) {
      this.update({ error: 'Connection paused. Retry connection to check for replies.' })
      return
    }
    const delay = Math.min(1000 * 2 ** this.retries++, 15000) + Math.random() * 300
    this.timer = setTimeout(() => { this.timer = undefined; void this.retry() }, delay)
  }

  private connect(epoch: number) {
    if (!this.mounted || !this.session || epoch !== this.epoch) return
    // Use the configured trusted origin, not an arbitrary URL from an event.
    const url = new URL(`${this.config.wsBase.replace(/\/$/, '')}${this.path().replace('/v1/sessions/', '/ws/sessions/')}`)
    url.searchParams.set('token', this.session.visitorToken)
    const socket = new WebSocket(url)
    this.socket = socket
    const current = () => this.mounted && epoch === this.epoch && this.socket === socket && Boolean(this.session)
    this.timer = setTimeout(() => {
      this.timer = undefined
      if (current()) { this.disconnect(); this.scheduleReconnect() }
    }, 10000)
    socket.onmessage = event => {
      if (!current()) return
      let data: Json
      try { data = object(JSON.parse(event.data)) } catch { return }
      if (data.sessionId && data.sessionId !== this.session?.sessionId) return
      if (data.type === 'connected') {
        clearTimeout(this.timer)
        this.timer = undefined
        this.update({ connection: 'online', error: null })
        // Subscribe first, then merge a snapshot to cover missed messages.
        void this.request(this.path('?messageLimit=500'), undefined, 'GET', this.read?.signal).then(snapshot => {
          if (current()) { this.applySession(snapshot); this.retries = 0 }
        }).catch(error => {
          if (!current()) return
          this.handleFailure(error, 'Could not refresh replies. Reconnecting to recover.')
          this.disconnect()
          this.scheduleReconnect()
        })
      } else if (data.type === 'session.closed') this.finish()
      else if (data.type === 'typing' || data.type === 'standin.status' || data.type === 'standin.delta') {
        this.config.onTransient?.(data)
      } else {
        const incoming = messages([data])
        if (incoming.length) this.merge(incoming) // Ignore unknown frames.
      }
    }
    socket.onclose = () => {
      if (current()) { this.disconnect(); this.scheduleReconnect() }
    }
    socket.onerror = () => { /* onclose drives bounded recovery. */ }
  }

  send = async () => {
    if (this.state.busy) return
    const body = this.state.pending?.body || this.state.draft.trim()
    if (!body || !['available', 'active'].includes(this.state.phase)) return
    this.update({ busy: true, error: null })
    let recover = false
    try {
      if (!this.session) {
        const start = typeof this.config.start === 'function' ? this.config.start() : this.config.start
        this.uncertain = true
        this.update({ draft: body }) // Persist an ambiguous-create marker before sending.
        const data = await this.request('/v1/sessions', {
          siteId: this.config.siteId, page: this.config.page(), initialMessage: body,
          ...(text(this.offer.standinProfileId) ? { standinProfileId: this.offer.standinProfileId } : { repId: this.offer.repId }),
          includeOpeningGreeting: Boolean(start?.openingMessage), showId: this.offer.showId,
          ...start,
          visitorLanguage: navigator.language, visitorLanguages: navigator.languages,
          pageLanguage: document.documentElement.lang,
        })
        if (!text(data.sessionId) || !text(data.visitorToken)) throw new Error('Incomplete session credentials')
        this.session = { sessionId: text(data.sessionId), visitorToken: text(data.visitorToken) }
        this.uncertain = false
        this.update({ draft: '', pending: null })
        this.applySession(data)
        if (this.mounted && this.session) this.connect(this.epoch)
      } else {
        const pending = this.state.pending || { body, clientMessageId: crypto.randomUUID() }
        this.update({ pending, draft: '' })
        const data = await this.request(this.path('/messages'), { ...pending, type: 'text' })
        const accepted = messages([data])
        if (!accepted.length) throw new Error('Incomplete message response')
        this.merge(accepted)
      }
    } catch (error) {
      if (!this.session && this.uncertain) {
        // A definite rejection can be retried after fresh discovery; a lost
        // response must never trigger an automatic second create.
        this.uncertain = !(error instanceof HttpError && error.status >= 400 && error.status < 500)
        this.update({ phase: this.uncertain ? 'uncertain' : 'unavailable',
          error: this.uncertain ? 'We could not confirm whether the chat started. Choose New chat to try again.' : 'Chat could not start. Check availability and try again.' })
      } else {
        this.handleFailure(error, this.state.phase === 'ended'
          ? 'Delivery was not confirmed before the chat ended. Choose New chat to review your saved message before sending again.'
          : 'Message not confirmed. Retry message to check delivery without sending a duplicate.')
        recover = error instanceof HttpError && error.status === 409
      }
    } finally {
      this.update({ busy: false })
      // Returning during an in-flight send skips mount recovery until it settles.
      if (this.mounted && this.session && (recover || (!this.socket && !this.timer))) void this.retry()
    }
  }

  end = async () => {
    // A close request must outlive an in-flight mutation, even after unmount.
    // Creation may still return credentials that we need in order to end it.
    while (this.state.busy) {
      await new Promise<void>(resolve => {
        const unsubscribe = this.subscribe(() => {
          if (this.state.busy) return
          unsubscribe()
          resolve()
        })
      })
    }
    if (!this.session) return
    this.update({ busy: true, error: null })
    try { await this.request(this.path(), undefined, 'DELETE'); this.finish() }
    catch (error) { this.handleFailure(error, 'Could not confirm the end of this chat. Retry End chat or reconnect.') }
    finally { this.update({ busy: false }) }
  }

  newChat = async () => {
    if (this.state.busy || this.session) return
    this.uncertain = false
    this.retries = 0
    // Starting over only prepares an editable draft. It never replays a send
    // into a different conversation or reuses that conversation's message ID.
    const pendingBody = this.state.pending?.body
    const draft = pendingBody && pendingBody !== this.state.draft
      ? [pendingBody, this.state.draft].filter(Boolean).join('\n\n')
      : this.state.draft || pendingBody || ''
    this.update({ ...INITIAL_CHAT_STATE, draft })
    await this.retry()
  }

  submitEmail = async (email: string) => {
    if (!this.session || !this.state.followupOffered || this.state.busy) return
    this.update({ busy: true, error: null })
    try { await this.request(this.path('/followup-request'), { email }); this.finish('Your follow-up request was sent.') }
    catch (error) {
      if (error instanceof HttpError && error.status === 409) {
        this.update({ followupOffered: false, error: 'That offer has changed. Retry connection to refresh the conversation.' })
      } else this.handleFailure(error, 'Could not submit your email. Check it and try again.')
    } finally { this.update({ busy: false }) }
  }

  trackLinkClick = async (messageId: string, url: string) => {
    if (!this.session) return
    try { await this.request(this.path('/link-clicks'), { messageId, url }) }
    catch { /* Best-effort tracking never blocks navigation. */ }
  }
}

Framework-independent visitor protocol, storage, recovery, and connection lifecycle.

import { useEffect, useRef, useState } from 'react'

import { getEmbedConfig } from '@/lib/embed'
import { GuideChatClient, INITIAL_CHAT_STATE, type ChatMessage } from '@/lib/guideChatClient'

// This module is imported only by chapter 12. Nothing starts until it mounts.
// Keep one client across Next.js navigation; mount() owns its live connection.
let chapterClient: GuideChatClient | undefined

function getChapterClient() {
  if (!chapterClient) {
    let storage: Storage | undefined
    try { storage = window.sessionStorage } catch { /* In-memory chat still works. */ }
    const { apiBase, wsBase } = getEmbedConfig()
    chapterClient = new GuideChatClient({
      apiBase,
      wsBase,
      siteId: 'f8592bc6-af7f-4dca-8c7f-65e9da38da49',
      page: () => window.location.href,
      storage,
    })
  }
  return chapterClient
}

const buttonClass = 'rounded-md bg-aqua-2 px-3 py-2 text-sm font-bold text-white transition hover:bg-aqua-1 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-aqua-2 disabled:cursor-not-allowed disabled:bg-snow-2 disabled:text-ash-4'
const secondaryClass = 'rounded px-1 py-1 text-sm font-semibold text-aqua-2 underline underline-offset-4 hover:text-aqua-1 focus-visible:outline focus-visible:outline-2 focus-visible:outline-aqua-2 disabled:cursor-not-allowed disabled:text-ash-5'

export function InlineGuideChat() {
  const [state, setState] = useState(INITIAL_CHAT_STATE)
  const [email, setEmail] = useState('')
  const client = useRef<GuideChatClient | undefined>(undefined)
  const transcript = useRef<HTMLDivElement>(null)
  const keepAtBottom = useRef(true)
  const form = useRef<HTMLFormElement>(null)

  useEffect(() => {
    const current = getChapterClient()
    client.current = current
    const unsubscribe = current.subscribe(() => setState(current.getSnapshot()))
    const unmount = current.mount()
    return () => {
      unsubscribe()
      unmount()
      client.current = undefined
    }
  }, [])

  useEffect(() => {
    if (transcript.current && keepAtBottom.current) {
      transcript.current.scrollTop = transcript.current.scrollHeight
    }
  }, [state.messages, state.pending])

  const canCompose = state.phase === 'available' || state.phase === 'active'
  const connectionLabel = state.phase === 'active'
    ? state.connection === 'online' ? 'Connected' : state.connection === 'connecting' ? 'Connecting…' : 'Connection interrupted'
    : state.phase === 'available' ? 'Available' : state.phase === 'loading' ? 'Checking availability…' : state.phase === 'ended' ? 'Chat ended' : state.phase === 'uncertain' ? 'Start not confirmed' : 'Currently unavailable'
  const attribution = safeUrl(state.poweredByUrl)

  return (
    <section aria-label="Live custom chat example" className="ph-no-capture min-w-0 overflow-hidden rounded-xl bg-white text-ash-2 shadow-2xl shadow-black/30 ring-1 ring-white/10">
      <div className="border-b border-snow-2 p-5">
        <p className="text-xs font-bold uppercase tracking-[0.18em] text-aqua-2">Live custom UI · Beta</p>
        <h2 className="mt-2 font-display text-2xl font-bold leading-tight">A real conversation, your own UI.</h2>
        <p className="mt-2 text-sm leading-6 text-ash-4">Talk with the Stand team or their AI Stand-in. Sending your first message starts a real chat.</p>
        <a href="#live-example-source" className={`${secondaryClass} mt-2 inline-block`}>View the code</a>
      </div>

      <div className="flex items-center justify-between gap-3 border-b border-snow-2 bg-snow-5 px-5 py-3">
        <div className="min-w-0">
          <p className="break-words text-sm font-bold">{state.host.name || 'Stand team'}</p>
          <p className="mt-0.5 text-xs text-ash-4">{state.host.kind === 'standin' ? 'AI Stand-in' : state.host.kind === 'rep' ? 'Human rep' : 'Stand chat'}</p>
        </div>
        <p role="status" className="text-right text-xs text-ash-4">{connectionLabel}</p>
      </div>

      <div
        ref={transcript}
        role="log"
        aria-label="Conversation messages"
        aria-live="polite"
        aria-relevant="additions text"
        onScroll={() => {
          const panel = transcript.current
          if (panel) keepAtBottom.current = panel.scrollHeight - panel.scrollTop - panel.clientHeight < 48
        }}
        className="h-64 space-y-3 overflow-y-auto overscroll-contain p-5"
      >
        {state.messages.length === 0 && (
          <p className="whitespace-pre-wrap break-words rounded-lg bg-snow-4 p-4 text-sm leading-6 text-ash-3">
            {state.phase === 'unavailable' ? 'Nobody is available for a new chat right now. You can check again in a moment.' : state.greeting || 'Ask us about Stand or building your own chat interface.'}
          </p>
        )}
        {state.messages.map((message) => (
          <Message key={message.messageId} message={message} onLinkClick={(url) => void client.current?.trackLinkClick(message.messageId, url)} />
        ))}
        {state.pending && (
          <div className="ml-6 rounded-lg bg-aqua-3/15 p-3 text-sm leading-6">
            <p className="text-xs font-bold text-ash-4">You · {state.busy ? 'Sending…' : 'Delivery not confirmed'}</p>
            <p className="whitespace-pre-wrap break-words">{state.pending.body}</p>
          </div>
        )}
      </div>

      <div className="space-y-3 border-t border-snow-2 p-5">
        {state.error && <p role="alert" className="rounded-md bg-gold-3/15 p-3 text-sm leading-6 text-ash-3">{state.error}</p>}
        {state.phase === 'ended' && <p className="text-sm leading-6 text-ash-4">This conversation has ended. You can start a new one below.</p>}
        {state.phase === 'uncertain' && <p className="text-sm leading-6 text-ash-4">The first request may have reached Stand. Starting again could create another conversation; your draft is kept.</p>}
        {state.notice && <p className="whitespace-pre-wrap break-words text-xs leading-5 text-ash-4">{state.notice}</p>}

        {canCompose && (
          <form ref={form} onSubmit={(event) => { event.preventDefault(); keepAtBottom.current = true; void client.current?.send() }}>
            <label htmlFor="guide-chat-message" className="text-sm font-semibold">Your message</label>
            <textarea
              id="guide-chat-message"
              rows={2}
              value={state.draft}
              onChange={(event) => client.current?.setDraft(event.target.value)}
              onKeyDown={(event) => {
                if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing) {
                  event.preventDefault()
                  if (!state.busy && !state.pending && state.draft.trim()) form.current?.requestSubmit()
                }
              }}
              disabled={state.busy || Boolean(state.pending)}
              placeholder="What would you like to know?"
              className="mt-2 block w-full resize-y rounded-md border border-snow-1 bg-white px-3 py-2 text-sm leading-6 text-ash-2 placeholder:text-ash-5 focus:border-aqua-2 focus:outline-none focus:ring-2 focus:ring-aqua-3/30 disabled:bg-snow-4"
            />
            <div className="mt-3 flex items-center justify-between gap-3">
              <button type="submit" disabled={state.busy || Boolean(state.pending) || !state.draft.trim()} className={buttonClass}>Send message</button>
              {state.phase === 'active' && <button type="button" onClick={() => void client.current?.end()} disabled={state.busy} className={secondaryClass}>End chat</button>}
            </div>
          </form>
        )}

        {state.followupOffered && state.phase === 'active' && (
          <form className="rounded-lg bg-snow-4 p-3" onSubmit={(event) => { event.preventDefault(); void client.current?.submitEmail(email) }}>
            <label htmlFor="guide-chat-email" className="text-sm font-semibold">Your email</label>
            <p id="guide-chat-email-help" className="mt-1 text-xs leading-5 text-ash-4">Leave your email for the team to follow up on this conversation.</p>
            <input id="guide-chat-email" type="email" autoComplete="email" required disabled={state.busy} value={email} onChange={(event) => setEmail(event.target.value)} aria-describedby="guide-chat-email-help" className="mt-2 block w-full rounded-md border border-snow-1 px-3 py-2 text-sm focus:border-aqua-2 focus:outline-none focus:ring-2 focus:ring-aqua-3/30" />
            <button type="submit" disabled={state.busy || !email.trim()} className={`${buttonClass} mt-3`}>Request follow-up</button>
          </form>
        )}

        {state.pending && !state.busy && state.phase === 'active' && <button type="button" onClick={() => void client.current?.send()} className={secondaryClass}>Retry message</button>}
        {!state.pending && !state.busy && (state.phase === 'unavailable' || (Boolean(state.error) && state.phase !== 'ended' && state.phase !== 'uncertain') || (state.phase === 'active' && state.connection === 'offline')) && <button type="button" onClick={() => void client.current?.retry()} className={secondaryClass}>Retry connection</button>}
        {(state.phase === 'ended' || state.phase === 'uncertain') && <button type="button" onClick={() => { setEmail(''); keepAtBottom.current = true; void client.current?.newChat() }} disabled={state.busy} className={buttonClass}>New chat</button>}

        <div className="flex flex-wrap items-center justify-between gap-2 pt-1 text-xs leading-5 text-ash-4">
          <span>Replies appear when complete.</span>
          {attribution && <a href={attribution} target="_blank" rel="noopener noreferrer" className="font-semibold text-aqua-2 underline underline-offset-2">Powered by Stand</a>}
        </div>
      </div>
    </section>
  )
}

function safeUrl(value: unknown): string | null {
  if (typeof value !== 'string') return null
  try {
    const url = new URL(value)
    return url.protocol === 'https:' || url.protocol === 'http:' ? url.href : null
  } catch { return null }
}

function Message({ message, onLinkClick }: { message: ChatMessage; onLinkClick: (url: string) => void }) {
  if (message.type === 'system-prompt' || message.senderType === 'system-prompt') return null
  if (message.type === 'text' || message.type === 'standin-idle-prompt') {
    return (
      <div className={`${message.senderType === 'visitor' ? 'ml-6 bg-aqua-3/15' : 'mr-6 bg-snow-4'} rounded-lg p-3 text-sm leading-6`}>
        <p className="text-xs font-bold text-ash-4">{message.senderType === 'visitor' ? 'You' : message.senderType === 'standin' ? 'AI Stand-in' : 'Stand team'}</p>
        <p className="whitespace-pre-wrap break-words">{message.body}</p>
      </div>
    )
  }

  let card: Record<string, unknown>
  try {
    const parsed: unknown = JSON.parse(message.body)
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
    card = parsed as Record<string, unknown>
  } catch { return null }

  if (message.type === 'link-card') {
    const url = safeUrl(card.url)
    if (!url) return null
    return <a href={url} target="_blank" rel="noopener noreferrer" onClick={() => onLinkClick(url)} className="mr-6 block rounded-lg border border-aqua-3 bg-white p-3 text-sm leading-6 text-aqua-2 hover:bg-snow-5"><span className="break-words font-bold underline underline-offset-2">{typeof card.title === 'string' ? card.title : url}</span>{typeof card.description === 'string' && <span className="mt-1 block whitespace-pre-wrap break-words text-ash-3">{card.description}</span>}</a>
  }
  if (message.type !== 'system-card') return null
  const labels: Record<string, string> = {
    'session-start': 'Conversation started with an AI Stand-in.',
    handoff: 'A human rep has joined the chat.',
    'human-transfer': 'Your conversation has moved to a human rep.',
    'standin-takeover': 'An AI Stand-in has joined the chat.',
    'session-end': 'Conversation ended.',
    'rep-followup-offer': 'The team is offering to follow up by email.',
    'rep-followup-confirmation': 'Your follow-up request has been received.',
  }
  if (typeof card.cardType !== 'string' || !Object.prototype.hasOwnProperty.call(labels, card.cardType)) return null
  return <p className="whitespace-pre-wrap break-words rounded-md border border-snow-2 p-3 text-xs leading-5 text-ash-4">{labels[card.cardType]}{typeof card.message === 'string' ? ` ${card.message}` : ''}</p>
}

React presentation, accessible controls, safe message rendering, and chapter-scoped mounting.

const api = 'https://api.stand.chat';
const siteId = 'YOUR_SITE_ID';
const page = window.location.href;
const query = new URLSearchParams({
  siteId, page, greetingsEnabled: 'false'
});
const discoveryResponse = await fetch(api + '/v1/reps/find?' + query, {
  credentials: 'omit'
});
if (!discoveryResponse.ok) throw new Error('Discovery failed: ' + discoveryResponse.status);
const offer = await discoveryResponse.json();
// Show an unavailable state unless offer.available is true.
// Preserve this response for create and attribution; never fabricate IDs.

Replace YOUR_SITE_ID and run on that registered website, or use demo to try the protocol with Stand Chat’s demo Stand-in before registering. These excerpts use top-level await: put them in a JavaScript module or an async function. This minimal client does not display a greeting; request greetingsEnabled: true only if yours does. Poll sparingly after user action or a bounded retry delay.

if (!offer.available || !(offer.standinProfileId || offer.repId)) {
  throw new Error('No responder available');
}
const createResponse = await fetch(api + '/v1/sessions', {
  method: 'POST',
  credentials: 'omit',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    page: window.location.href,
    siteId,
    ...(offer.standinProfileId
      ? { standinProfileId: offer.standinProfileId }
      : { repId: offer.repId }),
    initialMessage: 'Can you help me choose?',
    includeOpeningGreeting: false,
    showId: offer.showId,
    visitorLanguage: navigator.language,
    visitorLanguages: navigator.languages,
    pageLanguage: document.documentElement.lang
  })
});
if (!createResponse.ok) throw new Error('Start failed: ' + createResponse.status);
const session = await createResponse.json();
if (!session.sessionId || !session.visitorToken) {
  throw new Error('Incomplete session credentials');
}
// Preserve credentials; render session.messages; connect and recover.
// This example intentionally does not persist an opening greeting.

The snippets share api, siteId, offer, and session as integration state. Wire the result to your UI reducer and the recovery requirements below; they are not a complete UI.

const pending = {
  body: 'What is included?',
  type: 'text',
  clientMessageId: crypto.randomUUID()
};
async function sendPending() {
  const response = await fetch(
    api + '/v1/sessions/' + encodeURIComponent(session.sessionId) + '/messages',
    {
      method: 'POST', credentials: 'omit',
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + session.visitorToken
      },
      body: JSON.stringify(pending)
    }
  );
  if (!response.ok) throw new Error('Send failed: ' + response.status);
  return response.json(); // Merge by messageId/clientMessageId.
}
// Retry sendPending with this same pending object after recovery.
// Create a NEW ID only for a new logical visitor message.

REST sends can be combined with WebSocket receive. Both transports may deliver the same canonical message; deduplicate it.

const socketUrl = new URL(session.websocketUrl);
if (socketUrl.protocol !== 'wss:' || socketUrl.host !== new URL(api).host) {
  throw new Error('Unexpected WebSocket origin');
}
socketUrl.searchParams.set('token', session.visitorToken);
const socket = new WebSocket(socketUrl);
// Register message/close/error handlers immediately.
// Send only when socket.readyState === WebSocket.OPEN:
const visitorFrame = {
  type: 'message', messageType: 'text',
  body: 'Can a person join?', clientMessageId: crypto.randomUUID()
};
// socket.send(JSON.stringify(visitorFrame));
// socket.send(JSON.stringify({ type: 'typing', active: true }));
// Send active:false on submit, blur, or an idle timeout.

Keep a pending send until a canonical response/echo confirms it. A successful socket.send is not a delivery acknowledgement.

{
  "event": "message",
  "type": "text",
  "messageId": "message-123",
  "sessionId": "session-123",
  "senderId": "visitor-123",
  "senderType": "visitor",
  "body": "Can a person join?",
  "sentAt": "2026-09-15T12:00:00Z",
  "seq": 3,
  "clientMessageId": "client-message-123"
}

IDs are opaque strings. seq orders persisted transcript messages; sentAt is not a deduplication key. Optional fields may be null or absent.