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.

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.

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, exclude it from logs and analytics, and clear saved credentials when the conversation ends or authorization fails.
• 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.
• 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 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. Stand supports immediate takeover, a consent-based offer to join, and implicit takeover when the rep begins typing a reply.