Skip to main content
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 can start chatting immediately
  • 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 an invisible captcha challenge before their session is created. This happens automatically when:
  • Guest mode is enabled (enableGuestUser: true)
  • hCaptcha is configured on your backend
The captcha runs invisibly in the background—users won’t see a challenge unless suspicious activity is detected.
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.

​
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. New session — If no session exists and guest mode is enabled:
    • hCaptcha challenge runs (if configured)
    • A guest token is fetched from the backend
    • Token is stored locally for future visits
  4. Ready — The onReady callback fires and the widget is usable

​
Handling authentication errors

If authentication fails, the widget won’t render. You can detect this through the onReady callback timing or by checking console logs during development. 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.