autoch.at Documentation

Appearance

Live Chat Widget Setup ​

This guide walks you through integrating the Live Chat widget on your website.

Prerequisites ​

  • Active tenant account
  • Website where widget will be embedded
  • Widget token (generated in admin settings)

Quick Start ​

1. Get Widget Token ​

  1. Log in to your dashboard
  2. Open Messaging → Widget Playground
  3. Click Generate Widget Token
  4. Copy your tenant ID + the generated token (the Playground can also generate embed code for you)

2. Add Widget Script ​

Paste this near the end of your site's <body> (or wherever you inject scripts). The widget works on any website, regardless of framework:

html
<!DOCTYPE html>
<html>
<head>
  <title>Your Website</title>
</head>
<body>
  <!-- Your website content -->
  
  <!-- Chat Widget Script -->
  <script src="https://app.autoch.at/web-widget.js"></script>
  <script>
    ChatWidget.renderWebWidget({
      tenantId: "your-tenant-id",
      apiUrl: "https://api.yourdomain.com",
      token: "your-widget-token",
      primaryColor: "#3B82F6",
      companyName: "Your Company",
      position: "bottom-right"
    });
  </script>
</body>
</html>

3. Configure Widget ​

Customize the widget appearance:

javascript
ChatWidget.renderWebWidget({
  tenantId: 'your-tenant-id',
  apiUrl: 'https://api.yourdomain.com',
  token: 'your-widget-token',
  
  // Customization
  primaryColor: '#3B82F6',        // Button and header color
  companyName: 'Your Company',     // Display name
  position: 'bottom-right'          // 'bottom-right' or 'bottom-left'
});

Note: The widget is also available as renderWebWidget() directly (without the ChatWidget. prefix) for convenience.

React Integration ​

If using React, import the component directly:

tsx
import { WebWidget } from '@your-package/components/WebWidget';

function App() {
  return (
    <div>
      {/* Your app content */}
      <WebWidget
        tenantId="your-tenant-id"
        apiUrl="https://api.yourdomain.com"
        token="your-widget-token"
        primaryColor="#3B82F6"
        companyName="Your Company"
        position="bottom-right"
      />
    </div>
  );
}

Configuration Options ​

Required Parameters ​

  • tenantId - Your tenant ID
  • apiUrl - API base URL
  • token - Widget authentication token

Optional Parameters ​

  • primaryColor - Widget color (default: #3B82F6)
  • companyName - Company name (default: 'Support')
  • position - Widget position (default: 'bottom-right')

Widget Behavior ​

Session Management ​

  • Each visitor gets a unique session ID
  • Sessions persist across page loads (stored in browser)
  • Conversations are linked to sessions

Message Flow ​

  1. Customer types message in widget
  2. Message sent to the widget chat endpoint (POST /api/widgets/:tenantId/chat)
  3. AI generates a response using your assistant, training context, and safety rules
  4. Response displayed in the widget immediately (standard HTTP request/response)
  5. The dashboard receives live updates via the tenant WebSocket (so your team stays in sync)

Security ​

Token Security ​

  • Widget tokens are tenant-specific and signed.
  • Tokens are designed to be embedded on your website; the safest practice is to use the widget domain allowlist so only your domains can use the token successfully.
  • Tokens expire (default: 30 days). Generate a new token if you rotate secrets or want to invalidate old embeds.

HTTPS Requirement ​

  • Widget requires HTTPS in production
  • WebSocket connections use WSS
  • API endpoints must be HTTPS

Widget Playground ​

The Widget Playground allows you to test and customize your chat widget before embedding it on your website.

Accessing Widget Playground ​

  1. Navigate to Messaging → Widget Playground (or /messaging/playground)
  2. View live preview of your widget
  3. Customize widget settings in real-time
  4. Test widget functionality

Features ​

  • Live Preview: See widget as it will appear on your website
  • Real-Time Customization: Change colors, position, greeting instantly
  • Test Messaging: Send test messages to verify functionality
  • Copy Embed Code: Get widget code ready to paste

Using Widget Playground ​

  1. Customize Appearance: Adjust primary color, position, greeting
  2. Test Widget: Send test messages to verify everything works
  3. Copy Code: Copy the embed code when ready
  4. Deploy: Add code to your website

Tip: Use Widget Playground to test different configurations before deploying to production.

Testing ​

Local Testing ​

  1. Use http://localhost for development
  2. Widget works on localhost
  3. WebSocket connections work locally
  4. Use Widget Playground for testing

Production Testing ​

  1. Deploy widget script to production
  2. Test widget on live website
  3. Verify messages are received
  4. Check AI responses are generated
  5. Use Widget Playground to verify settings

Troubleshooting ​

Widget Not Loading ​

  • Check script is loaded
  • Verify API URL is correct
  • Check browser console for errors
  • Verify token is valid

Messages Not Sending ​

  • Check API endpoint is accessible
  • Verify token authentication
  • Review network requests in browser dev tools
  • Check API logs for errors

No AI Responses ​

  • Verify assistant is configured
  • Check default chat assistant is set
  • Review API logs for AI errors (model/provider config, safety blocks, rate limits)

For more troubleshooting help, see Troubleshooting Guide.

Next Steps ​

autoch.at Documentation

Copyright © 2024 autoch.at