Skip to content

Site Agent settings

Everything so far changed what the assistant knows, through versions. How it looks and behaves on your pages is set separately, in the site’s settings, which the first studied publish filled in for you (The Site Agent).

Settings belong to the site, not to a version: a save is live on the next page load, with no new version and no review. An owner or admin changes them in the console or with update_site_settings over MCP.

update_site_settings(tenant, site_id, settings, expected_updated_at="").

  • settings is a JSON merge patch over site.settings as get_site shows it. Name only what changes: an object merges key by key, null puts a key back to its default, and a list (such as voice.languages or assist.tools_off) is replaced whole.
  • Pass the site.updated_at you read as expected_updated_at. If the site changed since, nothing is saved and the call is refused with site_changed; read the site and send the patch again.
KeyDefaultSets
assistant_nameAssistantThe name on the button and in the call; at most 40 characters.
greetingnoneThe assistant’s first words; at most 160 characters. A page can override it (tag options).
avatar.enabledtrueWhether the call shows an animated character.
avatar.charactertaraWhich character; the catalog lists them.
voice.languages["english"]The languages the assistant speaks, as names, such as hindi, spanish or portuguese (Brazilian).
voice.default_languageenglishThe one calls start in; one of voice.languages.
voice.instructionsnonePer language, plain text the assistant follows when it speaks that language, such as the currency to say prices in: {"hindi": "…"}. Each key one of voice.languages; each text at most 500 characters.
colours.accent, .background, .textderivedThe button’s colours, each #rrggbb.
positionbottom-rightbottom-right or bottom-left.
show_on.include["/**"]Path globs where the button shows.
show_on.exclude[]Path globs where it never shows; these always win.
hoursnone (always){timezone, weekly: [{day, open, close}]}, day mon to sun, times HH:MM. Outside them the button is hidden. timezone defaults to Asia/Kolkata.
human_contactfrom the study{phone, email, whatsapp, url}: how the assistant tells a visitor to reach a person.
assistall onWhat the assistant may do; below.

The first publish of a studied version sets assistant_name, greeting, colours and position to what the study chose, unless a person has saved settings by then. Any save counts, of any key, and keeps the study’s choices out of every one of those keys. No later study changes them.

Path globs match the path only, not the query: ** matches across /, * within one segment, ? one character, and a trailing /** also matches the folder itself.

Each character speaks in its own voice, so the voice is not a setting: it is set from avatar.character, whatever the patch says. With the avatar off the site keeps the voice it had. A character none of whose voices speaks every site language is refused.

Javier is the character who speaks Spanish and Brazilian Portuguese, each beside English, so a site with either language starts with him.

Each switch is on unless turned off.

SwitchTurns off
formsFilling forms the study declared, and sending one after the visitor confirms.
search_boxTyping into the site’s search box.
account_pagesThe button on visitors’ own pages, where the assistant only points at a section.
cart_pagesThe button on cart, checkout and payment pages, where the assistant only looks.
cart_editsChanging a cart line’s quantity or removing it.
couponApplying a code the visitor says.
switchersSwitching language, region or currency.
bookingsFilling a booking flow up to its confirm step.
ratingSaying an item’s live rating.
site_toolsEvery site tool.
open_actionsSite tools that change something on the page reversibly.

assist.tools_off lists site tools turned off one by one.

Nothing is saved when a patch is refused:

CodeMeans
language_unsupportedA language the assistant cannot speak.
character_language_unsupportedNo voice of that character speaks every site language.
accent_low_contrastThe accent colour is hidden by the background; the message names one to use.
site_archivedThe site is archived.
site_changedThe site changed since expected_updated_at.

A page can set a few options for itself on the snippet’s tag:

AttributeDoes
data-language="hindi"The language a call on this page starts in, as a language name, not a code. It must be one of the site’s languages, in any case; any other value is ignored.
data-greeting="…"The assistant’s first words on this page. Plain text of at most 280 characters; tags and invisible characters are removed, and a longer value is ignored.
data-hide="1"Hide the button on this page. true, yes and an empty value also count.

A page your site builds without a full reload can set the same options in script, before or after site.js loads:

<script>
window.VoqalizeSite = { greeting: "Looking for a gift? I can help.", language: "english" };
// after site.js has loaded:
// window.VoqalizeSite.configure({ hide: true });
</script>

The keys are hide, greeting, language and pageType. pageType names one of the site’s page types (letters, digits, _ and -) when the address alone does not say which kind of page this is. A value set in code beats the tag, a later value beats an earlier one, and an invalid value falls through to the tag and then to the site’s settings. Reassigning window.VoqalizeSite and calling configure both take effect at once.

The button shows where show_on allows and inside hours. On top of that:

  • Your visitors’ own pages (account, orders, addresses and the like): the button shows unless assist.account_pages is off. The assistant reads nothing there and can only point at a section and help the visitor leave.
  • Cart, checkout and payment pages: the button shows unless assist.cart_pages is off. The assistant only looks; on the cart page it reads the cart’s lines.
  • Pages that change state by being opened (sign-out, account deletion, emptying the cart): never.

Your own show_on exclusions always win.

Pause in the console turns the site’s live key off: the button no longer shows on your pages and no visitor call starts, while the snippet stays where it is. Previews still work, and studies still run. Resume turns it back on. There is no MCP tool for either.

  • Goals: what the assistant leads visitors towards. A patch over MCP never changes them.
  • Notes: one-line corrections to what the assistant knows; see Notes in the console.
  • The robots agreement: whether the reader may read pages robots.txt asks crawlers to skip (robots.txt).
  • Pause and resume, above, and renaming the site.