webVox Integration Guide

Add AI voice conversations to your website with one script tag

Quick Start: 3 Steps to Add webVox

1 Get Your Developer Key

Generate a developer key from the Developer Portal. This key will be used to authenticate API requests.

Keep your developer key secure! Never expose it in client-side code.

2 Create an API Endpoint

Create a server endpoint that fetches temporary API keys. The aiId parameter will be passed automatically from your button.

// example for express.js
app.get('/webVoxKey', async (req, res) => {
	// IMPORTANT: Authenticate the user first to protect your webVox credits!
	// if (!req.session.user) return res.status(401).json({ error: 'Unauthorized' });
	
	const aiId = new URL(req.url).searchParams.get("aiId");
	
	const response = await fetch(
		`https://webvoxai.com/api?aiId=${aiId}`,
		{
			method: "POST",
			headers: {
				authorization: "Bearer YOUR_WEBVOX_DEVELOPER_KEY",
			},
		}
	);
	const json = await response.json();
	
	res.json({ apiKey: json.token });
});

Critical: Add authentication and rate-limiting to protect your webVox quota. Without this, anyone can use your credits!

💡 The aiId is automatically extracted from the button's data-ai-id attribute and passed as a query parameter.

3 Add the Embed Script

Include the webVox embed script in your HTML. Set the data-endpoint to your API endpoint path:

loading...

This script automatically detects the webVox button on your page and handles widget creation.

4 Add webVox Button

Create a button with data-webvox="true" and your AI's UUID in data-ai-id:

loading...

💡 Find your AI's UUID in your AI configurations page. Each AI config has a unique UUID.

How It Works

• User clicks a button with data-webvox="true"
• Script extracts the data-ai-id UUID from the button
• Script calls your endpoint: /webVoxKey?aiId={uuid}
• Your server authenticates the request and fetches a temporary API key from webVox
• Chat widget opens with the specified AI agent in bottom-right corner
• Widget can be opened and closed by users
• DOM tools (scroll, click, read) work automatically in the iframe context

What Your AI Can Do

🔍 Read Page Content

AI can understand your page content when embedded:

• Read specific elements by CSS selector
• Extract full page text content
• Access structured data and metadata
• Answer questions about visible content

🎯 Interact with Page

AI can guide users through your site:

• Scroll to specific elements
• Click buttons and links
• Smooth scrolling with visual feedback
• Help users navigate complex interfaces

🔒 Built-in Security

Safe and secure by design:

• DOM tools only work in iframe embed context
• Origin validation for all communications
• No direct access to parent page from main site
• Your developer key never exposed to clients

🎤 Voice Conversations

Natural voice interactions:

• Real-time voice conversations
• Automatic speech recognition
• Natural text-to-speech responses
• Works with any language your AI supports

Configuration Reference

Button Attributes

Attribute	Required	Example	Description
data-webvox	Yes	"true"	Enables webVox functionality on the button
data-ai-id	Yes	550e8400-e29b...	Your AI agent's UUID - find it in your AI configurations page

Script Attributes

Attribute	Required	Example	Description
data-endpoint	Yes	webVoxKey	The path to your API endpoint (receives `aiId` as query param)

Best Practices

Security First

Critical: Always authenticate users before generating keys
• Add rate limiting to your API endpoint (e.g., 10 requests/min per user)
• Never expose your developer key in client-side code
• Monitor usage in the Developer Portal regularly
• Consider IP-based rate limiting for extra protection

User Experience

• Use clear, descriptive button text like "Chat with support" or "Ask AI"
• Place buttons where users naturally look for help
• Test on mobile - widget is responsive and draggable
• Consider adding a small icon to buttons for visual clarity
• Multiple buttons per page are supported - use different AI IDs

Development Tips

• Test with console open to catch any API errors
• Verify the AI ID is correct - check your AI configs page
• Use meaningful AI names for easier debugging
• Test microphone permissions in different browsers
• Check network tab if widget doesn't appear

Common Mistakes

❌ Forgetting to authenticate in your endpoint
❌ Using wrong AI ID or typos in UUID
❌ Not adding rate limiting
❌ Exposing developer key in frontend code
❌ Testing without HTTPS (required for microphone access)

Support & Resources

Need Help?

Join our Discord community to get help from the team and other users with integration issues and questions.

Join Discord

Developer Portal

Manage your API keys, monitor usage, and access advanced configuration options.

Open Portal