Skip to main content

​
What is the Chat Widget?

The Support Unicorn Chat Widget is an embeddable, iframe-based chat widget that allows you to add live chat to any website with a simple JavaScript snippet. It provides:
  • Iframe isolation - Widget runs in isolated iframe for security
  • ActionCable - Real-time WebSocket communication
  • Vanilla JavaScript - No framework dependencies for SDK
  • Tailwind CSS - Modern, responsive styling
  • Widget Token Auth - Secure token-based authentication

​
How It Works

  1. SDK loads on your website
  2. Widget iframe is created and embedded
  3. WebSocket connection established via ActionCable
  4. Messages flow bidirectionally in real-time
  5. AI agent responds using your knowledge base

​
Architecture

┌─────────────────────────────────┐
│  Your Website                   │
│  ┌───────────────────────────┐  │
│  │ SDK (sdk.js)             │  │
│  │ - Creates iframe         │  │
│  │ - Handles postMessage    │  │
│  │ - Manages widget state   │  │
│  └───────────────────────────┘  │
│           │                      │
│           ▼                      │
│  ┌───────────────────────────┐  │
│  │ Widget Iframe             │  │
│  │ - Chat UI                 │  │
│  │ - ActionCable connection  │  │
│  │ - Message handling        │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────┐
│  Support Unicorn Server         │
│  - WebSocket endpoint (/cable)  │
│  - Message processing           │
│  - AI agent responses           │
└─────────────────────────────────┘

​
Features

Uses ActionCable WebSockets for instant message delivery without polling.
Widget tokens authenticate both HTTP and WebSocket connections.
Configure colors, position, locale, and welcome messages.
Works with Rails Turbo, Turbolinks, Astro, and standard SPAs.
Identify users and set custom attributes for better context.

​
Routes

RouteMethodDescription
/sdk.jsGETSDK JavaScript file
/widgetGETWidget HTML interface
/widget.jsGETWidget JavaScript
/cableWebSocketActionCable WebSocket endpoint

​
Next Steps

Installation Guide

Learn how to embed the widget on your website

Configuration

Customize widget appearance and behavior

JavaScript API

Programmatically control the widget