Introduction

Wireface Chat is an AI chatbot you run on your own server and add to any website with one line of HTML. The agent appears as an animated face (a Wireface face) that talks: its lips move with its voice, and it shows moods as it replies. Visitors can type, talk, send photos and, if they agree, turn on their camera.

You bring the AI. Connect an Anthropic, OpenAI, Google Gemini or ElevenLabs key in the admin panel, pick models and voices from the lists that appear, and write the agent's instructions. Everything runs through your server: keys, transcripts and tools never touch the visitor's browser.

What you get

• A chat widget in four layouts (a panel, a side drawer, a floating face, or inline in your page), with a launcher button or tab you can restyle, or none.
• Text and voice in one conversation. Visitors can switch between typing and talking at any time. See Voice.
• Vision: photo uploads and an opt-in webcam. See Vision and webcam.
• Tools: tools in your page (add to cart, open a product), and HTTP tools and MCP servers on the server.
• A knowledge base from your web pages, sitemaps and files, with sources shown under replies. See Knowledge base.
• People when needed: the agent (or the visitor) can hand the chat to your team, who reply from the admin panel. See Human handoff.
• Leads, ratings, webhooks and a REST API to connect it to the rest of your business.
• An admin panel for bots, providers, conversations, leads, team members, API tokens and webhooks.

How it fits together

Your web page
  widget.js            loaded from your chat server; draws the launcher in a shadow root
  iframe /frame/pk_... the chat window: messages, the face, microphone and camera
     |
     |  WebSocket /v1/widget/ws  (JSON messages, plus binary audio and camera frames)
     v
Wireface Chat server   one Node.js process (or one Docker container)
  - conversations, the agent loop, tools, knowledge search
  - SQLite database and uploaded files in DATA_DIR
  - calls Anthropic, OpenAI, Gemini and ElevenLabs with your keys
  - serves /admin (admin panel), /docs (these docs) and /api/v1 (REST API)

A few things follow from this design:

• The chat window is an iframe on your chat server. Your site's CSS can't break it, and it can't read your page. widget.js and the window talk over a private MessageChannel, and your code talks to both through the JavaScript API.
• The server relays all audio. The browser speaks one protocol whichever voice provider is behind it, and no provider key or token ever reaches the browser.
• Bots are versioned. You edit a draft and publish it; conversations keep the version they started with. See Concepts.
• It is one process with one database. Back up one directory and you have everything. See Backups.

What the server serves

Path	What
/widget.js	The loader your pages include (always the server's current version)
/widget@x.y.z.js	A pinned version; /manifest.json lists the current version and its SRI hash
/frame/<public id>	The chat window (the iframe widget.js opens)
/embed/<public id>	The chat window on its own, for a plain iframe without JavaScript
/core/<hash>/	The face engine
GET /v1/widget/bots/<public id>/config	A bot's public settings, fetched by widget.js
/v1/widget/ws	The chat window's WebSocket
POST /v1/widget/uploads	Image uploads from the chat window
/api/v1/...	The REST API (/api/v1/live is the admin panel's live WebSocket)
/api/docs, /api/openapi.json	The REST API's reference and OpenAPI spec
/admin/	The admin panel
/docs/	These docs
/healthz	A health check: { "ok": true, "version": "...", "uptime": ... }

What you need

• A machine that runs Docker (or Node.js 24 with pnpm).
• An API key from at least one of Anthropic, OpenAI or Google Gemini for the agent's replies. Voice needs an OpenAI, Gemini or ElevenLabs key (the same OpenAI or Gemini key will do). See Providers.
• HTTPS in front of the server for anything public: browsers only allow the microphone and camera on secure pages.

Next: Quick start.