Widget Pro

The heavyweight Vaquill widget. A Next.js 15 + React 19 chat surface with a persistent conversation sidebar, voice mode (TTS + STT), cross-tab sync via BroadcastChannel, gamification (XP and streaks), and multiple citation display modes. Use this when you want a Vaquill-style full experience embedded in your site rather than the minimal proxy widget. Source: github.com/Vaquill-AI/integrations/vaquill-widget-pro.

Need a leaner build? The Embedded Chat Widget ships with about 10 components, US-only focus, streaming SSE, and a single-file embed loader.

What you get

Persistent conversation sidebar with rename, delete, and search
Voice mode - microphone input with VAD plus TTS playback
Cross-tab sync via BroadcastChannel - threads stay consistent across browser tabs
Gamification - XP, streaks, and engagement progress
Citation display modes - cards, tabs, accordion, or pills
TTS provider matrix - OpenAI, ElevenLabs, Edge, Google, StreamElements
Multi-turn chatHistory preserved server-side in a process-local session map
Both embed modes - floating button and iframe
IndexedDB + localStorage fallback for client-side persistence

Status and caveats

The chat-completion plumbing in src/lib/ai/vaquill-client.ts talks to the Vaquill app’s chat backend for both streaming and non-streaming paths. A few legacy endpoints from the upstream RAG-widget fork are stubbed and degrade gracefully: per-message feedback persists only to the local session cache, citation-by-id lookup and file uploads throw a clear “not supported” error, and agent-settings return Vaquill-flavoured defaults.

The server-side session map lives in process memory. On Vercel cold starts or multi-instance deployments it resets. The React UI’s IndexedDB / localStorage is the durable copy, so users do not lose history, but server-side getConversationMessages returns empty for a cold instance until at least one turn is sent.

The AgentCapability enum (fastest-responses, optimal-choice, advanced-reasoning, complex-tasks) maps onto Vaquill’s mode: the first two go to standard, the latter two go to deep.

Prerequisites

Node.js 18+
A Vaquill API key (vq_key_...) from app.vaquill.ai/developer
Optional: an OpenAI API key if you want voice mode (TTS / STT)

Quickstart

Clone and install

git clone https://github.com/Vaquill-AI/integrations.git
cd integrations/vaquill-widget-pro
npm install

Add your keys

cp .env.example .env.local

Edit .env.local and fill in at minimum:

VAQUILL_API_KEY=vq_key_your_key_here
USE_VAQUILL=true

Run the dev server

npm run dev

Open http://localhost:3000.

Configuration

The full list lives in .env.example. The minimum set:

# Required - Vaquill chat backend
VAQUILL_API_KEY=vq_key_...
VAQUILL_PROJECT_ID=your_project_id   # legacy field; safe to ignore
USE_VAQUILL=true
VAQUILL_STREAM=true

# Optional - voice (set both to enable mic + TTS)
OPENAI_API_KEY=sk-...
TTS_PROVIDER=OPENAI   # OPENAI | ELEVENLABS | EDGE | GOOGLE | STREAMELEMENTS

# UI knobs (browser-readable)
NEXT_PUBLIC_THEME=light
NEXT_PUBLIC_WIDGET_FLOATING_BUTTON=true
NEXT_PUBLIC_WIDGET_FLOATING_POSITION=bottom-right
NEXT_PUBLIC_CITATION_DISPLAY_MODE=cards   # cards | tabs | accordion | pills | all

Key flags

Variable	Description
`VAQUILL_API_KEY`	Your Vaquill key. Required.
`USE_VAQUILL`	Must be `true` to route chat to the Vaquill API.
`VAQUILL_STREAM`	`true` to use SSE streaming, `false` for buffered responses.
`TTS_PROVIDER`	Pick a TTS engine. See the matrix below.
`NEXT_PUBLIC_CITATION_DISPLAY_MODE`	Source layout: `cards`, `tabs`, `accordion`, `pills`, or `all`.

TTS providers

Provider	Quality	Speed	Cost
OpenAI	High	Fast	Paid
ElevenLabs	Very High	Medium	Paid
Edge TTS	Good	Fast	Free
Google TTS	Medium	Fast	Free
StreamElements	Medium	Fast	Free

Switch with TTS_PROVIDER=... in .env.local.

Architecture

src/
  app/                   # Next.js App Router
    page.tsx             # main entry
    layout.tsx           # root layout + theme provider
    api/                 # serverless routes
      chat/              # chat / messages / conversations / citations
      tts/               # text-to-speech
      agent/             # agent settings + capabilities
  components/
    ChatContainer.tsx    # main chat surface
    ChatHistory/         # multi-thread sidebar
    gamification/        # XP / streaks / progress
  hooks/                 # voice, persistence, sync, search hooks
  lib/
    ai/                  # Vaquill client + completion plumbing
    audio/               # TTS providers + VAD wrapper
    storage/             # IndexedDB + localStorage fallback
  config/                # centralised config + env parsing
  styles/                # CSS design tokens

Embedding

The widget ships a single-file loader you can drop into any site:

<script>
  window.vaquillConfig = {
    serverUrl: 'https://your-deployment.vercel.app',
    position: 'bottom-right',
    theme: 'light'
  };
</script>
<script src="https://your-deployment.vercel.app/widget.js" defer></script>

The repo’s examples/ folder has drop-in examples for WordPress, Shopify, React, and plain HTML.

Deployment

Vercel (recommended)

npm i -g vercel
vercel
# then set env vars in the Vercel dashboard

When deploying behind a single-instance hobby plan, the in-memory session map survives between requests. For Pro / Enterprise plans with multiple regions, expect the server-side history to be per-instance - the client storage is the source of truth.

Railway

npm i -g @railway/cli
railway login
railway up
railway variables set VAQUILL_API_KEY=vq_key_...

Development commands

npm run dev      # dev server on :3000
npm run build    # production build
npm run start    # run the built bundle
npm run lint     # eslint

Troubleshooting

Voice mode not working

Production must be served over HTTPS (browser mic access requires it).
Grant the browser microphone permission for the site origin.
Verify OPENAI_API_KEY is set and TTS_PROVIDER is configured.
On Safari and iOS, WebM audio is unsupported - the widget falls back to MP4.

Chat returns nothing

Verify VAQUILL_API_KEY and USE_VAQUILL=true.
Open DevTools Network tab and look for the request to /api/inference or /api/inference-stream.
Test the key directly: curl -H "Authorization: Bearer vq_key_..." https://api.vaquill.ai/api/v1/health.

Build errors

rm -rf node_modules .next package-lock.json
npm install
npm run build

History is empty after a redeploy This is the cold-start caveat. The client IndexedDB / localStorage retains threads, but the server session map starts empty. Send one new turn in a thread to repopulate it server-side.

Browser support

Browser	Support
Chrome / Edge	Full
Firefox	Full
Safari / iOS	MP4 audio fallback (WebM unsupported); mic requires HTTPS

Embedded Chat Widget

Leaner Next.js variant pinned to the US.

Docker Widget

Self-host with Docker Compose and embed via script tag.

Statutes API

Search the US Code, CFR, and 50-state statutes.

GitHub

Source code and issue tracker.

Overview

MCP Servers

Chatbots

Widgets

Browser

Automation

What you get

Status and caveats

Prerequisites

Quickstart

Configuration

Key flags

TTS providers

Architecture

Embedding

Deployment

Vercel (recommended)

Railway

Development commands

Troubleshooting

Browser support

Embedded Chat Widget

Docker Widget

Statutes API

GitHub

​What you get

​Status and caveats

​Prerequisites

​Quickstart

​Configuration

​Key flags

​TTS providers

​Architecture

​Embedding

​Deployment

​Vercel (recommended)

​Railway

​Development commands

​Troubleshooting

​Browser support

​Related

Embedded Chat Widget

Docker Widget

Statutes API

GitHub

What you get

Status and caveats

Prerequisites

Quickstart

Configuration

Key flags

TTS providers

Architecture

Embedding

Deployment

Vercel (recommended)

Railway

Development commands

Troubleshooting

Browser support

Related