Doku
Widget reference
Configuration options, callbacks, context providers and custom actions for the chat widget.
All options are passed to the MochiiWidget constructor. Only apiKey is required.
const widget = new MochiiWidget({
apiKey: "YOUR_API_KEY",
// ...options
});
Appearance
| Option | Type | Description |
|---|---|---|
position | "bottom-right" or "bottom-left" | Corner in which the chat bubble appears. |
theme | "light", "dark" or "auto" | Color theme. auto follows the visitor's system setting. |
primaryColor | string | Brand color as a hex value, for example "#7C3AED". |
width | number | Width of the chat window in pixels. |
height | number | Height of the chat window in pixels. |
Branding and messages
| Option | Type | Description |
|---|---|---|
title | string | Title shown in the chat header. |
brandName | string | Name of the assistant. |
avatar | string | URL of the assistant's avatar image. |
inputPlaceholder | string | Placeholder text in the message box. |
firstMessages | string[] | Messages shown when the chat opens. |
suggestedMessages | string[] | Quick replies offered to the visitor. |
persistChat | boolean | Keep the conversation when the visitor returns. |
domain | string | Base URL of the Mochii API. Use https://www.mochii.ai. |
Contextual messages
The widget can generate its greeting and suggestions from the page the visitor is on:
new MochiiWidget({
apiKey: "YOUR_API_KEY",
generateContextualMessages: {
enabled: true,
prompt: "Based on the current page, write a relevant greeting",
generateSuggestions: true,
},
});
Callbacks
new MochiiWidget({
apiKey: "YOUR_API_KEY",
callbacks: {
onOpen: () => console.log("Widget opened"),
onClose: () => console.log("Widget closed"),
onMessage: (message) => console.log("New message", message),
},
});
Context providers
Context providers tell the chatbot about the current page and visitor, so it can give more relevant answers. Both functions are called when the chatbot needs the information.
new MochiiWidget({
apiKey: "YOUR_API_KEY",
contextProvider: {
getPageContext: async () => ({
url: window.location.href,
title: document.title,
description: document
.querySelector('meta[name="description"]')
?.getAttribute("content"),
}),
getUserContext: async () => ({
userId: "user_123",
preferences: {},
}),
},
});
Only pass information you are comfortable sharing with the chatbot, and nothing the visitor has not agreed to share.
Custom actions
Actions let the chatbot do things on your site, such as navigating to a page or opening a dialog. Describe each action and its parameters; the chatbot decides when to call it.
new MochiiWidget({
apiKey: "YOUR_API_KEY",
actions: [
{
name: "navigateTo",
description: "Navigate to a specific page",
parameters: {
path: {
type: "string",
description: "The path to navigate to",
required: true,
},
},
execute: async ({ path }) => {
window.location.href = path;
return { success: true };
},
},
],
});
Write clear descriptions. The chatbot relies on them to choose the right action and fill in the parameters.