Customize for Your Use Case
While these guidelines provide a solid foundation, remember that every knowledge base is unique. Here are some key points to consider:
- Experiment with different structures to find what works best for your specific needs.
- UI elements may require special attention - their optimal format can vary based on your agent.
- Don't hesitate to iterate and refine your approach over time.
The standard prototype environment provides a full-featured preview of your agent with development tools and debugging capabilities.
Conversation Testing
- • Test various user intents
- • Validate response accuracy
- • Check conversation flow
- • Verify knowledge base integration
UI/UX Validation
- • Visual design verification
- • Theme and branding check
- • Responsive behavior testing
- • Accessibility compliance
The voice prototype environment specifically focuses on testing voice interactions, speech recognition, and audio features.
🎧 Audio Testing Checklist
Input Testing:
- • Clear speech recognition
- • Background noise filtering
- • Multiple microphone types
- • Various audio qualities
Output Testing:
- • Voice clarity and tone
- • Speaking pace and rhythm
- • Pronunciation accuracy
- • Emotional expression
```json theme={null}
{
"voice": {
"provider": "elevenlabs",
"voice_id": "your-voice-id",
"speed": 1.0,
"stability": 0.75,
"clarity": 0.75
}
}
```
Test different voice providers and settings to find the perfect match for your brand personality and use case.
```json theme={null}
{
"transcription": {
"provider": "deepgram",
"model": "nova-2",
"language": "en-US",
"smart_format": true,
"punctuate": true
}
}
```
Use different transcription models to test accuracy with your specific use case and target audience.
```javascript theme={null}
// Enable debug mode for detailed logging
window.VG_CONFIG = {
debug: true,
logLevel: 'verbose', // 'error', 'warn', 'info', 'debug', 'verbose'
// Custom debug settings
debugSettings: {
showConversationFlow: true,
logApiCalls: true,
trackPerformance: true,
highlightElements: true
}
}
```
* Conversation flow tracking
* API request/response logs
* Performance timing data
* Error stack traces
* Configuration validation
* Element highlighting
* State visualization
* Flow diagram overlay
* Performance heat maps
* Interaction tracking
**Debug Console**: Open your browser's developer tools to access comprehensive logging and debugging information during prototype testing.
Key Performance Indicators
Response Times:
- • First response: \<2 seconds
- • Subsequent responses: \<1 second
- • Voice processing: \<3 seconds
- • Knowledge base queries: \<1.5 seconds
Quality Metrics:
- • Response accuracy: >95%
- • Intent recognition: >90%
- • Voice clarity: High quality
- • Error rate: \<1%
```javascript theme={null}
// A/B testing configuration
window.VG_CONFIG = {
experiment: {
name: 'greeting_test_v1',
variant: 'B', // 'A' or 'B'
variants: {
A: {
greeting: "Hello! How can I help you today?",
style: "formal"
},
B: {
greeting: "Hey there! What can I do for you? 😊",
style: "casual"
}
}
}
}
```
* Greeting messages and tone
* Response personalities
* Visual themes and layouts
* Conversation flow patterns
* Feature availability
* User engagement rates
* Conversation completion
* User satisfaction scores
* Task completion success
* Response relevance ratings
Run A/B tests in the prototype environment to validate changes before implementing them in production.
Essential Test Cases
Basic Interactions:
- □ Initial greeting and welcome
- □ Simple question answering
- □ Knowledge base queries
- □ Fallback responses
- □ Conversation ending
Advanced Features:
- □ Multi-turn conversations
- □ Context maintenance
- □ Tool/function calling
- □ Human handoff triggers
- □ Voice interaction (if enabled)
User Experience Checklist
Visual Design:
- □ Brand consistency
- □ Color contrast (WCAG)
- □ Font readability
- □ Image quality
- □ Animation smoothness
Responsiveness:
- □ Mobile layout
- □ Tablet adaptation
- □ Desktop optimization
- □ Touch interactions
- □ Keyboard navigation
Accessibility:
- □ Screen reader support
- □ Keyboard navigation
- □ Focus indicators
- □ Alt text for images
- □ High contrast mode
Desktop Browsers:
- □ Chrome (latest 2 versions)
- □ Firefox (latest 2 versions)
- □ Safari (latest 2 versions)
- □ Edge (latest 2 versions)
Mobile Browsers:
- □ Mobile Chrome
- □ Mobile Safari
- □ Samsung Internet
- □ Mobile Firefox
**Prototype Not Loading:**
```javascript theme={null}
// Check configuration
console.log('VG_CONFIG:', window.VG_CONFIG);
// Verify required fields
if (!window.VG_CONFIG?.ID) {
console.error('Missing agent ID');
}
```
**Common Fix**: Ensure your agent ID is correct and your account has access to the testing environment.
```javascript theme={null}
// Advanced debugging setup
window.VG_DEBUG = {
enabled: true,
// Log all events
logEvents: true,
// Track conversation state
trackState: true,
// Monitor performance
performanceMonitoring: true,
// Visual debugging
highlightElements: true
};
```
**Browser DevTools**: Use the Network tab to monitor API calls, Console for logging, and Performance tab for runtime analysis.
The welcome center of your widget - your users' first impression and primary navigation hub.
A comprehensive conversation history interface that keeps users engaged and informed.
Key Features
- ✅ Chronological conversation display
- ✅ One-click conversation resumption
- ✅ Search and filter capabilities
- ✅ Export conversation transcripts
- ✅ Mobile-optimized interface
Self-service support that reduces chat volume while providing instant answers.
```text theme={null}
Header Title: "Welcome back, {user.name}! 👋"
Description: "How can we help you today?"
Height: 120px (recommended)
```
**Dynamic Variables Available:**
* `{user.name}` - User's display name
* `{user.email}` - User's email address
* `{user.company}` - Company name (if available)
Best Practice Examples
E-commerce:
- "Track my order"
- "Return policy"
- "Size guide"
SaaS:
- "Getting started"
- "Billing questions"
- "Feature requests"
External Content Sources
- 🔗 **Help Center Integration**: Embed your existing documentation
- 📊 **Analytics Dashboards**: Show real-time metrics to users
- 🛒 **E-commerce Data**: Display order status and product info
- 📅 **Calendar Systems**: Enable appointment booking
**Quick Diagnostic Checklist:**
* ✅ Button visibility enabled in settings
* ✅ Required features (voice, handoff) properly configured
* ✅ Custom URLs are accessible and valid
* ✅ No JavaScript errors in browser console
If voice calling buttons don't work, ensure your voice configuration is complete and enabled.
```text theme={null}
Font Options:
- Any Google Font name (e.g., "Roboto", "Open Sans", "DM Sans")
- "inherit" - Use your website's existing font
- Custom web fonts (via CSS import)
```
**Popular Professional Fonts:**
* **DM Sans** - Modern, clean (default)
* **Inter** - Highly readable, tech-focused
* **Poppins** - Friendly, approachable
* **Roboto** - Google's flagship, versatile
Avoid "inherit" unless you're certain your website font loads properly in the widget context
Best For:
- ✅ Mobile-first designs
- ✅ Limited horizontal space
- ✅ Clean, stacked appearance
- ✅ Easy thumb navigation
Best For:
- ✅ Desktop-focused interfaces
- ✅ Quick action accessibility
- ✅ Compact widget designs
- ✅ Traditional web layouts
Best For:
- ✅ Persistent action buttons
- ✅ Chat-focused interfaces
- ✅ Minimal visual interference
- ✅ Always-visible controls
Background Image Options
Subtle Patterns:
- • Light textures
- • Geometric patterns
- • Brand watermarks
Avoid:
- • Busy, distracting images
- • High contrast backgrounds
- • Text-heavy graphics
```json theme={null}
{
"primary": "#your-brand-color",
"auto_generate": true,
"theme_type": "light" // or "dark"
}
```
* Choose your primary brand color
* System generates 9 complementary shades
* Ensures proper contrast ratios
* Maintains accessibility standards
* Customize each color shade individually
* Fine-tune for specific brand guidelines
* Advanced color theory application
* Perfect brand color matching
Cool Colors (Blue, Green, Purple):
- • Trust and reliability
- • Professional services
- • Technology and innovation
- • Healthcare and wellness
Warm Colors (Red, Orange, Yellow):
- • Energy and excitement
- • Food and hospitality
- • Retail and e-commerce
- • Creative industries
```css theme={null}
/* Example custom CSS overrides */
.widget-container {
border-radius: 20px;
box-shadow: 0 10px 25px rgba(0,0,0,0.1);
}
.chat-message {
font-weight: 500;
line-height: 1.6;
}
.primary-button {
background: linear-gradient(45deg, #your-color1, #your-color2);
}
```
**CSS Customization Capabilities:**
* Override default styling
* Add custom animations
* Implement brand-specific effects
* Fine-tune spacing and typography
Advanced CSS should be tested thoroughly across different browsers and devices
Mobile-First Design Principles
- 🔄 **Vertical layouts** work better on mobile screens
- 👆 **Touch-friendly buttons** with adequate spacing
- 📱 **Readable fonts** at minimum 14px size
- 🎯 **High contrast** for outdoor visibility
- ⚡ **Fast loading** optimized images
Desktop Enhancement Features
- 🖱️ **Hover effects** for interactive elements
- ⌨️ **Keyboard navigation** support
- 📏 **Larger layouts** utilizing screen space
- 🎨 **Rich graphics** and detailed images
- ⚡ **Advanced animations** and transitions
**Common Image Issues & Solutions:**
* **Not loading**: Check file size (≤0.5MB) and format (PNG/JPG/WebP)
* **Poor quality**: Use high-resolution source images
* **Slow loading**: Compress images using tools like TinyPNG
* **Wrong dimensions**: Resize to recommended specifications
Images hosted on external servers may have CORS restrictions. Use the built-in upload feature for reliable delivery.
View and manage all tools available to your agent, including workspace-wide tools and agent-specific custom functions.
Tool Management Actions
Enable Tools:
- • Select from available library
- • Configure tool parameters
- • Set access permissions
- • Test functionality
Disable Tools:
- • Remove from agent's toolkit
- • Preserve configuration
- • Maintain audit logs
- • Re-enable when needed
Specialized tools for managing and querying your agent's knowledge base with advanced search and content management capabilities.
```javascript theme={null}
// Tool test configuration
{
"test_suite": {
"name": "customer_lookup_tests",
"tests": [
{
"name": "valid_customer_email",
"input": {
"email": "test@example.com"
},
"expected_output": {
"status": "found",
"customer_id": "12345"
},
"timeout": 3000
},
{
"name": "invalid_email_format",
"input": {
"email": "invalid-email"
},
"expected_output": {
"status": "error",
"message": "Invalid email format"
}
}
]
}
}
```
* **Unit Tests**: Individual function testing
* **Integration Tests**: API connectivity validation
* **Performance Tests**: Response time measurement
* **Error Tests**: Failure scenario handling
* Pass/fail status for each test
* Execution time measurements
* Error details and stack traces
* Performance benchmarks
Key Performance Indicators
Reliability Metrics:
- • Uptime: 99.9%
- • Success Rate: 98.5%
- • Error Rate: \<1.5%
- • Timeout Rate: \<0.1%
Performance Targets:
- • Response Time: \<2s
- • Availability: 99.9%
- • Throughput: 1000 req/min
- • Cache Hit: >80%
```javascript theme={null}
// Error tracking configuration
{
"error_monitoring": {
"log_level": "INFO", // DEBUG, INFO, WARN, ERROR
"capture_stack_traces": true,
"include_request_data": true,
"alert_thresholds": {
"error_rate": 5, // Alert if >5% error rate
"response_time": 5000, // Alert if >5s response
"failure_count": 10 // Alert after 10 consecutive failures
}
}
}
```
* **API Errors**: External service failures
* **Validation Errors**: Invalid input parameters
* **Timeout Errors**: Slow response handling
* **Authentication Errors**: Access permission issues
* **System Errors**: Internal processing failures
* **Automatic Retry**: For transient failures
* **Fallback Responses**: When tools are unavailable
* **User Notifications**: Clear error explanations
* **Escalation Paths**: Human handoff triggers
* **Recovery Procedures**: Quick restoration methods
```javascript theme={null}
{
"caching": {
"enabled": true,
"strategy": "smart", // 'none', 'simple', 'smart'
"ttl": 300, // Time to live in seconds
"cache_key_pattern": "${function_name}_${param_hash}",
"invalidation_triggers": [
"data_update",
"configuration_change"
]
}
}
```
* **Memory Cache**: Fast in-memory storage
* **Distributed Cache**: Shared across instances
* **Persistent Cache**: Disk-based storage
* **Smart Cache**: AI-driven cache management
* Reduced API calls
* Faster response times
* Lower costs
* Improved reliability
```javascript theme={null}
{
"version_control": {
"current_version": "2.1.0",
"available_versions": [
{
"version": "2.1.0",
"status": "active",
"release_date": "2024-01-15",
"changelog": "Added new parameter validation"
},
{
"version": "2.0.1",
"status": "deprecated",
"release_date": "2023-12-10",
"changelog": "Bug fixes and performance improvements"
}
],
"rollback_enabled": true,
"auto_update": false
}
}
```
* **Semantic Versioning**: Clear version numbering
* **Backward Compatibility**: Legacy support
* **Migration Tools**: Automated upgrades
* **Testing Environments**: Safe version testing
* **Staged Rollouts**: Gradual deployment
* **Canary Releases**: Limited testing
* **Rollback Capability**: Quick reversion
* **Feature Flags**: Selective activation
Standard Widget Display
- 🎯 **Floating bubble** appears in chosen corner
- 📱 **Click to expand** reveals full chat interface
- 🔄 **Persistent state** maintains conversation across page navigation
- ⚡ **Fast loading** with optimized bundle sizes
- 🎨 **Branded appearance** using your custom theme
```javascript theme={null}
VG_CONFIG = {
modalMode: true,
render: 'bottom-right'
}
```
* Center-screen overlay display
* Focused user attention
* Larger conversation area
* Professional presentation
* Customer support portals
* Lead generation forms
* Product consultation
* Detailed assistance flows
```javascript theme={null}
VG_CONFIG = {
autostart: true,
// Widget opens automatically with proactive message
}
```
**Use Auto-start Carefully**: Only enable auto-start for high-intent pages where users expect immediate assistance (like support pages or checkout flows).
**Best Practices for Auto-start:**
* Use on specific high-value pages only
* Provide clear value proposition in opening message
* Respect user's ability to minimize/close
* Consider timing delays for better UX
```html theme={null}
```
* Easy implementation
* Automatic updates
* CDN-optimized delivery
* Cross-browser compatibility
* No additional dependencies
* Custom stylesheets
* User data pre-population
* Regional deployment
* Performance tuning
* Event callbacks
```javascript theme={null}
window.VG_CONFIG = {
ID: "your-agent-id",
region: 'na', // 'na' or 'eu'
render: 'bottom-right',
// Optional: User identification
user: {
name: 'John Doe',
email: 'john@company.com',
phone: '+1234567890'
},
// Optional: Custom styling
stylesheets: [
"https://cdn.example.com/custom-styles.css"
],
// Optional: Custom user ID
userID: 'your-internal-user-id',
// Optional: Auto-start configuration
autostart: false
}
```
```html theme={null}
```
* Dedicated chat pages
* Customer support portals
* Help center integration
* Controlled environments
* Fixed dimensions required
* Limited cross-domain features
* Separate security context
* Manual responsive handling
**iFrame Security**: Modern browsers may restrict some features in iframe contexts. Test thoroughly in your target environment.
```bash theme={null}
# Install official NPM package
npm install @tixae-labs/web-sdk
# Or with yarn
yarn add @tixae-labs/web-sdk
```
```javascript theme={null}
// React/Vue/Angular Integration
import { initConvocore } from '@tixae-labs/web-sdk';
const widget = initConvocore({
agentId: 'your-agent-id',
region: 'na',
position: 'bottom-right'
});
// Programmatic control
widget.open();
widget.close();
widget.sendMessage('Hello!');
```
* TypeScript support
* Framework integration
* Programmatic API
* Event system
* State management
* Version control
* Bundle optimization
* Development tools
* Documentation
* Community support
🔐 Secret API Key
Your agent's secret API key provides programmatic access to all agent data and operations. Keep this secure and never expose it in client-side code.
```javascript theme={null}
VG_CONFIG = {
// Custom CSS files for advanced styling
stylesheets: [
"https://cdn.example.com/custom-widget-styles.css",
"https://fonts.googleapis.com/css2?family=Your+Font"
]
}
```
```css theme={null}
/* Example custom widget CSS */
.vg-widget-container {
/* Custom border radius */
border-radius: 20px !important;
/* Custom shadow */
box-shadow: 0 10px 25px rgba(0,0,0,0.15) !important;
/* Custom animation */
transition: transform 0.3s ease !important;
}
.vg-widget-container:hover {
transform: scale(1.05) !important;
}
/* Custom message bubbles */
.vg-message-user {
background: linear-gradient(45deg, #your-color1, #your-color2) !important;
}
```
**CSS Priority**: Use `!important` declarations to ensure your custom styles override default widget styling.
Enforce consistent policies across all customer-facing agents:
Define technical rules and output formatting requirements:
```plaintext theme={null} OUTPUT FORMATTING RULES: - Always respond in valid JSON when using structured output - Maximum response length: 500 characters for each response - Include source citations for all factual claims - Use markdown formatting for emphasis - Never output sensitive information (passwords, API keys, etc.) API USAGE GUIDELINES: - Always verify data before calling external tools - Use the KB-Search tool before answering factual questions - Handle API errors gracefully with fallback responses ```Share domain expertise and terminology across specialized agents:
Coordinate behavior across agent teams for seamless experiences:
```plaintext theme={null} HANDOFF PROTOCOL: - Always capture: name, email, and inquiry type before handoff - Use the transfer_to_agent tool for complex requests - Provide context summary when needed AGENT SPECIALIZATIONS: - Sales Agent: Handle purchases and product inquiries - Support Agent: Technical issues and troubleshooting - Billing Agent: Invoices, payments, and account questions When a user's request is outside your expertise, immediately transfer to the appropriate specialized agent. ```Quickly deploy campaign-specific messaging across all agents:
```plaintext theme={null} HOLIDAY SALE CAMPAIGN (Dec 1-31, 2024): - Mention our "Holiday Special: 25% off all products" - Offer free shipping on orders over $50 - Highlight gift wrapping services - Promote extended return policy through January 15 - Use festive but professional language RESPONSE EXAMPLES: - "Great timing! We're offering 25% off during our holiday sale." - "Would you like free shipping? Orders over $50 qualify!" ```
Prompt Name
A descriptive name to identify this prompt (e.g., "Brand Voice Guidelines", "GDPR Compliance", "Holiday Campaign 2024")
Prompt Content
The actual instructions that will be appended to agents' system prompts. Write clear, specific guidelines using markdown formatting.
Select which agents should use this global prompt:
Assignment Rules
- Maximum Limit: Each agent can have up to 10 global prompts assigned
- Current Usage: The UI shows how many prompts each agent already has
- Multi-Select: Assign one prompt to multiple agents at once
- Instant Update: Changes take effect immediately for new conversations
Before saving, review how your prompt will appear:
```markdown theme={null} # Your Global Prompt Preview This is how your prompt content will be appended to the agent's system prompt. You can use: - **Bold text** for emphasis - `code blocks` for technical instructions - Lists for structured guidelines - Clear headings for organization ```You can modify agent assignments at any time:
When you delete a global prompt:
⚠️ Deletion Impact
- The prompt is immediately removed from all assigned agents
- Agents revert to using only their base system prompts
- Deletion is permanent and cannot be undone
- Active conversations will not experience behavior changes
Possible Causes:
Debug Steps:
- Check Prompts dashboard - is the agent listed as assigned?
- View agent settings - do global prompts appear in instructions?
- Start a fresh conversation (old ones use old prompts)
- Test with a clear, simple instruction to verify prompt is active
- Check for conflicting instructions in other prompt layers
When you can't assign more prompts:
If agents respond slowly after adding prompts:
Global prompts work seamlessly with Canvas node-based workflows:
Prompt Hierarchy
Order of Application:
- Global Prompts (from Prompts dashboard)
- Canvas Global Configuration (appendBeforePrompt)
- Node-Specific Instructions (per-node prompts)
Global prompts work with both text and voice agents:
Use global prompts across different deployment channels:
Website Chat Widget
Standard prompts with UI Engine formatting
WhatsApp/SMS
Add brevity guidelines, avoid complex formatting
Voice (Phone)
Conversational tone, shorter responses
Email
More formal, can be longer and detailed