Chat Clients: Full Interface vs Embeddable Widget

Your AI agent can be accessed through two different chat clients, each designed for different use cases. This guide explains both options and helps you choose the right approach.

Overview

Both clients support text chat, voice conversations, and all AI features.

Full Chat Interface

The full chat interface is a complete, standalone web application for interacting with your AI assistant.

Access URL

https://xinfer.ai/t/your-subdomain

Or for a specific conversation:

https://xinfer.ai/t/your-subdomain/chat/[chat-id]

Page Layout

Desktop View:

Mobile View:

Key Features

Sidebar

Chat Area

Input Area

Keyboard Shortcuts

URL Parameters

User Types

Guest Users:

• Can chat if guest permission is enabled
• Session-based history (not persistent)
• See login/signup prompts

Logged-in Users:

• Persistent chat history across sessions
• Can vote on responses
• Profile and preferences saved

Admin Users:

• "Admin Mode" to view any user's chats
• Access to admin panel from menu

Embeddable Widget

The chat widget is a floating button and panel that can be embedded on any website.

Basic Installation

Add one line to your website:

<script src="https://xinfer.ai/t/[your-workspace]/widget.js" async></script>

Replace [your-workspace] with your workspace subdomain (e.g., mycompany).

Place before the closing </body> tag.

Important: The widget URL must include /t/[workspace]/. URLs like /embed.js or /widget.js without the tenant path do not exist.

Widget Appearance

Collapsed: Floating chat button in corner Expanded: Chat panel with full conversation interface

Default position: bottom-right corner

Configuration Options

Data Attributes Method

<script
  src="https://xinfer.ai/t/your-subdomain/widget.js"
  data-customer-id="12345"
  data-customer-name="John Doe"
  data-customer-email="john@example.com"
  data-customer-phone="+1-555-123-4567"
  data-position="bottom-right"
  async
></script>

JavaScript Configuration Method

<script>
  window.XinferChat = {
    customerId: '12345',
    customerName: 'John Doe',
    customerEmail: 'john@example.com',
    customerPhone: '+1-555-123-4567',
    position: 'bottom-left',
    onReady: function() {
      console.log('Chat widget is ready');
    }
  };
</script>
<script src="https://xinfer.ai/t/your-subdomain/widget.js" async></script>

JavaScript configuration takes precedence over data attributes.

Available Options

Programmatic Control

After the widget loads, you can control it via JavaScript:

// Open the widget
window.XinferChat.open();

// Close the widget
window.XinferChat.close();

// Toggle open/closed
window.XinferChat.toggle();

Widget Features

Admin Configuration

Configure in Admin > App Config under the embed section:

{
  "embed": {
    "enabled": true,
    "allowedDomains": ["yoursite.com", "*.yoursite.com", "localhost"],
    "theme": {
      "primaryColor": "#6366f1",
      "position": "bottom-right",
      "borderRadius": 16
    },
    "autoPromptCount": 3
  }
}

Domain Whitelist

Only whitelisted domains can load the widget:

{
  "allowedDomains": [
    "example.com",        // Exact match
    "*.example.com",      // All subdomains
    "localhost"           // Local development
  ]
}

Comparison: Full Chat vs Widget

When to Use Full Chat

• As your primary AI support destination
• When users need full conversation history
• For complex, multi-session interactions
• When you want users to log in and track history

When to Use Widget

• Add AI help to existing website
• E-commerce product assistance
• Contextual help on specific pages
• Lead capture without leaving your site

Advanced Integration

Customer Identity Linking

Pass your customer ID to link conversations:

<script
  src="https://xinfer.ai/t/your-subdomain/widget.js"
  data-customer-id="CRM-12345"
  async
></script>

Benefits:

• Match chat conversations to CRM records
• Track customer interactions in analytics
• Pre-populate context for the AI
• Include customer data in follow-up requests

Technical Details

Widget Loading Flow

1. Page loads widget.js from your tenant URL
2. Loader extracts tenant and data attributes
3. Main widget bundle loads from /embed/widget.js
4. Widget fetches config from /t/tenant/embed/config
5. Guest session initialized via /t/tenant/api/auth/guest
6. Widget renders and is ready

Storage

Widget localStorage keys (prefixed with xinfer_{tenant}_):

• Chat ID for conversation continuity
• Messages for offline persistence
• Auto-prompt shown count

Full chat uses both localStorage and server-side persistence for logged-in users.

Cross-Origin Sessions

For session sharing between widget and full chat:

• HTTPS required on both sites
• Cookies use SameSite=None; Secure
• User can log in on main site, see same session in widget

Shadow DOM Isolation

The widget creates its own shadow DOM to prevent CSS conflicts with your website. This ensures consistent appearance regardless of your site's styles.

Z-Index

Widget uses z-index: 2147483647 (maximum) to appear above all other content.

Voice Chat

Both clients support voice conversations powered by Hume AI.

How It Works

1. Click the microphone/voice button
2. Grant microphone permission when prompted
3. Connection establishes with Hume AI
4. Speak naturally - AI responds with voice
5. Click "End Call" to return to text

Requirements

• Modern browser (Chrome, Firefox, Safari, Edge)
• Microphone permission
• HTTPS connection
• Voice enabled in app config

Voice Messages

Voice conversations are automatically transcribed and saved to chat history, so users can review what was discussed.

Access Control

Permission Levels

Configure in Admin > App Config:

Email Confirmation

If chatPermission is "user" and email isn't confirmed:

• Chat shows confirmation message
• Link to resend confirmation
• Must verify email to continue

Troubleshooting

Widget Not Loading

1. Check browser console for errors
2. Verify domain is in allowedDomains
3. Ensure embed.enabled is true
4. Confirm script URL is correct

"Domain not allowed" Error

Add your domain to embed.allowedDomains:

• Include production domain
• Include staging/preview domains
• Add localhost for development

Customer Data Not Pre-filling

• Use correct attribute names (data-customer-name, not data-name)
• Ensure values aren't empty strings
• Load script with async attribute

Voice Not Working

• Check microphone permission is granted
• Verify browser supports WebRTC
• Ensure voice is enabled in app config
• Try a different browser (Chrome recommended)

Chat History Missing

• Guest users: History is session-only
• Must be logged in for persistent history
• Try refreshing the page

Summary

Both clients provide the same AI capabilities - choose based on how users will access your AI assistant.

Related Pages

• Integration - Get embed codes and URLs
• App Config - Configure chat settings
• Text Prompts - Customize AI behavior
• Voice Prompts - Configure voice responses
• Follow-Ups - Manage human assistance requests