Stand JavaScript API | Stand Feature Reference

Before you begin

Plan availability: All plans.

Prerequisite: An installed Stand widget and permission to change the host website’s JavaScript.

Key boundary: The API can open and contextualize Stand, but it does not expose session tokens, WebSocket credentials, transcripts, or internal widget state.

01

What the JavaScript API controls

window.StandChat is the public interface created by the Stand embed script. Use it when an existing website control—such as a pricing button, comparison table, booking flow, or application menu—should open Stand without using Stand’s own button or card component.

The API separates script readiness from responder availability. The global object may already exist while Stand is still looking for a live rep or AI Stand-in, so custom UI should use whenAvailable(...) before becoming visible or actionable.

Calls operate on the widget installed on the current page. They do not provide server-side access to Stand data.

A website that renders its own transcript and message composer uses the separate custom chat UI beta and visitor API contract.

02

Connect a custom page control

Install Stand on the page first. Then wait until both the page control and window.StandChat exist, register an availability callback, and reveal the control only after the callback runs.

To try these calls before creating a Site, use data-stand-id="demo". Stand Chat’s demo Stand-in then answers and receives the greetings, visitor messages, prompts, and identity the page supplies. Configuration saved in Stand, such as behavior rules or knowledge bases, requires your own Site. Widget installation describes demo mode.

Open Stand from an existing button

<button type="button" data-ask-pricing hidden>Ask about pricing</button>
<script defer src="https://cdn.stand.chat/widget/stand.js" data-stand-id="YOUR-SITE-ID"></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    const button = document.querySelector("[data-ask-pricing]")
    const stand = window.StandChat
    if (!button || !stand) return

    stand.whenAvailable((responder) => {
      button.hidden = false
      button.textContent = `Ask ${responder.name || "us"} about pricing`
    })
    button.addEventListener("click", () => {
      if (stand.isAvailable()) {
        stand.openChat("What would you like to know about our plans?")
      }
    })
  }, { once: true })
</script>

Use your Site’s generated embed snippet. This static-page example waits for DOMContentLoaded, which follows parser-inserted defer scripts. Dynamically loaded scripts and single-page applications need their own readiness and cleanup handling.

03

Public methods

Method	Behavior	Return or timing
`initiallyHideChatButton()`	Suppresses the default floating launcher until page code opens Stand. Behavior rules do not reveal it.	Returns nothing. A later `openChat(...)` reveals and opens the widget. The `data-stand-hide-button` script attribute applies the same setting without page code.
`openChat(repMessage = "")`	Opens chat. A non-empty string supplies the greeting for a new session; it does not replace an existing transcript.	Returns nothing. A request made while the UI loads is queued. Of the requests made before Stand finds a responder, only the latest is kept; later requests are applied in order. If no responder is available, nothing opens.
`openChat(repMessage, visitorMessage, prompt)`	Sends non-blank visitor text to the current or new session. The private prompt is attached only when a new session is created.	The visitor message is visible in the transcript; the prompt is not visitor-authored text.
`openChat(repMessage, options)`	Accepts `visitorMessage`, `prompt`, `visitorIdentity`, `sourceType`, `analyticsId`, and `interaction` for custom integrations.	`visitorIdentity` applies to the session created by this open request.
`identify(identity)`	Sets `{ externalId, name? }` for future sessions, or clears it with `null`.	Returns nothing; it does not modify an active session.
`isAvailable()`	Reports whether Stand has found an eligible responder.	Boolean. `false` also covers a lookup that has not finished.
`whenAvailable(callback)`	Runs the callback with `{ available, human, name, title, avatarUrl, brandName }` when a responder is available.	Runs immediately if already available and returns an unsubscribe function.
`isHuman()`	Reports whether the available responder is a live person.	`false` can mean AI or not yet available.
`getName()`, `getTitle()`, `getAvatar()`	Read responder identity for custom page UI.	Return a string, or an empty string before availability.

04

Opening messages and attribution

repMessage supplies the greeting for a new session; an empty value uses the configured greeting. Opening an existing session preserves its greeting and transcript.
Until the visitor sends a first message, each open request, including a Stand button, Stand card, or the floating launcher, replaces the previous request’s greeting, prompt, and attribution. The session is created with the values of the latest request.
visitorMessage becomes a visitor-authored transcript message. It starts a new conversation when needed, or appends to the current conversation. Empty or whitespace-only values are ignored.
prompt is attached to a newly created session and retained for the responder. A later open without a prompt clears an unsent one. It does not update an active session, and visitors do not see it as their message.
sourceType, analyticsId, and interaction attribute the activation. The default source for direct API calls is public_api. An open with interaction: "auto" does not replace an invitation the visitor already opened.
visitorIdentity supplies a stable external ID and optional name to only the session created by that request.

05

Hide the floating launcher

A page that opens Stand only from its own controls can hide the default floating launcher. Add data-stand-hide-button="true" to the embed script tag, set hideButton: true in window.StandChatConfig before the script loads, or call initiallyHideChatButton(). All three apply the same hidden state. The attribute and configuration take effect as soon as the script runs, so they do not depend on when page code executes.

While the launcher is hidden, the matched behavior rule does not reveal it, whatever its trigger, including On load. openChat(...), whether called by page code or by a stand-button or stand-card, reveals and opens the widget, and the launcher then remains for that page view. An active conversation restored after a reload or same-site navigation appears as usual.

Hide the launcher in the snippet

<script defer src="https://cdn.stand.chat/widget/stand.js" data-stand-id="YOUR-SITE-ID" data-stand-hide-button="true"></script>

Pair the hidden launcher with a page control that calls StandChat.openChat after whenAvailable reports a responder, as in the example above.

06

Lifecycle and cleanup

The embed script may be deferred or loaded after application code. Do not assume the global exists at the first page script execution.
Availability is positive-only: custom controls are revealed when a responder is found. A false check does not distinguish “still loading” from “unavailable.”
whenAvailable(...) immediately supplies a copied current availability object when Stand is already ready.
Save and call the unsubscribe function when a React, Vue, or other single-page component unmounts.
Prefer stand-button or stand-card when their declarative behavior is sufficient; they handle readiness and availability automatically.

07

Boundaries and failure behavior

Calling openChat(...) cannot bypass routing or create a conversation when the site has no eligible responder.
Getter values can be empty until availability is known.
The API does not return contact details, conversation history, messages, authentication state, or private Stand credentials.
Page-supplied identity and prompt values are application-provided context, not proof of identity or permission.
Site behavior rules are declarative and do not execute arbitrary JavaScript; this API is the supported integration contract for reviewed website code.

08

Related features

Custom chat UI — Custom chat UIs let a website render its own visitor conversation interface, including interfaces built with an AI coding agent, while Stand provides routing, AI replies, human chat, and conversation history through the visitor HTTP and WebSocket APIs. Stand’s live examples include an inline React client, the homepage hero’s chat, and the homepage’s pink cow chat.
Stand button — The stand-button web component adds a compact, page-native chat invitation that can appear for a selected live rep, AI Stand-in, or either responder and can reveal one dedicated surrounding container.
Stand card — The stand-card web component turns authored page content into a contextual chat invitation with explicit activation, responder display filtering, dedicated surrounding-content reveal, optional visitor input, identity, themes, and spotlight behavior.
Page-known visitor identification — Visitor identification lets a signed-in website attach its own stable customer ID and optional name to a new Stand conversation. Reps can recognize and search for the visitor by name without exposing the website’s ID in the chat.
Widget installation — Widget installation places a Site-specific deferred script on the published website. The snippet loads Stand, identifies the Site through `data-stand-id`, and lets the backend confirm that the expected domain has requested availability.