The Voltai.load() function returns an instance with methods to control the widget from your code.
const voltai = Voltai.load({
apiKey: 'your-api-key'
});
// Now you can use voltai.open(), voltai.close(), voltai.login(), etc.
open()
Opens the chat panel.
If the visitor does not already have a guest or signed-in session, the widget opens into its verification step first. After verification completes, the chat UI appears automatically.
close()
Closes the chat panel.
toggle()
Toggles the chat panel open or closed.
Use these methods to integrate the widget with your own UI. For example, open the chat when a user clicks a “Need help?” button.
Sending messages
sendChat(query, options)
Sends a chat message programmatically. This lets you start conversations from your own code, like a search box or help button.
If the visitor does not already have a guest or signed-in session, the widget opens, keeps the latest queued query, shows the verification step, and submits the message automatically after verification succeeds.
await voltai.sendChat('How do I reset my password?', {
topics: ['Support']
});
| Name | Type | Description |
|---|
query | string | The message to send |
options | object | Required settings (see below) |
| Property | Type | Required | Description |
|---|
topics | string[] | Yes | Topic names to associate with the message. The backend resolves names to full topic objects. |
newChat | boolean | No | Start a new conversation (default: false) |
Promise<void>
Example: Basic usage
await voltai.sendChat('Show me getting started guides', {
topics: ['Documentation', 'Tutorials']
});
Example: Start a new chat
await voltai.sendChat('I have a billing question', {
topics: ['Billing'],
newChat: true
});
Example: Combined with open
// Open the widget and send a message
voltai.open();
await voltai.sendChat('What are your pricing plans?', {
topics: ['Sales'],
newChat: true
});
sendChat() no longer requires you to pre-authenticate the visitor yourself. If verification is needed, the widget handles it inline and submits the latest queued message afterward.
If multiple sendChat() calls are made before verification completes, the latest pending message replaces any earlier unsent one.
Authentication
login()
Opens the login popup for users to sign in.
You can call this before the widget is opened. If the widget is still finishing its initial auth bootstrap, the SDK waits until auth is ready and then runs the login flow.
logout()
Logs out the current user and clears their session.
isLoggedIn()
Returns whether a user is signed in. Returns false for guest users, and also returns false until auth initialization has settled.
if (voltai.isAuthReady() && !voltai.isLoggedIn()) {
await voltai.login();
}
boolean
isAuthReady()
Returns whether the widget has finished restoring the current auth state.
if (!voltai.isAuthReady()) {
console.log('Still initializing auth');
}
boolean
Cleanup
destroy()
Removes the widget from the page and cleans up all resources.
Use this when:
- Navigating away in a single-page app
- Conditionally removing the widget
- Reinitializing with different settings
Complete example
Here’s a page with custom buttons to control the widget:
<button id="open-btn">Open Chat</button>
<button id="close-btn">Close Chat</button>
<button id="ask-btn">Ask a Question</button>
<button id="login-btn">Sign In</button>
<button id="logout-btn">Sign Out</button>
<script src="https://cdn.voltai.ai/widget@latest/voltai-widget.js"></script>
<script>
const voltai = Voltai.load({
apiKey: 'your-api-key',
enableGuestUser: true
});
document.getElementById('open-btn').onclick = () => {
voltai.open();
};
document.getElementById('close-btn').onclick = () => {
voltai.close();
};
document.getElementById('ask-btn').onclick = async () => {
voltai.open();
await voltai.sendChat('How do I get started?', {
topics: ['Getting Started']
});
};
document.getElementById('login-btn').onclick = async () => {
await voltai.login();
};
document.getElementById('logout-btn').onclick = async () => {
await voltai.logout();
};
</script>