For developers
Widget attributes
Every attribute of <tolkly-chat>, the --tolkly-* colour properties, and <tolkly-search>.
<tolkly-chat> needs only two attributes: endpoint and project. Everything else comes from the
server (GET /v1/projects/<project>/widget): the project's name, greeting, theme and who answers.
The project's owner sets these in the app, in the project's Widget section, with a live
preview. Use the attributes below when a site wants its own.
Attributes
| Attribute | What it does |
|---|---|
endpoint | The Tolkly server's origin, https://api.tolkly.io. Without it, the origin widget.js was loaded from. |
project | The project's id. Required. |
name | Sets the chat's title and the site's name in its lines. Without it, the project's name. |
greeting | Replaces the chat's opening line with the site's own. |
handoff | The site's own support link. The chat offers it when the project has no operators in Tolkly. Only https:, http:, tg: and mailto: links work; others are ignored. A t.me link gets the order number from the question as its start parameter. |
teaser | A one-line hint over the closed chat, in place of the one set in «Widget». Shown once per browser session. It goes away when the visitor hides it or opens the chat. |
open | The chat starts open, without taking the page's focus. |
position | left or right: the corner of the button and the window, in place of the one set in «Widget» (Placement). |
inline | Puts the open chat into the page, sized by its container: no button, no close. Give the container a height. |
launcher | none: no button and no hint in the corner. The chat still opens there, from your own control with open(); show unread replies from tolkly:unread. |
lang | The chat's language, instead of <html lang> (Language). |
theme | Light or dark (Light and dark): site follows the page, system the visitor's system, light and dark fix one. Without it, the choice in «Widget», site by default. |
send-icon | The send button's icon: arrow (up), plane or forward (right), in place of the one picked in «Widget». Any other value draws the arrow. |
collapse | How many statements of an answer show before the rest folds. 3 by default; 0 never folds. |
data-identity | A token your site's server signed for the visitor (Signed visitor identity). |
nonce | The style nonce from your Content-Security-Policy. Needed for browsers without constructed stylesheets (Safari before 16.4). Without it, the widget takes the nonce of the page's first <script nonce> (CSP). |
preview | Draws the chat as visitors see it, but sends nothing and restores no saved conversation. The app's widget preview uses it. Not for a live site. |
For name, greeting, teaser, theme, send-icon and position, the attribute on the tag
wins over the server. Whether the AI answers or only people do can't be set on the tag. Only the
project's switch decides that.
The element reacts at once when lang, name, data-identity or theme change. Put the other
attributes in the markup.
How the chat gets the visitor to a person:
handoffis set and the project has no operators in Tolkly: through the link.- The project has operators: the chat hands the conversation to them.
- Neither: the chat asks the visitor for a contact (of the kinds the project allows), so your team can write back.
Colours and font
The theme is a set of CSS custom properties on the element. The server sends the ones it read from
the site, with the owner's corrections from the app. Set your own in the tag's style attribute:
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project"
style="--tolkly-accent: #0b7a53; --tolkly-radius: 8px"></tolkly-chat>The server's colours sit inside the widget, below anything your page sets: a value in the tag's
style and a rule in your stylesheet (tolkly-chat { --tolkly-accent: … }) both win, with no
!important.
| Property | Default (light) | Used for |
|---|---|---|
--tolkly-accent | #4f46e5 | the button, the visitor's messages, pressed controls |
--tolkly-accent-fg | #ffffff | text on the accent |
--tolkly-accent-text | the accent | accent-coloured text and outlines on the background: source marks, focus |
--tolkly-bg | #ffffff | the window's background |
--tolkly-fg | #16181d | text |
--tolkly-muted | #667085 | secondary text |
--tolkly-border | #e4e7ec | borders |
--tolkly-surface | #f6f7f9 | cards, code, quoted sources |
--tolkly-radius | 12px | the window's corners (in the app: «Corners»). Small controls take it, up to 12px. The reply field wraps its buttons with 5px more. |
--tolkly-font | system-ui, … | the text font; a family the page already loads |
--tolkly-mono | ui-monospace, … | code |
A value you set applies in both schemes. To set one for a scheme only, select it by
data-scheme (Light and dark).
Light and dark
The chat has a light and a dark palette. The server sends both: the colours read from your site,
and its dark (or light) mode when the site has one, read from prefers-color-scheme rules and
.dark-style classes. When the site has none, the other palette is made from your colours: the
brand keeps its hue and stays readable on the new background.
Which one shows is the theme attribute, else the choice in «Widget» («Light or dark»):
| Value | The chat |
|---|---|
site (default) | looks like the page under it: its background colour, then a dark or light class or data-theme, data-bs-theme, data-color-mode on <html> or <body>, then the page's color-scheme. It follows your site's own switch as it happens. |
system | follows the visitor's system setting. |
light, dark | always that palette. |
The chat puts the palette it shows on the tag as data-scheme="light" or data-scheme="dark".
Your own switch can drive the chat by setting the attribute:
document.querySelector('tolkly-chat').setAttribute('theme', isDark ? 'dark' : 'light')To give a scheme colours of your own, select it in your stylesheet:
tolkly-chat[data-scheme="dark"] { --tolkly-bg: #0f172a; --tolkly-accent: #60a5fa; }Placement
The chat sits in the bottom right corner, 20 px from the page's edges. The project's owner can move it in the app: Widget → «Position» sets the corner and the gaps from the side and the bottom, 0 to 400 px. Every page gets this setting from the server. A page can set its own on the tag:
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project" position="left"
style="--tolkly-offset-x: 24px; --tolkly-offset-y: 96px"></tolkly-chat>| Property | Default | What it moves |
|---|---|---|
--tolkly-offset-x | 20px | the button and the window from the page's side (the right one, or the left with position="left") |
--tolkly-offset-y | 20px | the button from the page's bottom; the window and the hint stay 68 px above it |
Unlike the colours, the offsets work from your stylesheet too. There they win over the owner's
setting without !important. For example, if your phone layout has a tab bar at the bottom, you
can lift the chat on phones only:
@media (max-width: 600px) {
tolkly-chat { --tolkly-offset-y: 80px; }
}Any CSS length works, calc(env(safe-area-inset-bottom) + 64px) included. On a screen narrower
than 600 px, the open chat fills the whole screen, so the offsets move only the button there.
Until the project's settings arrive (at most 1.5 s), the button is not drawn. Otherwise it would appear in the default corner and then jump to the owner's.
<tolkly-search>
The same script adds a search box over a project's pages, for docs sites:
<tolkly-search endpoint="https://api.tolkly.io" project="your-project"></tolkly-search>The element draws a «Search docs ⌘K» button where it stands.
- It opens on that button or on Cmd+K (Ctrl+K) anywhere on the page. Escape closes it.
- Pages are listed as you type. Enter asks for an answer with its sources.
- It takes
endpoint,project,lang,themeand the--tolkly-*properties. It reads no settings from the server: withoutthemeit follows the page, in the widget's own colours. open(question?)opens it; with a question, it asks it at once.close()closes it.- Its code loads only on a page that has the element.