Introduction - homie Documentation

The Client API is a browser-side JavaScript interface exposed by the homie embed script. Once the script loads, a global window.homieBot object becomes available so you can open or close the widget, check its state, send messages programmatically, attach metadata, and read the chat history — all from your own page code.

This page documents the client-side browser API exposed by the embed script. For server-side REST endpoints, see the REST API.

Install the embed script

Add the embed script to your page. Styling and behavior are managed from the homie platform and pulled in automatically by the embed.

<script
  src="https://cdn.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  defer
></script>

For platform-specific install steps, see the Installation overview.

Requirements

The script must be embedded on your page.
chatbotId must be set (on the script tag or via window.homieBotConfig).

See Configuration for all script attributes and global config objects.

When the API is available

The window.homieBot object only exists after the embed has initialized. Do not assume it is present at page load.

Reading window.homieBot immediately on page load may return undefined. Listen for the homiebot:api-ready event, or use the waitForHomie() polling fallback shown in the examples.

The embed dispatches browser events as it reaches each lifecycle stage:

Event	When
`homiebot:api-ready`	`window.homieBot` is available
`homiebot:assistant-ready`	Chat iframe is ready for `sendMessage` / `getHistory`
`homiebot:opened`	Chat widget was opened
`homiebot:closed`	Chat widget was closed

Each event carries { chatbotId } in event.detail. See Events for full details.

Methods at a glance

Method	Purpose
`open()`	Open the chat
`close()`	Close the chat
`toggle()`	Toggle open/closed
`isOpen()`	Read whether the widget is open
`isReady()`	Read whether the iframe is ready for messages
`sendMessage(input, options?)`	Inject a message into the chat
`getHistory()`	Read the current chat history
`updateMessageMetadata(metadata)`	Attach metadata to the next user message
`sendCustomPdpQuestion(questionSetId)`	Open the custom product-question flow
`trackPdpQuestionsView(element, questionSetId)`	Report a view for self-rendered product questions

See Methods for the full reference.

Explore the Client API

Configuration

Script attributes, global config objects, language and Shopify market resolution.

Methods

Full reference for every method on window.homieBot.

Events

Browser events dispatched by the embed for lifecycle and interaction.

Examples

Practical recipes for opening, messaging, and tracking.

Troubleshooting

Fixes for the most common integration issues.

​Install the embed script

​Requirements

​When the API is available

​Methods at a glance

​Explore the Client API

Configuration

Methods

Events

Examples

Troubleshooting

Install the embed script

Requirements

When the API is available

Methods at a glance

Explore the Client API