# Widgets and installation

> The six surfaces, the script tag, allowed domains, and what to check when nothing appears.

Source: https://welcomeai.dev/docs/widgets
Category: Widgets
Updated: 2026-09-09

---
## Choosing a surface

Six of them. What separates one from the next is *where it appears on your page and how it opens*,
so pick by that rather than by what it is called.

- **Floating chat.** A bubble in the corner that opens a panel. The default for a marketing site.
- **Inline chat.** The same panel, always open, inside an element you choose. For a help page.
- **Spotlight.** One large question box, the page's own. The answer arrives in the same card, and
  the quick actions sit under it as pills.
- **Inline input.** A field the width of whatever holds it. Its quick actions open *underneath* as a
  panel with an icon and a line of description each, filtered as the visitor types.
- **Docs assistant.** A drawer that arrives from the right edge over a documentation page, with
  citations that deep-link into it.
- **Full page.** A page at your own address, for when you have nowhere to embed. Its header carries
  your logo and your workspace name.

Floating chat and Inline chat are on every plan. The other four need Pro.

Spotlight and Inline input answer one question at a time and start again, which is why they are the
two that do not offer a lead form asked across several turns.

## Spotlight and Inline input

Both are set up on the widget's **Design** tab, and both offer the same two things:

- **A rotating placeholder.** Up to eight phrases; each types itself out, holds, then clears. Off
  until you add a phrase. A visitor whose system asks for reduced motion sees the first phrase
  standing still instead, which is not a setting either of you can override.
- **Quick actions**, edited on the **Behavior** tab. Each one takes a label, a question to send, and
  optionally a description and an icon -- one of twelve, or a PNG, JPG or SVG of your own. Inline
  input draws all three; Spotlight draws pills, and a pill is a label, so the description and the
  icon are not used there.

Spotlight has one more: a **soft gradient wash** behind the card, mixed from your Primary colour and
a Glow colour. Inline input renders on a flat surface, so it reads neither.

## Language

Two languages, and two different questions.

**The interface** is set on the Behavior tab: **English**, **Spanish**, or **Auto-detect**, which
follows the visitor's own browser and uses Spanish when it is set to Spanish and English for anything
else. This is the widget's own words -- the placeholder, the send and close buttons, the typing line,
the lead form's labels, the Powered by line. If your embed names a language itself with
`data-locale="es"`, that wins over all three: a Spanish page inside an otherwise English site should
stay Spanish whatever the reader's laptop says.

**The answers** are not this setting. The assistant is told to reply in the language the visitor
writes in, so a question in Spanish gets an answer in Spanish even on a widget whose interface is
English, and the follow-up suggestions come back in that language too. You do not have to choose a
language for your customers; you choose one for the buttons around them.

## Installing

Copy the script tag from the widget's Install tab and paste it just before the closing body tag.

```html
<script src="https://cdn.welcomeai.dev/widget.js" data-widget="wg_xxxxxxxxxxxx" async></script>
```

Nothing else is required. The widget loads asynchronously and does not block your page.

## Allowed domains

A widget only answers on the domains you list. Add every host it will run on, including staging.
`*.example.com` covers subdomains. A request from anywhere else is refused, which is what stops
someone from lifting your key and running your assistant on their own site.

## Nothing appears

Check in this order:

1. **Is the widget published?** A draft widget does not load.
2. **Is the domain allowed?** The browser console shows a refusal with the origin we saw.
3. **Is the script actually on the page?** View source and search for `data-widget`.
4. **Is something blocking it?** A strict content security policy needs `cdn.welcomeai.dev` allowed.

The widget page shows the domains where the widget has been seen and when, which usually settles the
question faster than the console does.