DeskAdmin and settings

Installing the web widget

Updated 2026-11-12

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; 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
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.

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:
JavaScript
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.