Skip to content

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).
launcherTitleThe label on the expanded bubble.
darkMode'light' (default), 'dark' or 'auto'.
localeWidget language, for example 'en' or 'pt_BR'.
useBrowserLanguagetrue to follow the visitor's browser language instead of locale.
hideMessageBubbletrue to hide the launcher; open the chat yourself with toggle().
showPopoutButtontrue to let visitors pop the chat out into its own window.
showUnreadMessagesDialogfalse to stop showing the unread message preview (default true).
widgetStyle'standard' or 'flat'.
welcomeTitle / welcomeDescriptionOverride the greeting shown when the chat opens.
availableMessage / unavailableMessageOverride the status text when your team is online or away.
enableFileUpload / enableEmojiPicker / enableEndConversationtrue 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:readyThe widget has finished loading.
voxeleon:openedThe visitor opened the chat window.
voxeleon:closedThe visitor closed the chat window.
voxeleon:on-messageA new message was sent or received in the conversation.
voxeleon:on-start-conversationThe visitor started a new conversation.
voxeleon:postbackThe visitor pressed a button in a bot message; event.detail has the payload.
voxeleon:errorThe 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.