Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.voltai.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Voltai Widget supports different authentication modes to fit your use case.

​
Guest mode

Guest mode lets visitors use the chat without signing in. This is useful for public-facing support widgets where you want to minimize friction. Enable it with the enableGuestUser option: 
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true
});
When guest mode is enabled:
  • Users start chatting after a quick verification step the first time they open the widget or trigger a programmatic chat
  • A temporary session is created automatically
  • Chat history persists across page refreshes (stored locally)
  • Guest users are limited to 5 questions before being prompted to sign in
Guest sessions are anonymous and have a 5-question limit. After reaching this limit, users will need to log in to continue chatting.

​
Bot protection with hCaptcha

To protect against automated abuse, the widget integrates with hCaptcha. When enabled, guest users complete a captcha challenge inside the widget before their guest session is created. This happens when:
  • Guest mode is enabled (enableGuestUser: true)
  • hCaptcha is configured on your backend
  • The user opens the widget or a programmatic sendChat() call needs a guest session
The widget keeps the launcher visible at all times. If verification fails, users can retry from the open panel without losing access to the launcher.
hCaptcha configuration is handled server-side. Contact your administrator if you need to enable or adjust captcha settings.

​
Authenticated users

For applications where users have accounts, the widget supports popup-based authentication. This allows:
  • Users to sign in with their existing credentials
  • Conversations tied to their account
  • Chat history synced across devices
  • Personalized responses based on user context
  • Unlimited questions (no 5-question limit)

​
Auth0 Connection

If you have a specific login method configured for your organization, you can specify which connection to use: 
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  authConnection: 'EXAMPLE'
});
When authConnection is set, users are directed to that specific login method. When omitted, it displays its standard Login Widget with all available options.

​
Default organization selection

If authenticated users can belong to multiple organizations, you can tell the widget which organization to prefer after login: 
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  authConnection: 'EXAMPLE',
  defaultOrgName: 'Acme'
});
When defaultOrgName is set, the widget looks for a case-insensitive match against the user’s available organization names. If no match is found, it falls back to the first available organization automatically.

​
How authentication works

  1. Widget loads — The SDK initializes and checks for existing sessions
  2. Session check — If a valid token exists locally, it’s restored
  3. Open or send — If no session exists and guest mode is enabled, opening the widget or calling sendChat() shows the verification step
  4. Guest session — After captcha succeeds, a guest token is fetched and stored locally for future visits
  5. Continue chatting — The chat UI appears and any queued sendChat() request is submitted automatically

​
Programmatic authentication

You can check authentication status and trigger login programmatically from your code.

​
Waiting for auth state

The widget exposes auth methods immediately, but auth restoration still happens asynchronously after Voltai.load(). Use onAuthReady, auth:ready, or voltai.isAuthReady() when you need to make a decision based on the settled auth state before opening the widget. 
const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true,
  onAuthReady: ({ isLoggedIn, isGuest }) => {
    console.log('Auth initialized', { isLoggedIn, isGuest });
  }
});

​
Checking login status

Use isLoggedIn() to check if a user is signed in (returns false for guest users). If you care about startup timing, check isAuthReady() first: 
if (!voltai.isAuthReady()) {
  console.log('Still restoring auth state');
} else if (voltai.isLoggedIn()) {
  console.log('User is signed in with a full account');
} else {
  console.log('User is a guest or not logged in');
}

​
Triggering login

Prompt users to sign in. voltai.login() is safe to call before the widget is opened: 
if (!voltai.isLoggedIn()) {
  await voltai.login();
}

​
Logging out

await voltai.logout();

​
Listening for auth changes

Subscribe to authentication events to react when users log in or out: 
voltai.on('auth:ready', ({ isLoggedIn, isGuest }) => {
  console.log('Auth initialized', { isLoggedIn, isGuest });
});

voltai.on('auth:login', (payload) => {
  if (payload.isGuest) {
    console.log('Guest user logged in');
  } else {
    console.log('User signed in');
  }
});

voltai.on('auth:logout', () => {
  console.log('User logged out');
});

​
Example: Custom login button

<button id="login-btn">Sign In</button>

<script>
  const voltai = Voltai.load({
    apiKey: 'your-api-key',
    enableGuestUser: true,
    onAuthReady: () => {
      console.log('Auth initialization complete');
    }
  });

  document.getElementById('login-btn').onclick = async () => {
    if (!voltai.isLoggedIn()) {
      await voltai.login();
    }
  };
</script>

​
Example: Check auth before opening the widget

const voltai = Voltai.load({
  apiKey: 'your-api-key',
  enableGuestUser: true,
  onAuthReady: async ({ isLoggedIn }) => {
    if (!isLoggedIn) {
      await voltai.login();
    }
  }
});
In this flow:
  • onReady is too early for auth decisions because it only means the widget mounted.
  • onAuthReady runs after auth restoration has settled.
  • If the widget is later opened while the visitor still has no session and enableGuestUser is enabled, the guest captcha flow still happens inside the widget.

​
Handling authentication errors

If verification or authentication fails, the widget button still remains available and the open panel shows a retry path. Common issues:
  • Invalid API key — Verify your API key is correct
  • hCaptcha failure — May occur if the user’s browser blocks the captcha script
  • Network errors — Check connectivity to the backend

​
Security considerations

  • API keys are visible in client-side code. They’re scoped to your domain and only allow widget operations.
  • Guest tokens are short-lived and automatically refresh.
  • hCaptcha adds a layer of protection against automated abuse.
For sensitive applications, authenticated mode (coming soon) provides stronger user verification.