Appearance
A deployment's look and words, stored once and used on every site that shows it, in every language you write them in.
A deployment's appearance is how its widget looks and behaves: theme and colours, the launcher, the teaser, the panel's header, and the pages it shows on. It is stored with the deployment and reaches every site at once, with no change to the tag.
Only what you set is stored. Anything you leave out takes the widget's own default, so a better default of ours reaches every deployment that didn't choose otherwise.
What wins: the tag's attributes win over the appearance, and TalkWidget('update', …) wins over both.
It's public
Any site the key allows can read the appearance (the widget needs it), so nothing secret belongs in it.
How to set it
The dashboard's Deployments page makes deployments and their tags. Editing the look and words there is coming; until then, use the API or the MCP server.
- The API:
GETandPUT /v1/keys/{id}/appearancewith a secret key (below). - The MCP server: ask your assistant. Its
set_widget_lookchanges the look andset_widget_textswrites the words in one language at a time, translating them for you (MCP server tools). - The tag's attributes, for one site.
Read it
/v1/keys/{id}/appearance{id} is the deployment's id (key_…). Answers { "key_id": "key_…", "appearance": { … } }, the appearance exactly as stored ({} for none).
Replace it
/v1/keys/{id}/appearanceSend { "appearance": { … } }: the whole appearance, which replaces what was there. null or {} goes back to the defaults. Answers the same as GET.
curl -X PUT https://talk.madein10.com/v1/keys/key_…/appearance \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "appearance": { "theme": "auto", "launcher": { "style": "card", "position": "bottom-left" } } }'- Which deployments: a publishable key of your secret key's env (a live key the live deployments, a test key the test ones). A secret key's id, a revoked deployment, or another organization's or env's answers 404.
- A bad appearance is 400
invalid_field, naming the field (appearance.colors.accent must be a colour like #1e6fd9), and nothing changes.
The shape
Every key and part is optional. The colours shown are our defaults: the product's Aqua blue on soft neutrals.
{
"theme": "light", // light | dark | auto (the visitor's system setting); default light
"colors": { "accent": "#1e6fd9", "on_accent": "#f8fbff", "ink": "#161a21", "paper": "#f7f8fa" },
"dark_colors": { "accent": "#4aa3ff", "on_accent": "#0e1218", "ink": "#eef1f6", "paper": "#15181e" },
"launcher": {
"style": "face", // face | face_label | card | pill | icon | tab
"mobile_style": "face", // the same, on phones; default the same as style, but card → face
"label": { "en": "Talk to us", "fa": "با ما صحبت کنید" }, // face_label, pill and tab show it; 24 characters
"position": "bottom-right", // bottom-right | bottom-left
"offset_x": 20, "offset_y": 20, // px from the window's edges, 0 to 160
"icon": { "kind": "builtin", "name": "chat" } // pill, icon and tab show it
},
"teaser": {
"enabled": true,
"messages": { "en": ["Hi, I'm here if you need anything", "Questions about pricing? Ask me."], "fa": ["…"] },
"delay_seconds": 4, // 0 to 120, after the page loads
"rotate_seconds": 6, // 3 to 60, between messages
"frequency": "every_visit", // every_visit | once_per_session | once_per_day
"on_mobile": true,
"pages": { "show_on": ["/pricing*"], "hide_on": ["/checkout*"] }
},
"panel": { "title": { "en": "Alex at Nordlicht" }, "subtitle": { "en": "Speaks your language" } },
"pages": { "hide_on": ["/admin/*"] } // where the whole widget shows
}At most 48 KB of JSON; unknown fields are refused.
Launcher styles
| Style | What it is |
|---|---|
face | The character's face in a circle (the default) |
face_label | The face and the label |
card | A small video card: the idle loop, the name and a Talk button |
pill | An icon and the label, on the accent colour |
icon | A round icon button, on the accent colour |
tab | A slim vertical tab on the window's edge that slides out on hover; vertically centred, so offset_x doesn't apply |
The panel is the same for all of them. mobile_style applies at 640 px wide and below, and on short touch screens. The icon of pill, icon and tab is one of ours, the character's face, or your own: see Icons.
Colours
#rrggbb, stored lower-case. colors is the light theme's palette, dark_colors the dark one's (used by dark and auto). Each has four colours: accent (the launcher's ring, buttons, the AI badge), on_accent (text on the accent), ink (text) and paper (backgrounds). With your own accent or paper, the widget mixes its tint from them.
Texts and languages
The label, the teaser messages, and the panel's title and subtitle are set per language, by two-letter code (en, fa), at most 16 languages each.
| Text | Limit |
|---|---|
| Teaser messages | 1 to 5 per language, 140 characters each |
| Launcher label | 24 characters |
| Panel title | 40 characters (the character's name when unset) |
| Panel subtitle | 80 characters |
Texts are plain text on one line: runs of spaces and line breaks become one space, control characters aren't allowed, and an empty one is dropped.
Which language shows: the widget's language is the tag's data-language, else the page's <html lang>, else the visitor's browser's. A text is yours in that language, else our own words in it, else your English one, else any of yours. Persian, Arabic, Hebrew and Urdu turn the widget right to left.
How often the teaser comes back
frequency | What it means |
|---|---|
every_visit | On each page load until the visitor dismisses it; then not again in that browser session |
once_per_session | Once a browser session |
once_per_day | Once in 24 hours; a dismissal lasts as long |
It's remembered in the visitor's browser, per deployment. Opening the panel counts as seen. The teaser never shows while the panel is open, and on phones only if on_mobile allows it.
Pages
pages decides where the whole widget shows; teaser.pages where the teaser pops up. Both take show_on (if set, only those pages) and hide_on (never those; it wins over show_on).
- Patterns match the path,
*for anything:/pricing,/blog/*. With a?the query is matched too:/*?utm_source=ads*. A trailing slash doesn't matter. - At most 20 patterns each, 200 characters, starting with
/(or*alone), in visible ASCII without quotes, angle brackets, backslashes, backticks or#. - Checked again when your site changes pages without reloading.