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, before the closing </body> tag:

<script src="https://xinfer.ai/t/1072/widget.js" async></script>

The number is your account ID. Copy the snippet from Admin > Chat Widget rather than typing it — the ID is used instead of your subdomain so that renaming your subdomain never breaks a widget already installed on your site.

Subdomain form. https://your-subdomain.xinfer.ai/widget.js also works; the loader detects which mode it was called in from its own src. Prefer the account-ID form above, because the subdomain form breaks if you ever rename your subdomain.

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/1072/widget.js"
  data-customer-id="12345"
  data-customer-name="John Doe"
  data-customer-email="john@example.com"
  data-customer-hmac="9f2b…"
  data-customer-phone="+1-555-123-4567"
  data-position="bottom-right"
  async
></script>

JavaScript Configuration Method

The global is XinferChat — lowercase i. JavaScript property names are case-sensitive, so a config object assigned to any other spelling is silently ignored.

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

JavaScript configuration takes precedence over data attributes.

Available Options

data-customer is still accepted as a legacy alias for data-customer-id.

Secure Mode — Required for Email Identity

An email passed on its own is a claim, not a proof: anyone can put any address in a script tag. It is only treated as an identity when accompanied by data-customer-hmac, computed on your server:

data-customer-hmac = HMAC-SHA256(your widget secret, email.trim().toLowerCase())

This fails closed — with no secret configured, a missing signature, or one that doesn't match, the visitor is simply treated as a guest and the email is not used to attach to an account. Shopify stores get this automatically via the theme app extension.

See Chat Widget for the full procedure and how to obtain your secret.

Programmatic Control

After the widget loads, you can control it via JavaScript. Note the spelling: XinferChat, lowercase i.

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

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

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

Widget Features

Admin Configuration

Configure the widget in Advanced Admin > App Config:

Domain Whitelist

For security, only whitelisted domains can load the widget. Add your domains in App Config:

• Your main website (e.g., yoursite.com)
• Subdomains if needed (e.g., *.yoursite.com for all subdomains)
• localhost for testing during 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/1072/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

Voice Chat

Both clients support voice conversations.

How It Works

1. Click the microphone/voice button
2. Grant microphone permission when prompted
3. Connection establishes with the voice service
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 Advanced 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
• Agent Voice - Choose your AI's voice personality
• Follow-Ups - Manage human assistance requests
• Shopping Carts - View and manage customer carts