# Installing the web widget

The web widget is how customers reach you on your website. Admins set it up in **Settings › Channels › Chat widget**, which has seven tabs: Appearance, Conversation, Forms, Install, Test, Who answers and Activity. Only admins and owners see Channels.

## Install

Copy the code from the **Install** tab and paste it before `</body>` on every page of your website:

```html
<script src="https://<your-service>/ailo.js" data-ailo-tenant="<site ID>" async></script>
```

Attributes you can add to that line:

| Attribute | Description |
| --- | --- |
| `data-ailo-tenant` | Required; already filled in the install code |
| `data-ailo-locale` | Sets the widget's language; values under [Languages](#languages); a language fixed under Conversation takes precedence |
| `data-ailo-launcher` | `hidden` hides the default launcher button so you can use your own; see [Opening it with your own button](#opening-it-with-your-own-button) |
| `data-ailo-theme` | `light`, `dark` or `auto` (follows the visitor's system); a theme chosen under Appearance takes precedence |

If the code is on a page twice, only the first one counts.

### Check installation and allowed websites

**Check installation** lists the websites that loaded the widget in the last 7 days, each marked Allowed or Blocked; a blocked one can be added to the allowed websites right there.

**Allowed websites** is the list of websites that can use the widget:

- When the list is empty, any website can load the widget.
- Once you add websites, only an exact match of protocol, domain and port works; on any other website the widget does not show.
- Subdomains are added one by one, without paths, up to 50.

## Appearance

| Setting | Description |
| --- | --- |
| Brand color | Six presets (Cobalt by default) or a custom color; you are warned when button text contrast is too low |
| Logo | PNG, JPEG or WebP, up to 256 KB |
| Launcher position | Bottom right (default) or bottom left |
| Launcher icon | Square PNG or SVG, up to 50 KB, optionally a separate one for dark theme; placed Centered (default) or Fill |
| Theme | Light, Dark or Match visitor's system |
| Welcome message and default language | One welcome message per language; the default language is used when the install code sets none |
| Voice input | The customer speaks, checks the text, then sends; off by default |
| AI assistant line | While Ailo serves, shows "Ailo is our team's AI assistant" in the widget header; hidden by default |

## Conversation

| Setting | Default |
| --- | --- |
| Customers see when we're typing | On |
| Also while Orbit drafts | On |
| Customers type to start a new conversation | On |
| Customers can end the conversation | On |
| System text and chat language | Follow the customer, or fix one language |

## Forms

The **post-chat form** asks customers to rate the conversation when it ends:

- The customer picks one of three: Helpful, Okay or Not helpful, and can then answer your follow-up questions.
- The rating card appears immediately, or after 5, 10, 30 or 60 seconds, 10 by default; if the customer is typing it waits until they stop.
- The rating card stays available for 1–30 days, 7 by default.

A pre-chat form can also be set up here, but the widget does not show pre-chat forms yet, so customers do not see it.

## Test

The **Test** tab is for admins. You play the visitor in the real widget while serving the same conversation in Desk; **New visitor** starts over, and you can switch between phone and desktop width. Test conversations are visible only to you and stay out of stats; the AI allowance for testing is counted per organization per day, separately from live service.

## Who answers

When your organization is connected to a Harness organization, choose in **Who answers** which Ailo serves this channel, or "No Ailo for now" to have the team answer. See [Desk overview](overview.md#where-ailo-comes-from).

## Activity

**Activity** lists the setting changes on this channel: who changed what, and when. The full log is in **Settings › Activity log**.

## Languages

The widget speaks 10 languages: 简体中文, English, ไทย, Tiếng Việt, Bahasa Indonesia, Bahasa Melayu, Filipino, မြန်မာ, ខ្មែរ and नेपाली. Their values in the install code are `zh`, `en`, `th`, `vi`, `id`, `ms`, `fil`, `my`, `km` and `ne`.

When the site fixes a language under Conversation, the widget always uses it. Otherwise it picks in this order: `data-ailo-locale` in the install code, the visitor's browser language, the site's default language, and English when none of those apply.

## Opening it with your own button

With the default launcher hidden, use `ailo('open')` and `ailo('close')` to open and close the widget. Add a small stub first so calls made before the widget loads are queued and run once it is ready:

```html
<script>
  if (typeof window.ailo !== 'function')
    window.ailo = (...args) => {
      window.ailo.q = window.ailo.q || [];
      window.ailo.q.push(args);
    };
</script>
<script src="https://<your-service>/ailo.js" data-ailo-tenant="<site ID>" data-ailo-launcher="hidden" async></script>
<button type="button" onclick="ailo('open')">Contact support</button>
```

Several calls in a row count as the last one. On a website that is not allowed there is no widget, and the calls do nothing.

## Tell the widget who the player is

When a player signs in to your website, you can let the widget know who they are; the customer profile in Desk then shows the verified player ID.

1. An admin creates a site key under "Site keys" in **Settings › My keys**. The key is shown only once. Up to two can be active at a time, for rotation.
2. Your website's back end signs a short-lived token (a JWT) for the signed-in player:
   - the header has `alg: HS256` and `kid` set to the site key's Key ID, and it is signed with that key's secret;
   - the payload has exactly `tenant` (the site ID), `player_id`, `iat`, `exp` and `jti`; any extra or missing field is refused;
   - `player_id` is 1–128 letters, digits or `_.:-`, so no e-mail addresses or spaces; `jti` is 8–128 of the same characters and each token can be used once;
   - it is valid for at most 600 seconds.
3. On the page, register a function that fetches a token:

```js
ailo('identify', {
  // Ask your own back end for a fresh token every time; return null when nobody is signed in.
  getToken: () =>
    fetch('/my-site/ailo-token', { method: 'POST' })
      .then((r) => (r.ok ? r.json() : null))
      .then((b) => b?.token ?? null),
});

// When the player signs out, or a different player uses this device:
ailo('reset');
```

The widget sends the token when it first starts a conversation and renews it before it expires. If a token is refused, the chat still opens and the visitor is treated as not signed in; the customer's side never shows verification status.

::: note
Tokens carry only the player ID for now. Details such as VIP level, currency or nickname cannot be passed to the widget through the token yet.
:::

::: warning
Keep the site key on your server only. Never put it in page code.
:::

## What else customers can do

- **Send images and PDFs**: JPG, PNG or PDF, up to 10 MB, visible only to your team.
- **End the conversation themselves**: **End conversation** is in **⋯** in the widget header; you can turn this off under Conversation.
- **Open links** in replies.

A banned visitor sees only "Chat isn't available right now." and cannot send messages.

## Related

- [Desk overview](overview.md)
- [Keys, bans and the activity log](security.md)
