Methods - homie Documentation

All methods live on window.homieBot, which becomes available after the homiebot:api-ready event. Methods that send or read messages (sendMessage, getHistory, sendCustomPdpQuestion) require the iframe to be ready — they wait internally, but you can check readiness with isReady() or listen for homiebot:assistant-ready.

Always guard against window.homieBot being undefined at page load. See Examples for a wait-for-ready pattern.

open()

Opens the chat widget if it is currently closed. Returns void.

window.homieBot.open();

close()

Closes the chat widget if it is currently open. Returns void.

window.homieBot.close();

toggle()

Toggles the widget between open and closed. Returns void.

window.homieBot.toggle();

isOpen()

Returns boolean — whether the widget is currently open. Does not change the UI.

if (window.homieBot.isOpen()) {
  console.log('Chat is open');
}

isReady()

Returns boolean — whether the chat iframe is fully loaded and ready to accept sendMessage and getHistory. Use this before sending messages from late-bound code.

if (window.homieBot.isReady()) {
  window.homieBot.sendMessage({ text: 'Hello' });
}

sendMessage(input, options?)

Injects a message directly into the chat — ideal for product detail pages (PDPs) or context-driven prompts. Opens the chat first if it is closed. Returns a Promise.

await window.homieBot.sendMessage(
  { text: 'Do you have this product in grey?' },
  { open: true } // opens the chat before sending
);

input (required: text)

Field	Type	Description
`text`	string	The message to inject.
`id`	string	(optional) Your own reference/tracking ID.
`setId`	string	(optional) Question set ID for tracking.
`questionId`	string	(optional) Question ID within the set.
`newChat`	boolean	(optional) Start a new conversation.

options

Field	Type	Default	Description
`open`	boolean	`true`	Open chat if closed.
`maxRetries`	number	`3`	Retries while the iframe initializes.
`retryDelay`	number	`300`	Milliseconds between retries.
`timeout`	number	`5000`	Total timeout in ms waiting for ACK.
`relaxedOrigin`	boolean	`false`	Disable origin checks (special cases only).

The signature documented above is the supported public contract. The current embed source exposes a simplified sendMessage(input) form where input accepts text, questionSetId, questionId, type ('DEFAULT' | 'PDP_QUESTION'), and newChat, and no options argument. If you target the latest embed, prefer the text / newChat fields, which are stable across both.

getHistory()

Returns a Promise resolving to the current chat history payload from the iframe. Useful for custom tracking. The request times out after a few seconds if the iframe does not respond.

const history = await window.homieBot.getHistory();
console.log('Chat history:', history);

updateMessageMetadata(metadata)

Attaches metadata to the next user message as key-value pairs. Returns void. If the iframe is not yet ready, the metadata is queued and sent automatically once the iframe initializes. Multiple calls merge.

window.homieBot.updateMessageMetadata({
  productId: '12345',
  category: 'power-tools',
  source: 'pdp',
});

Limits and validation

Constraint	Limit
Max keys	5 key-value pairs per call
Key length	Max 50 characters
Value length	Max 100 characters
Key type	Must be a string
Value type	String, or `null` to remove a key

Merging and removing keys

Existing keys can be overwritten with new values.
Keys are removed by passing null as the value.
Multiple calls are merged — new keys are added, existing keys are updated.

// Set initial metadata
window.homieBot.updateMessageMetadata({
  productId: '12345',
  category: 'power-tools',
});

// Update an existing key and add a new one
window.homieBot.updateMessageMetadata({
  category: 'hand-tools', // overwrites existing
  brand: 'Bosch', // adds new key
});

// Remove a key
window.homieBot.updateMessageMetadata({
  brand: null, // removes the key
});

Single-page applications (SPAs): metadata keys persist across navigation because they live in the global window context. When you navigate between pages, clear stale metadata manually by calling updateMessageMetadata() with null values to avoid unintended persistence.

// Clear metadata on a route change in an SPA
window.homieBot.updateMessageMetadata({
  productId: null,
  category: null,
  source: null,
});

sendCustomPdpQuestion(questionSetId)

Opens the chat and triggers the custom product-question flow for a given question set. Returns a Promise. This method backs the “ask something else” button rendered by the product-questions widget.

await window.homieBot.sendCustomPdpQuestion('pdp-questions-set-123');

This method is exposed on window.homieBot but is primarily intended for the built-in product-questions widget. Use it only if you render your own custom product-question entry point.

trackPdpQuestionsView(element, questionSetId)

Reports a qualified view (impression) for self-rendered product questions. Returns void. Use this when your shop fetches the product questions from the REST API and renders them with its own markup — it applies the same viewability rules as the built-in rendering, so your views and click-through rates stay comparable in the platform’s analytics:

counts only when the element has been at least 50% visible in the viewport for 1 second
counts at most once per page visit (per product URL)
safe to call again on framework re-renders — a pending measurement is re-armed on the new element, a counted visit never fires twice

Call it once right after rendering your questions element:

// You fetched { questionSetId, questions } from the product questions API
// and rendered your own UI into `container`.
window.homieBot.trackPdpQuestionsView(container, questionSetId);

Parameter	Type	Description
`element`	Element	The DOM element containing your rendered questions.
`questionSetId`	string	The question set ID returned by the questions endpoint.

Views are the denominator of the click-through rate. If you render questions yourself and never call this method, your product pages will show clicks but no views in the analytics.

​open()

​close()

​toggle()

​isOpen()

​isReady()

​sendMessage(input, options?)

​getHistory()

​updateMessageMetadata(metadata)

​sendCustomPdpQuestion(questionSetId)

​trackPdpQuestionsView(element, questionSetId)

open()

close()

toggle()

isOpen()

isReady()

sendMessage(input, options?)

getHistory()

updateMessageMetadata(metadata)

sendCustomPdpQuestion(questionSetId)

trackPdpQuestionsView(element, questionSetId)