Custom chat UI

What a custom chat UI changes

The customer supplies the launcher, layout, transcript, composer, and interaction design. A custom interface can be a page section, application panel, or character-based chat experience. It connects to the same visitor APIs used by stand.js and ui.js; loading those scripts is not required when the customer implements the conversation client.

Stand still selects an eligible responder, creates the conversation, delivers messages, runs configured Stand-in skills, supports rep takeover, and makes the conversation available in Chats and History. Site and path routing, availability, organization quotas, and plan entitlements continue to apply.

This is a supported beta integration surface for developers and AI coding agents. The guide documents the current endpoint and event contracts, implementation requirements, and a release checklist. Custom clients must track updates to that beta contract.

For a conventional inline transcript with a customized appearance, use stand-chatbox instead of implementing a visitor client. It shares the supplied widget’s rendering and lifecycle, with CSS variables, shadow parts, slots, and capped or growing height. A fully custom client remains useful for canvas scenes, games, character interfaces, or a different interaction model.

Stand’s custom chat examples

examples.stand.chatBeyond the
chat bubble.17 demos

The recordings show both custom conversation interfaces and page controls that open Stand’s supplied widget. Each example links to its live page and public-domain source.

Chapter 12 includes a live inline React client connected to Stand’s website coverage, with its actual client and component source available to copy or download. It starts a real conversation on the first send and restores it when returning to the chapter after in-page navigation. The standard floating widget is hidden on this chapter and returns on navigation away with its separate conversation preserved.

The stand.chat homepage hero is a custom chat UI too. Its ask line, under a drone light show, starts a real conversation with Stand’s eligible website responders inside the hero, on the same client as Chapter 12 with an opening greeting, hidden context about the show, and activation attribution. It shows streamed replies and typing indicators and keeps the conversation in session storage for the tab. When the availability lookup finds no eligible responder, the hero hides its ask line and chat unless the visitor already has a conversation. The drone show and story playback remain available. The regular floating widget remains a separate conversation.

The stand.chat homepage also has a pink cow with a question mark on its side. Selecting it unfolds a custom chat card. The first message starts a real conversation with Stand’s eligible website responders, using the cow’s opening greeting and hidden context about custom chat interfaces. The regular floating widget is hidden while this card is open.

The cow does not save its conversation in browser storage. Its close button, Escape, and backdrop end the conversation and dismiss the cow. If session creation is still pending, the returned session is ended even if the cow has already disappeared. This example is part of Stand’s own website; installing the standard widget does not add a cow to another website.

• Open the homepage hero chatAsk a question under the light show when an eligible responder is available. Sending a message starts a real conversation with Stand.
• Open the pink cow exampleShows the homepage cow when an eligible responder is available. Sending a message starts a real conversation with Stand.
• Open the Chapter 12 clientInteractive example reel, live inline chat, downloadable client source, and the visitor API guide.
• Website privacy policyThe owning policy for non-essential cookies and storage on Stand’s website.

• Automatic appearance waits for 30 seconds of visible time after the hero scrolls away and is suppressed once the visitor starts a chat in the regular widget or the homepage hero. A mounted chatbox with a pending first send or authenticated active conversation also suppresses the cow, even when non-essential storage is disabled; idle or ended boxes do not. Background time does not count, including when browser timers are suspended.
• The cow appears only after the availability lookup confirms an eligible responder. It stays hidden while the lookup is pending, returns no available responder, or fails. This also applies to ?pinkcow.
• Before appearing, the cow waits for modal dialogs, an open regular chat panel or expanded chatbox, and an unanswered consent banner. A modal or either chat panel opening mid-walk dismisses it. An idle inline chatbox or collapsed floating panel does not block it merely by being present.
• When the site’s non-essential storage policy permits, a cookie records that the cow appeared or that the visitor chatted instead and suppresses later automatic appearances. Rejected consent and a pending required consent decision prevent this cookie from being written, so the cow may return on a later visit.
• The homepage can run a PostHog experiment on the cow through the pink-cow feature flag. The flag is read only at the moment the cow would otherwise appear, so visitors in the experiment’s control group reach that moment but see no cow, and the same cookie policy suppresses later automatic appearances. Visitors whose cookie preference disables analytics storage are outside any experiment and see the cow as usual. Cookieless page usage counts do not enroll them in the experiment; ?pinkcow ignores the flag.
• WebGL is required. Automatic appearance is disabled when the browser reports data-saving mode. Reduced motion uses a stationary cow and a fade. The ?pinkcow homepage query skips the usual wait once an eligible responder is confirmed and follows the same cookie policy.

Visitor API lifecycle

• Custom chat UI protocol and implementation guideLive inline example and reusable source, plus request and response fields, WebSocket events, cards, recovery, analytics, and client requirements.

Authentication and page context

• Discovery and visitor session creation use the public Site ID. Subsequent HTTP calls use Authorization: Bearer <visitorToken>; the session WebSocket uses the token query parameter.
• A visitor token grants access only to its conversation. Keep it private and exclude it from logs and analytics. On closure, stop sends and reconnects, finish any permitted final reconciliation while still authorized, then clear saved credentials. On authorization failure, discard the unusable token and retain unconfirmed visitor text for an explicit new-chat flow.
• No developer API key, rep login, Keycloak token, or OpenAPI integration credential belongs in the browser client.
• visitorExternalId and visitorIdentityName provide the same unverified page-known identity as the widget identification API. They do not authenticate the visitor or authorize customer backend actions.
• Optional prompt context is retained for the responder and dashboard. A custom client must exclude system-prompt messages from the visitor transcript; hiding them is a display rule, so browser-supplied context must not contain secrets.

Required conversation behavior

• Show the matched responder’s identity and distinguish an AI Stand-in from a human. Update that identity when handoff or takeover cards arrive.
• Render the returned sensitive-data notice when configured and the Powered by Stand link when poweredByUrl is present. A custom interface does not change branding entitlements.
• Handle text, link cards, and system cards, including session start/end, human transfer, Stand-in takeover, and the recovery email follow-up flow. Preserve visitor choice in handoff and action-confirmation conversations.
• Treat AI streaming deltas and typing/status events as temporary display state. Reconcile final messages using server message IDs, sequence numbers, and client message IDs rather than appending duplicate replies.
• Provide loading, unavailable, sending, failed-send, reconnecting, and ended states. Restore the same authorized conversation across navigation when continuity is offered; do not create a new session just because the socket disconnects.
• Render untrusted text and links safely, support keyboard and mobile use, and keep controls consistent with the conversation language.
• Send greeting, activation, link-click, and branding-click events only for interactions the custom interface actually presents. Carry returned attribution IDs into session creation so analytics reflect that interface.

Availability and beta boundaries

• A successful availability lookup is not a reservation. The server revalidates the Site, responder, and capacity when a conversation starts; handle creation failure without inventing a local conversation.
• Custom appearance does not grant extra chats, remove Base branding, enable paid skills, or bypass disabled Sites or unavailable responders.
• Before registering, a client can send demo as siteId for discovery and session creation. Stand Chat’s demo Stand-in then answers from any page domain. Only that Stand-in responds, and the conversations are not visible in your account; your own responders, instructions, knowledge, skills, and History require your registered Site ID.
• The current session read returns a bounded recent-message snapshot, not an unlimited transcript export. Reps use History for retained conversation review and export.
• The visitor API does not support visitor file uploads or expose rep and organization management operations.
• The shipped widget remains a reference implementation. A generated visual prototype requires protocol integration and verification before it can handle Stand conversations.

Related features

• Stand chatbox — The stand-chatbox web component starts a complete Stand conversation inside the host page, with the supplied messaging engine, customizable surfaces, capped or continuously growing height, and an optional floating panel after engagement.
• Stand JavaScript API — The public window.StandChat API lets a website reveal its own chat entry points, inspect responder availability, open Stand with page-specific context, and identify a signed-in visitor.
• Visitor messaging and chat controls — The Stand widget gives website visitors a real-time text conversation with a matched rep or AI Stand-in. Visitors can send formatted messages, minimize or resize the window, end a conversation, and start another without leaving the website.
• Conversation continuity — Stand restores an active website conversation when the visitor reloads the page or moves around the same site in the same browser. The transcript, responder, conversation language, and session boundary remain intact instead of routing the visitor into a duplicate chat.
• AI-to-human handoff — A rep can move an active AI conversation to human handling without starting over. The dashboard offers immediate takeover or an invitation that waits for the visitor to accept.