Docs
Add the chat widget to your website
The VoxelEon chat widget is a single script tag — no SDK installation, no build step. Paste it before the closing </body> tag of every page you want the widget on.
1. Get your website token
In your VoxelEon dashboard, go to Settings → Inboxes → Add Inbox → Website, create a website channel, and copy the install snippet shown there — it already has your website token filled in. The snippet below is the same one, for reference.
2. Paste the snippet
Replace YOUR_WEBSITE_TOKEN with the token from your dashboard.
<script>
(function(d,t) {
var BASE_URL="https://app.voxeleon.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/voxeleon-sdk.js";
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.voxeleonSDK.run({
websiteToken: 'YOUR_WEBSITE_TOKEN',
baseUrl: BASE_URL
})
}
})(document,"script");
</script>3. (Optional) Configure the widget
Set window.voxeleonSettings before the install script to customize position, style, and launcher text.
<script>
window.voxeleonSettings = {
position: 'right', // 'left' or 'right'
type: 'standard', // 'standard' or 'expanded_bubble'
launcherTitle: 'Chat with us',
darkMode: 'auto' // 'light', 'dark', or 'auto'
};
</script>4. (Optional) Identify logged-in users
If a visitor is already signed in on your site, pass their identity to the widget so conversations are attributed to the right customer.
window.$voxeleon.setUser('user-id-123', {
email: 'jane@example.com',
name: 'Jane Doe',
});Runtime API reference
After the voxeleon:ready event, these methods are available on window.$voxeleon.
| toggle(state?) | Open or close the chat window. Pass 'open' or 'close', or nothing to switch. |
| toggleBubbleVisibility(visibility) | Show or hide the launcher bubble: 'show' or 'hide'. |
| popoutChatWindow() | Open the chat in its own browser window. |
| setUser(identifier, user) | Identify the visitor. identifier is a string or number; user has at least one of name, email, avatar_url (also phone_number and identifier_hash). |
| setCustomAttributes(attributes) | Set attributes on the contact, such as plan or company. |
| deleteCustomAttribute(key) | Remove one contact attribute. |
| setConversationCustomAttributes(attributes) | Set attributes on the current conversation, such as the page or product. |
| deleteConversationCustomAttribute(key) | Remove one conversation attribute. |
| setLabel(label) | Add a label to the conversation. The label must exist in VoxelEon. |
| removeLabel(label) | Remove a label from the conversation. |
| setLocale(locale) | Change the widget language, for example 'fr' or 'pt_BR'. |
| setColorScheme(mode) | 'light', 'dark' or 'auto'. |
| reset() | Forget the visitor and the current conversation, for example when they log out. |
window.addEventListener('voxeleon:ready', () => {
window.$voxeleon.setCustomAttributes({ plan: 'pro', company: 'Acme' });
window.$voxeleon.setConversationCustomAttributes({ page: location.pathname });
});Settings reference
Set these on window.voxeleonSettings before the install snippet runs.
| position | 'left' or 'right' (default 'right'). |
| type | 'standard' (round bubble) or 'expanded_bubble' (bubble with a label). |
| launcherTitle | The label on the expanded bubble. |
| darkMode | 'light' (default), 'dark' or 'auto'. |
| locale | Widget language, for example 'en' or 'pt_BR'. |
| useBrowserLanguage | true to follow the visitor's browser language instead of locale. |
| hideMessageBubble | true to hide the launcher; open the chat yourself with toggle(). |
| showPopoutButton | true to let visitors pop the chat out into its own window. |
| showUnreadMessagesDialog | false to stop showing the unread message preview (default true). |
| widgetStyle | 'standard' or 'flat'. |
| welcomeTitle / welcomeDescription | Override the greeting shown when the chat opens. |
| availableMessage / unavailableMessage | Override the status text when your team is online or away. |
| enableFileUpload / enableEmojiPicker / enableEndConversation | true or false to turn those chat features on or off. |
Verified identity (identifier_hash)
Without a hash, anyone can claim to be any user. For logged-in users, compute an HMAC-SHA256 of the identifier on your server, keyed with the website inbox's HMAC token (VoxelEon, Inboxes, your website inbox, Configuration), and pass it as identifier_hash. Turn on "Require identity validation for all conversations" in the inbox to refuse unverified users. Never put the HMAC token in browser code.
import { createHmac } from "node:crypto";
const identifierHash = createHmac("sha256", process.env.VOXELEON_HMAC_TOKEN)
.update(String(user.id))
.digest("hex");$identifier_hash = hash_hmac( 'sha256', (string) $user->ID, $hmac_token );window.$voxeleon.setUser(String(user.id), {
name: user.name,
email: user.email,
identifier_hash: identifierHash, // computed on your server
});5. (Optional) Listen for widget events
The widget dispatches events on window you can hook into, e.g. window.addEventListener('voxeleon:ready', () => { ... }).
| voxeleon:ready | The widget has finished loading. |
| voxeleon:opened | The visitor opened the chat window. |
| voxeleon:closed | The visitor closed the chat window. |
| voxeleon:on-message | A new message was sent or received in the conversation. |
| voxeleon:on-start-conversation | The visitor started a new conversation. |
| voxeleon:postback | The visitor pressed a button in a bot message; event.detail has the payload. |
| voxeleon:error | The widget could not load or an identity call failed; event.detail has the reason. |
Need help?
Email hello@voxeleon.com and we'll help you get the widget live.