Trigger the chat from your own UI

Dispatch a humind-open-chat custom event on window to open the chat overlay from any element on your page: a "Need help?" button in the checkout, a CTA inside a product card, a help-center tile, anywhere a visitor might want to start a conversation without going through the floating entry point.

This page applies to every integration path:

• Shopify merchants using the Humind app — the chat is auto-injected by the theme extension, so the humind-open-chat listener is already on window site-wide. Just dispatch the event.
• Non-Shopify merchants who embedded <humind-widget> manually — same event, same listener.
• Hybrid Shopify setups (Shopify backend, custom storefront) where <humind-widget> is embedded by hand — same contract.

When to use this

The default floating entry point (bottom-right button + proactive messages) is what ships with <humind-widget> out of the box, and it's good enough for most storefronts. Reach for humind-open-chat when you want to:

• Wire your own CTA somewhere on the page (a "Talk to an expert" button, a size-help link, a shipping-question tile).
• Open the chat pre-filled with a specific question.
• Open the chat with a specific product in context so the AI can ground its answers on that product.
• Route visitors who clicked something intent-loaded (e.g., a "Gift for dad" tile) into a targeted conversation.

Prerequisites

<humind-widget> must already be mounted on the page. If the overlay isn't in the DOM, the event fires and goes nowhere (no listener is registered). See Install the chat.

Event contract

window.dispatchEvent(new CustomEvent('humind-open-chat', {
  detail: {
    message: 'I need help choosing a size.'
  }
}))

detail fields

Field	Type	Purpose
message	string	Optional. The message to send as if the visitor had typed it. The chat opens and immediately starts a reply. Omit to just open the overlay idle.
productId	string	Optional. A Shopify GID (gid://shopify/Product/12345) or your internal Humind product ID. Loads a product context bar at the top of the chat and lets the AI ground answers on that specific product.

Examples

Open with a pre-filled message

<button id="size-help">Need help with sizing?</button>

<script>
  document.getElementById('size-help').addEventListener('click', () => {
    window.dispatchEvent(new CustomEvent('humind-open-chat', {
      detail: { message: 'Can you help me pick a size?' }
    }))
  })
</script>

Open with a product context

On a product card or list, pass the product ID so the conversation is grounded on that product.

<article data-product-id="gid://shopify/Product/12345">
  <button class="ask-about-this">Ask about this product</button>
</article>

<script>
  document.querySelectorAll('.ask-about-this').forEach(btn => {
    btn.addEventListener('click', e => {
      const card = e.target.closest('[data-product-id]')
      window.dispatchEvent(new CustomEvent('humind-open-chat', {
        detail: {
          message: 'Tell me more about this product.',
          productId: card.dataset.productId
        }
      }))
    })
  })
</script>

Open idle (no pre-filled message)

window.dispatchEvent(new CustomEvent('humind-open-chat'))

Close the chat

Dispatch a humind-close-chat event to programmatically close the overlay. Useful if you've wired your own "close" button somewhere on the page, or if you want the chat to dismiss itself after a visitor completes an action elsewhere on the site.

window.dispatchEvent(new CustomEvent('humind-close-chat'))

No detail payload is read — the event is a fire-and-forget signal. If the overlay is already closed, the event is a no-op.

Gotchas

• Use window.dispatchEvent, not document.dispatchEvent. The listener is registered on window. Dispatching on document does nothing. See Troubleshooting → humind-open-chat fires but the overlay ignores it.
• Don't duplicate <humind-widget> on the page. Only one overlay should exist. The other widgets (<humind-gift-finder>, <humind-product-questions>, <humind-quiz>) already dispatch humind-open-chat when a visitor interacts with them, and they expect a single <humind-widget> instance to catch it.
• The chat service must be reachable. If the backend or embed.thehumind.com CDN is down, the overlay shows a fallback "unavailable" state. Your CTA still fires cleanly; nothing breaks on your side.

Tracking chat opens in your analytics

window is the source of truth for chat-open events. If you want to forward them to GA4, Segment, Mixpanel, or any other analytics pipeline, add your own listener:

window.addEventListener('humind-open-chat', e => {
  analytics.track('chat_opened', {
    productId: e.detail?.productId,
    hasPrefilledMessage: Boolean(e.detail?.message)
  })
})

This catches both your own CTAs and the floating entry point — every path that opens the chat goes through this event.

Other events the chat listens to

The overlay also listens for two events emitted by other Humind widgets. You don't need to dispatch these yourself — they're documented here in case you see them in devtools or want to listen for them in your own analytics.

• humind-quiz-completed — dispatched by <humind-quiz> when a visitor finishes a quiz. The chat overlay listens for it and may use it to refine context. You don't need to listen or dispatch this yourself.
• humind-continue-thread — dispatched by <humind-quiz> when a visitor clicks "Continue in chat" at the end of a quiz. Hands the quiz context off to the chat.

Both are emitted by the quiz widget, not fired by merchants. If you need to open the chat from your own code, use humind-open-chat.