Tune Stand Chat Behavior With Triggers and JS API

Stand Guidebook

Chapter 10 of 12

Field guide

What to learn in this chapter

Match Stand to each page with declarative runtime rules, page-native prompts, and supported API calls from website-owned code.

Need an exact capability definition, plan requirement, or limitation? Browse the Feature Reference.

Runtime rules

Edit behavior without redeploying the snippet.

App link

Open Chat widget behavior from Sites.

In Stand, open Sites, choose a site, then use Chat widget behavior to edit the ordered runtime rules. Changes apply to the next visitor load without changing the snippet.

Open Sites

Chat widget behavior is site configuration that the installed script fetches when the page loads. The organization owner can change the invitation without redeploying the snippet; other members can ask the owner to make the change. The script checks for an available responder and applies the first enabled behavior rule that matches the page path.

Each site has an ordered list of behavior rules. Put specific rules above broad rules. The empty path rule is the default fallback. The / rule is only the front page. Other paths match exactly, ignoring a trailing slash; add /* to match that page and every child path.

Practice

Try this next

01As the organization owner, open Sites → Chat widget behavior for the installed site and add an enabled rule for /pricing above the fallback rule.
02Choose Time and a short delay, then choose Custom greeting and write one pricing-specific invitation.
03Save, reload the published /pricing page, and confirm that a responder is available and the invitation appears after the delay.
04Test another page to confirm the fallback still applies. To repeat the greeting test, use a fresh browser context: greeting memory suppresses repeat invitations in the same browser.
05Change one setting at a time and compare the resulting conversations before using desktop auto-open more widely.

Field

How it works

Notes

FieldRule order

How it worksRules are evaluated top to bottom. The first enabled rule whose path matches is the only rule used.

NotesPut exact page rules above broader /* subtree rules. Use the empty path only for the fallback behavior.

FieldEnabled

How it worksDisabled rules are skipped without being deleted.

NotesUse this to pause an experiment while keeping its settings.

FieldPath pattern

How it worksMatched against window.location.pathname only. Query strings and hashes are ignored.

NotesEmpty path means default fallback. / means the front page only. /pricing and /pricing/ match only that page. /pricing/* also matches /pricing, /pricing/, and child pages such as /pricing/enterprise.

FieldWidget show trigger

How it worksControls when the floating widget is shown or opened after find reports availability.

NotesOn load runs immediately. Time waits for Delay. Scroll waits for Scroll %. None means no automatic floating widget reveal.

FieldDelay

How it worksUsed only by the Time trigger.

NotesSet the number of seconds to wait before the trigger fires.

FieldScroll %

How it worksUsed only by the Scroll trigger.

NotesSet how far down the page the visitor must scroll before the trigger fires.

FieldGreeting

How it worksControls the first visible chat invitation.

NotesDefault greeting keeps the selected rep or Stand-in’s configured greeting. No greeting suppresses it. Custom greeting uses Custom greeting text. To avoid repeated interruptions, the invitation appears once per visitor browser on that website, not on every reload; clearing site data or using another browser or device starts fresh.

FieldCustom greeting text

How it worksReplacement first message from the rep or Stand-in.

NotesWrite it from the rep or Stand-in point of view and tie it to the page context.

FieldHalf-sized

How it worksStarts the floating widget in a smaller presentation.

NotesUseful when the page needs quieter coverage.

FieldStep aside

How it worksLets the floating widget move aside after it has appeared.

NotesUseful when the widget should stay available without sitting over page content.

FieldOpen chat widget on desktop

How it worksOpens the full chat window when the selected default or custom greeting would appear.

NotesUses the same once-per-browser memory as the greeting. Mobile layouts show only the greeting bubble because an open chat takes over the screen.

FieldStand admin access

How it worksLets Stand administrators edit the site’s declarative behavior rules when the organization owner allows it.

NotesTurn the permission off and save to revoke the admin edit path. It never enables stored source-code execution.

Declarative prompts

Add page prompts before writing JavaScript.

These examples are for website editors who can add HTML and CSS. First install the Stand snippet from your site's Installation snippet in Sites and confirm that a human rep or enabled Stand-in is available on that page. Keep that snippet on the page; it loads these custom HTML elements and connects them to Stand.

Start with the button below. Paste its HTML where you want the invitation, reload the page, and select it after it appears. It opens the supplied chat window. Use the card when you also need supporting copy or a visitor message field; use the JavaScript API later in this chapter for controls you already own.

stand-button

Use a button for compact page prompts.

Preview

New-conversation greeting: I can help you install Stand. What would you like to know?

HTML

<stand-button hidden avatar message="I can help you install Stand. What would you like to know?">How does it work?</stand-button>

<style>
  stand-button::part(button) { cursor: pointer; }
  stand-button:hover::part(button) { background: #F4F4F4; }
</style>

A stand-button is the smallest in-page chat prompt. Use it when the page already has enough context and all you need is a compact invitation that opens Stand with a page-specific greeting from the rep or AI Stand-in.

Put it anywhere on the page and include native hidden to avoid a flash before the custom element upgrades. The message attribute supplies the greeting for a new conversation. If a chat is already in progress, the button reopens it without replacing its messages.

Use show-when="rep" for a selected live human, show-when="standin" for a selected AI Stand-in, or omit it for the default either behavior. Empty and unsupported values stay hidden. This filters the single responder returned by find or session restoration; it does not request a responder type, change routing, or guarantee who remains assigned.

To reveal surrounding content too, move hidden from the button to its closest dedicated ancestor and mark that ancestor data-stand-reveal. Use exactly one hidden location. A self-hidden component takes precedence, and Stand never climbs to an arbitrary hidden tab, modal, accordion, or responsive container.

HTML

<section hidden data-stand-reveal>
  <h2>A product specialist is online</h2>
  <stand-button show-when="rep" message="What would you like to ask our team?">
    Chat with a person
  </stand-button>
</section>

<section hidden data-stand-reveal>
  <h2>Get help from an AI Stand-in</h2>
  <stand-card show-when="standin" greeting="What would you like help with?" data-stand-action>
    Ask our AI Stand-in
  </stand-card>
</section>

Multiple buttons and cards evaluate the selected responder independently. If prompts share a marked wrapper, any matching child reveals it, while each mismatched component remains internally hidden. Use separate wrappers when the surrounding heading or copy is specific to a rep or Stand-in. External reveal is one-way, so keep the marker on a wrapper owned by this prompt instead of framework-managed application state.

stand-button attributes

hidden: Recommended in the original HTML on either the button or its dedicated data-stand-reveal wrapper so content cannot flash before the custom element upgrades.
show-when: Optional responder display filter: either (the default), rep, or standin. Empty or unsupported values fail closed. The filter does not change routing.
avatar: Optional. Shows the Available rep or eligible Stand-in avatar as the button icon. Omit it for a text-only button.
message: Opening greeting from the rep or Stand-in for a new conversation. This is not a message sent by the visitor and does not replace an existing transcript.
prompt: Optional internal context attached when a new session starts. Visitors do not see it; reps can see it in history and AI Stand-ins use it as guidance. It does not update a session already in progress.
analytics-id: Optional attribution label included with the activation event so teams can compare buttons or placements.
class: Optional standard HTML class. Use it with ::part(button), ::part(icon), and ::part(label) to style the button.

stand-button slots and parts

default slot: The visible button label. Keep it short and action-oriented.
::part(button): Styles the native button wrapper.
::part(icon): Styles the optional avatar icon shown when the avatar attribute is present.
::part(label): Styles the slotted button label.

stand-card

Use a card when the prompt needs context.

Adjust the preview, then copy the generated HTML. Replace sample copy and image URLs with your own; the example image path belongs to this documentation site. The greeting is spoken by the responder. Text entered in the message field is spoken by the visitor and is sent when they choose Start chat.

HTML

<stand-card hidden identity="avatar name" greeting="What would you like to know about this page?">
  <strong>Ask a question about this page</strong>
  <textarea data-stand-visitor-message aria-label="Your message" rows="3"></textarea>
  <button slot="actions" type="button" data-stand-action>Start chat</button>
</stand-card>

The text field and action button are direct children. Start with this structure, then add the optional layout and styling below.

The configurable preview below uses the live Stand widget. Selecting its action with a message sends that text to Stand; if you already have a conversation, it continues there. The preview's identity comes from the responder selected for this website.

Preview

Plan the right call Share your goal before choosing a time.

Useful when visitors are comparing meeting options.

HTML

<stand-card hidden theme="outlined horizontal cover-media" identity="avatar name title" greeting="I can help you decide whether a call is worth booking. What are you trying to figure out?">
  <img slot="media" src="/images/guide/stand-card-implementation.png" alt="">
  Plan the right call
  Share your goal before choosing a time.
  <textarea data-stand-visitor-message aria-label="Your message" rows="3" placeholder="What would you like help deciding?"></textarea>
  <span slot="footer">Useful when visitors are comparing meeting options.</span>
  <button slot="footer" type="button" data-stand-action style="margin-left: auto">Start chat</button>
</stand-card>

Publish this markup on the page that loads your Stand installation snippet. Replace sample content and media paths with your own.

Use stand-card when the invitation should carry supporting copy, identity, media, or a layout that feels like part of the page.

The default, unnamed slot holds body content. Named slots place your HTML in the media, actions, or footer region. Visual variants go in the space-separated theme attribute, and ::part() selectors style the component's internal surfaces. Slots control layout only; putting a button in an actions slot does not make it open chat. Stand generates only the availability fields named by identity. Omitting it hides the generated identity header; when identity is shown for an AI Stand-in, that header includes the AI badge.

The card fills the width of its containing block by default. To constrain or align it, put ordinary layout CSS directly in its style attribute—for example, style="max-width: 42rem; margin-inline: auto". These styles apply to the custom-element host, so they do not need to cross the shadow boundary.

Behavior is explicit. Mark one direct child with data-stand-action, or put that marker on stand-card to activate the whole surface. A child action and the message source must be direct children of the card, not nested inside another element. Mark the visitor-message source with data-stand-visitor-message. Use type="button" so a native button cannot submit an ancestor form before Stand upgrades the element or when its script is unavailable.

Cards use the same show-when and data-stand-reveal contract as buttons. The generated code can keep hidden on the card or move it to one dedicated wrapper. Stand removes exactly that one attribute after a matching result; it does not change aria-hidden, inert, dialog state, or framework state, and it does not re-hide an external wrapper later.

Add spotlight when a high-intent card should center on the visible viewport as the page continues scrolling behind a blurred glass layer. Stand leaves a visual imprint in the page so the layout remains complete. Spotlight includes a secondary Cancel action by default; use dismiss-label to change it, or author one direct data-stand-dismiss control.

To identify a signed-in visitor, set visitor-id and optionally visitor-name, or call StandChat.identify({ externalId, name }). Clear a global identity with StandChat.identify(null). These values are captured when a new conversation starts; changing them does not relabel a conversation already in progress. The page-asserted ID stays private and is never authorization. The optional name is visible to authenticated reps in dashboard and history, but not in the visitor chat.

Check the prompt on your own page

If it stays hidden, check the installed snippet, page coverage, and responder availability, then check the browser console for an invalid filter or conflicting action markers.
Use one action: either the card itself or one direct child. With no action marker, the card displays content but does not open chat.
Give each message field an accessible name. The generated field uses aria-label="Your message"; replace it with a visible label associated with a unique field ID when your layout allows.
Test with an empty field, a visitor message, and an existing conversation. Confirm that the greeting is not posted as visitor speech and that visitor text arrives once.
If spotlight stays inline, make sure the whole card fits in the visible viewport as you scroll it across the midpoint. A card taller or wider than that viewport cannot enter spotlight. A previous dismissal or activation is remembered for that card in the same browser.
Check keyboard access, narrow screens, image alternatives, and spotlight dismissal before publishing.

stand-card attributes

hidden: Recommended in the original HTML on either the card or its dedicated data-stand-reveal wrapper so content cannot flash before the custom element upgrades.
show-when: Optional responder display filter: either (the default), rep, or standin. Empty or unsupported values fail closed. The filter does not change routing.
greeting: Opening greeting from the rep or Stand-in for a new conversation. An explicit action opens chat; the greeting does not replace an existing transcript.
prompt: Optional internal context attached when a new session starts. Visitors do not see it; reps can see it in history and AI Stand-ins use it as guidance. It does not update a session already in progress.
analytics-id: Optional attribution label included with the activation event so teams can compare cards or placements. Labels may be reused; spotlight dismissal is still remembered per card and page.
spotlight: Optional. When the fully visible card crosses the viewport midpoint in either scroll direction, it centers above a blurred glass layer while the page keeps its native momentum. After placement it stays fixed, moving only enough to remain visible when an on-screen keyboard or browser controls reduce the viewport. Its actions stay fixed through each pointer gesture. A visual imprint preserves the underlying layout. Dismissal or activation suppresses the spotlight for that card in the visitor browser on that website origin. It can appear again after site data is cleared or in another browser or device.
dismiss-label: Optional label for the generated spotlight dismissal action. Missing or empty values use Cancel. The attribute has no effect without spotlight.
identity: Optional space-separated generated identity fields: avatar, name, and title. Omit it to hide the generated identity header, including the AI badge. When identity is shown for an AI Stand-in, the header also includes the AI badge.
data-stand-action: Makes the card focusable and opens chat on click, Enter, or Space. Nested links and form controls keep their own behavior. Do not also mark a child action; conflicting markers disable activation.
visitor-id / visitor-name: Optional page-known visitor identity captured when a new session starts. visitor-id is required when visitor-name is present. The ID is private correlation metadata; authenticated reps can see the name in dashboard and history. These attributes do not authenticate the visitor or update an existing session.
theme: Optional space-separated style variants. Supported values are outlined, elevated, horizontal, cover-media, stretch-media, and divided-footer.
class: Optional standard HTML class. Use it with ::part() selectors and your own slotted content selectors to customize styling.
style: Optional standard HTML style attribute on the card host. The card fills its containing block by default; use max-width and margins here to constrain and align it without crossing the shadow boundary.

stand-card slots

default slot: Main body content. Content never becomes behavior merely because of its element type.
slot="media": Image, video, icon, or illustration content. It appears above the card body, or beside it when the horizontal theme is used.
slot="actions": A dedicated row for primary and dismissal controls. Use the footer slot instead when an action should share a row with footer copy. Behavior still requires data-stand-action or data-stand-dismiss.
slot="footer": Supplementary notes, badges, secondary copy, and actions that should share the same row. It has no divider unless theme includes divided-footer, and never implies behavior.

stand-card direct-child behavior markers

data-stand-action: Marks one direct child as the sole chat action. Do not combine it with data-stand-dismiss on the same child. A button should also use type="button" so it cannot submit an ancestor form before Stand upgrades the element or when the script is unavailable.
data-stand-visitor-message: Marks one direct child as the visitor-message source. Stand reads value when present, otherwise editable or text content. Nonempty text is sent when the action runs, to a new or existing chat. An empty source only opens chat.
data-stand-dismiss: Marks one direct child as the authored spotlight dismissal action. Do not combine it with data-stand-action on the same child. Use it instead of the generated fallback when you need custom markup. A native button should also use type="button" to avoid submitting an ancestor form.

stand-card theme variants

outlined: Removes the default shadow so the card reads as a bordered panel. If elevated is also selected, its stronger shadow takes precedence.
elevated: Adds a stronger shadow for shaded sections or high-emphasis prompts.
horizontal: Places card content beside the media slot on wider screens.
cover-media: Sizes image or video media to cover the card media area.
stretch-media: Stretches image or video media to fill the available media height.
divided-footer: Adds a divider above supplementary footer content. Actions remain in their own undivided region.

stand-card shadow parts

::part(card): Styles the outer card surface.
::part(media): Styles the media slot wrapper.
::part(header): Styles the generated availability identity header.
::part(header-prefix): Styles the generated avatar or mascot.
::part(title): Styles the generated rep or Stand-in name.
::part(subtitle): Styles the generated title or role.
::part(header-suffix): Styles the generated AI badge.
::part(content): Styles the default slot wrapper.
::part(actions): Styles the actions slot wrapper.
::part(footer): Styles the footer slot wrapper.
::part(dismiss): Styles the generated spotlight dismissal action.
::part(imprint): Styles the noninteractive card-shaped imprint that preserves the underlying page layout while spotlight is active.
::part(spotlight): Styles the top-layer dialog that holds the active spotlight card.

Styled examples

Four common prompts, each tuned to the page.

These styled previews use sample people and AI identities to illustrate the design. Their generated HTML shows the actual selected responder on your website; it does not select Alex, Riley, or a responder type. Add a show-when filter when the surrounding invitation is specific to a human or AI.

Example 1

Pricing Page

Plans and limits→ Pricing detailsCompare plans, limits, and what changes by team size.

New-conversation greeting: I can help with pricing. What would you like to compare?

HTML

<stand-card hidden class="stand-card--pricing" theme="elevated" data-stand-action greeting="I can help with pricing. What would you like to compare?">
  <span class="stand-card-eyebrow">Plans and limits</span>
  <strong>→ Pricing details</strong>
  <span>Compare plans, limits, and what changes by team size.</span>
</stand-card>

CSS

.stand-card--pricing::part(card) {
  border-color: #F6C510;
  border-left: 4px solid #F6C510;
  background: #fffdf4;
  cursor: pointer;
}

.stand-card--pricing:hover::part(card) {
  background: #fff8d8;
}

.stand-card--pricing .stand-card-eyebrow {
  display: block;
  margin-bottom: 0.25rem;
  color: #C19802;
  font-size: 0.75rem;
  font-weight: 700;
  text-transform: uppercase;
}

Example 2

Booking

Alex Morgan

Product specialist

Before you bookPlan the right callShare your goal before choosing a time.

New-conversation greeting: I can help you decide whether a call is worth booking. What are you trying to figure out?

HTML

<stand-card hidden class="stand-card--booking" theme="outlined elevated horizontal cover-media" identity="avatar name title" data-stand-action greeting="I can help you decide whether a call is worth booking. What are you trying to figure out?">
  <img slot="media" src="/images/guide/stand-card-implementation.png" alt="">
  <span class="stand-card-eyebrow">Before you book</span>
  <strong>Plan the right call</strong>
  <span>Share your goal before choosing a time.</span>
  <span slot="footer">Useful when visitors are comparing meeting options.</span>
</stand-card>

CSS

.stand-card--booking {
  max-width: 42rem;
}

.stand-card--booking::part(card) {
  border-color: #38B9E0;
  background: #f7fcfd;
  cursor: pointer;
}

.stand-card--booking:hover::part(card) {
  background: #eef9fc;
}

.stand-card--booking::part(media) {
  min-height: 12rem;
}

.stand-card--booking .stand-card-eyebrow {
  color: #1B90B3;
  font-weight: 700;
}

Example 3

Service Fit

Riley

Not sure yet?Which option fits?Describe your goal and compare the likely paths.

New-conversation greeting: I can help you narrow this down. What are you trying to accomplish?

HTML

<stand-card hidden class="stand-card--service-fit" theme="outlined" identity="avatar name" data-stand-action greeting="I can help you narrow this down. What are you trying to accomplish?">
  <span class="stand-card-eyebrow">Not sure yet?</span>
  <strong>Which option fits?</strong>
  <span>Describe your goal and compare the likely paths.</span>
</stand-card>

CSS

.stand-card--service-fit::part(card) {
  border-color: #38B9E0;
  background: #f3fbfd;
  cursor: pointer;
}

.stand-card--service-fit:hover::part(card) {
  background: #e3f7fc;
}

.stand-card--service-fit::part(header-prefix) {
  background: #1B90B3;
}

.stand-card--service-fit .stand-card-eyebrow {
  color: #05485D;
  font-weight: 700;
}

Example 4

Contact

Alex Morgan

Product specialist

Have a question?Ask before you submitGet an answer before sending the contact form.

New-conversation greeting: I can answer a quick question before you contact the team. What would you like to know?

HTML

<stand-card hidden class="stand-card--contact" theme="outlined" identity="avatar name title" data-stand-action greeting="I can answer a quick question before you contact the team. What would you like to know?">
  <span class="stand-card-eyebrow">Have a question?</span>
  <strong>Ask before you submit</strong>
  <span>Get an answer before sending the contact form.</span>
  <span slot="footer">Good for visitors who are close to reaching out.</span>
</stand-card>

CSS

.stand-card--contact::part(card) {
  border-style: dashed;
  border-color: #A3A3A3;
  background: white;
  cursor: pointer;
}

.stand-card--contact:hover::part(card) {
  background: #F4F4F4;
}

.stand-card--contact::part(footer) {
  color: #676767;
  font-style: italic;
}

.stand-card--contact .stand-card-eyebrow {
  color: #B3371B;
  font-weight: 700;
}

Pricing, booking, service fit, and contact pages usually need different invitations. Use a class on stand-card, style the shadow-DOM parts with ::part(), and style your own slotted content with normal CSS. Select any preview card to open the live widget when a responder is available. Its greeting applies to a new conversation; an existing chat reopens with its transcript intact.

Developer API

Use the JavaScript API when you need custom page UI.

Live examples

Try both API patterns on this page.

Waiting for Stand

Page button

Opens chat with a replacement first message from the rep or Stand-in.

Submit a feature request

Use stand-button or stand-card first when a declarative prompt is enough. Use the JavaScript API when the site already has its own button, comparison table, booking flow, or component that should open Stand.

Declarative prompts can use show-when="rep", show-when="standin", or the default either behavior. This filters the responder already selected by find or session restoration; it does not change routing or guarantee a responder type. Put native hidden on the component, or on one dedicated ancestor marked data-stand-reveal when its surrounding copy should appear at the same time.

The JavaScript API is the window.StandChat object created by the Stand script. Because the script can load asynchronously, read it defensively and wire custom UI only after the object exists.

The object can exist before the availability lookup has finished. isAvailable() tells you whether Stand found a responder. whenAvailable(callback) is the usual place to reveal custom UI, and the callback receives a copied availability object: { available, human, name, title, avatarUrl, brandName }.

openChat(...) reveals and opens the widget. For a new session, the first argument supplies the rep or Stand-in greeting and the optional prompt supplies internal AI context. An optional visitor message is sent to the conversation, including an existing session if one is already open. Greeting and context arguments do not rewrite an existing session.

identify(...) sets the stable visitor ID and optional display name for future sessions. Call it before starting a new session; it does not relabel an existing conversation. A name without an externalId is ignored. The ID stays private and the page-asserted data is never authentication; authenticated reps can see the name in dashboard and history.

The API exposes copied availability data only. It does not expose visitor tokens, websocket tokens, session tokens, or internal widget state.

Code

<button type="button" data-ask-pricing hidden>Ask about pricing</button>
<script>
function setupPricingButton(tries = 0) {
  const StandChat = window.StandChat
  const button = document.querySelector("[data-ask-pricing]")

  if (!StandChat || !button) {
    if (tries < 200) {
      window.setTimeout(() => setupPricingButton(tries + 1), 50)
    }
    return
  }

  StandChat.whenAvailable(() => {
    button.hidden = false
  })

  button.addEventListener("click", () => {
    StandChat.openChat("I can help with pricing. What would you like to compare?")
  })
}

setupPricingButton()
</script>

This waits for the deferred Stand script and still works if Stand has already found someone available.

Code

<stand-button
  hidden
  avatar
  message="Happy to walk you through installation. How do you host your website today?"
  prompt="Answer installation questions directly. Ask for the website platform only when it changes the steps needed.">
  Ask how Stand works
</stand-button>

<stand-card
  hidden
  greeting="I can help with pricing. What would you like to compare?"
  prompt="Answer factual plan questions directly. For a recommendation, ask only for missing details that change the choice, such as expected chat volume.">
  <strong>Compare pricing</strong>
  <span>Ask which plan fits your site.</span>
  <textarea data-stand-visitor-message rows="3" aria-label="Your pricing question" placeholder="What matters most to your team?"></textarea>
  <button slot="actions" type="button" data-stand-action>Start chat</button>
</stand-card>

Omitting show-when allows either responder. The marked button opens chat and sends the textarea text to the new or current conversation; without data-stand-action the card is inert. Greeting and prompt apply only to a new session. The prompt is not shown as visitor text, but its HTML attribute is inspectable and AI replies can use its contents. Add spotlight for a generated Cancel action, or dismiss-label to rename it.

Code

<section hidden data-stand-reveal>
  <h2>A product specialist is online</h2>
  <stand-button
    show-when="rep"
    message="What would you like to ask our team?">
    Chat with a person
  </stand-button>
</section>

<section hidden data-stand-reveal>
  <h2>Get an immediate AI answer</h2>
  <stand-card
    show-when="standin"
    greeting="What would you like help with?"
    data-stand-action>
    Ask our AI Stand-in
  </stand-card>
</section>

Each wrapper owns the one native hidden attribute, so its responder-specific heading and prompt reveal together. Stand never opens an unmarked hidden ancestor. Multiple components may share a wrapper when its surrounding content is valid for every matching child; any match reveals the wrapper, while mismatched components remain internally hidden.

Code

<label for="feature-request">Describe your feature request</label>
<textarea id="feature-request"></textarea>
<button id="feature-request-submit" type="button" disabled>
  Submit a feature request
</button>

<script>
  function setupFeatureRequestBox(tries = 0) {
    const StandChat = window.StandChat
    const textarea = document.getElementById("feature-request")
    const button = document.getElementById("feature-request-submit")
    const prompt = "Record the submitted feature request in this conversation. Ask a clarifying question only if needed to understand it. Ask explicit permission before a separate research interview. Do not promise review, delivery, or contact from a person; use the enabled follow-up skill only when the visitor requests or agrees to it."

    if (!StandChat || !textarea || !button) {
      if (tries < 200) {
        window.setTimeout(() => setupFeatureRequestBox(tries + 1), 50)
      }
      return
    }

    let standAvailable = StandChat.isAvailable()
    const updateButton = () => {
      button.disabled = !standAvailable || !textarea.value.trim()
    }

    StandChat.whenAvailable(() => {
      standAvailable = true
      updateButton()
    })

    textarea.addEventListener("input", updateButton)
    button.addEventListener("click", () => {
      const visitorMessage = textarea.value.trim()
      if (!standAvailable || !visitorMessage) return
      StandChat.openChat("What feature would you like to have?", visitorMessage, prompt)
    })

    updateButton()
  }

  setupFeatureRequestBox()
</script>

The button remains disabled until Stand is available and the textarea has content.

API

Meaning

Parameters

Return and notes

APIwindow.StandChat

MeaningGlobal public API object added by stand.js. It is the entry point for all methods below, not the <stand-chat> custom element.

ParametersNo parameters. Read it from window after the script has executed, for example const StandChat = window.StandChat.

Return and notesObject or undefined. It may exist before a responder has been found. Guard async pages and use whenAvailable before showing custom UI.

APIStandChat.initiallyHideChatButton()

MeaningSuppresses the default floating chat button so page code or declarative prompts control when chat appears.

ParametersNo parameters.

Return and notesReturns undefined. Calling openChat later clears this hidden state and opens the widget immediately.

APIStandChat.openChat(repMessage = "")

MeaningReveals the widget and opens chat. A non-empty repMessage supplies the greeting for a new session; it does not replace an existing transcript.

ParametersrepMessage: string. Use an empty string to keep the configured greeting.

Return and notesReturns undefined. If the widget is still loading, the open request is queued until availability and UI are ready. If no responder is available, nothing visible opens.

APIStandChat.openChat(repMessage, visitorMessage)

MeaningOpens chat and sends visitorMessage. It starts a new conversation or adds a message to the current one.

ParametersrepMessage: string. visitorMessage: string. Empty or whitespace-only visitorMessage is ignored.

Return and notesUse when the page already collected text, such as a form field or textarea.

APIStandChat.openChat(repMessage, visitorMessage, prompt)

MeaningOpens chat and sends the visitor message. The prompt attaches internal context when a new session starts.

Parametersprompt: string. It is retained as context in dashboard History, not rendered as a visitor message. HTML attributes are inspectable, and AI replies can quote or paraphrase it; do not include secrets.

Return and notesUse for page facts and relevant help, such as "The visitor is comparing plans; ask only for missing details needed for a recommendation."

APIStandChat.openChat(repMessage, options)

MeaningAdvanced form for custom components that need attribution. It behaves like openChat with string arguments, using fields on options.

Parametersoptions.visitorMessage?: string; options.prompt?: string; options.visitorIdentity?: { externalId: string, name?: string }; options.sourceType?: string; options.analyticsId?: string; options.interaction?: string.

Return and notessourceType defaults to public_api. analyticsId and interaction are used for activation attribution; visitorIdentity is stored privately. A name without externalId is ignored.

APIStandChat.identify(identity)

MeaningSets the page-known identity used by future sessions without displaying it in visitor chat.

Parametersidentity: { externalId: string, name?: string } or null to clear it.

Return and notesReturns undefined. The external ID stays private; authenticated reps can see the optional name. Treat all page-asserted identity as unverified metadata, never authorization.

APIStandChat.isAvailable()

MeaningChecks whether the availability lookup found a live rep or AI Stand-in for this page.

ParametersNo parameters.

Return and notesReturns boolean. false means unavailable or the lookup has not finished.

APIStandChat.whenAvailable(callback)

MeaningRegisters a callback to run when Stand has a responder. If Stand is already available, the callback runs immediately with the current availability copy.

Parameterscallback: function receiving { available, human, name, title, avatarUrl, brandName }.

Return and notesReturns an unsubscribe function. Call it during component cleanup in React, Vue, or other SPA code.

APIStandChat.isHuman()

MeaningTells custom UI whether the available responder is a live human rep.

ParametersNo parameters.

Return and notesReturns boolean. false can mean AI Stand-in or not available yet.

APIStandChat.getName()

MeaningReads the available responder display name for custom UI.

ParametersNo parameters.

Return and notesReturns string or empty string.

APIStandChat.getTitle()

MeaningReads the available responder title or role for custom UI.

ParametersNo parameters.

Return and notesReturns string or empty string.

APIStandChat.getAvatar()

MeaningReads the available responder avatar URL for custom UI.

ParametersNo parameters.

Return and notesReturns string URL or empty string.

Executable-code boundary

Keep executable code in the website implementation.

Stand behavior rules are declarative. They can match paths and control reveal timing, greetings, opening, half-size, and step-aside presentation, but they do not run stored JavaScript in the customer page.

When the built-in controls are not enough, implement reviewed code in the website and connect it through stand-button, stand-card, or the public StandChat API. Legacy custom-JavaScript values are ignored, and new non-blank values are rejected.

Questions

Common reader notes

Can a behavior rule run custom JavaScript?

No. Behavior rules are declarative. Put reviewed code in the website and use Stand's Web Components or public JavaScript API for supported integrations.

Does changing behavior require a new snippet?

No. Runtime behavior is returned by Stand after the snippet calls find.

Can a page show different prompts for a person and an AI Stand-in?

Yes. Set show-when to rep or standin on each stand-button or stand-card. The default either value preserves the existing behavior. This filters the selected responder; it does not change routing.

Can Stand reveal content around a button or card?

Yes. Put native hidden and data-stand-reveal on one dedicated closest ancestor instead of the component. Stand removes exactly one hidden attribute after a matching result and never traverses arbitrary hidden ancestors.

Continue the guide

Choose your next chapter.

Previous chapter 09

Make It Feel Like You

Use real identity, avatars, pins, and brand presence.

Next chapter 11

Connect Backend Systems

Give selected Stand-ins controlled access to live APIs.

Try the guide on one real page.

Create your account

Tune when Stand appears and what it asks.

What to learn in this chapter

Edit behavior without redeploying the snippet.

Open Chat widget behavior from Sites.

Try this next

Add page prompts before writing JavaScript.

Use a button for compact page prompts.

Use a card when the prompt needs context.

Configure the card+Expand card configurator

Check the prompt on your own page

Four common prompts, each tuned to the page.

Pricing Page

Booking

Service Fit

Contact

Use the JavaScript API when you need custom page UI.

Try both API patterns on this page.

Keep executable code in the website implementation.

Common reader notes

Can a behavior rule run custom JavaScript?

Does changing behavior require a new snippet?

Can a page show different prompts for a person and an AI Stand-in?

Can Stand reveal content around a button or card?

Choose your next chapter.

Try the guide on one real page.