Smart Agents Advanced

This page covers the behaviours you need to know once the snippet is in place: where Smart Agents is rendered, how dialogue variables travel, how a conversation is persisted, and how to read initialization errors.

Rendering target

Smart Agents is not injected where the script tag sits. It is rendered through a portal into a target element resolved at init() time:

If an element whose id matches containerId exists in the page, Smart Agents is rendered inside that element.
Otherwise, Smart Agents is appended to <body>.

containerId defaults to st-smartbot. Which means:

Your page contains...	Result
nothing	Floating mode: Smart Agents is appended to `<body>` and positioned by its CSS
`<div id="st-smartbot"></div>`	Contained mode: Smart Agents is rendered inside that block
`<div id="my-bot"></div>` + `containerId: 'my-bot'`	Contained mode, in your own element

<!-- Contained mode: Smart Agents fills this block instead of floating -->
<div id="st-smartbot" style="width: 400px; height: 600px"></div>

caution

The target element must already be in the DOM when init() is called. A containerId pointing to an element that is created later (or never) silently falls back to <body>, which usually looks like "Smart Agents ignored my container".

info

In contained mode, sizing and positioning are up to your page: the container is your layout, Smart Agents fills it. Combine it with ui.display.alwaysOpen: true to get a permanently expanded conversation panel rather than a bubble to click.

Dialogue variables

Variables are custom values your page shares with the dialogue, so the bot can greet a visitor by name, branch on a contract type, or skip a question it already knows the answer to.

Setting variables

Variables can be provided at initialization:

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'en',
      variables: {
        userName: 'John',
        isVIP: true,
        contractCount: 3,
      },
    });
  });
</script>

...and updated at any time afterwards:

<script type="text/javascript">
  window.stSmartBot.updateVariables({
    isVIP: false,
    cartAmount: 129.9,
  });
</script>

Behaviours to know

Behaviour	Detail
Accepted types	`string`, `number` and `boolean` only. Nested objects and arrays are rejected by the validator.
Conversion to strings	Values are converted to strings before being stored. `true` becomes `"true"`, `3` becomes `"3"`. `getVariables()` therefore always returns strings.
Merge, not replace	`updateVariables()` merges the keys you pass into the existing set. Keys you do not mention keep their previous value, and there is no way to delete a key.
Sent on every call	The current variables are attached to every request made to the dialogue API. An `updateVariables()` call is taken into account from the next visitor message.

<script type="text/javascript">
  window.stSmartBot.updateVariables({ isVIP: true });
  window.stSmartBot.getVariables();
  // → { isVIP: "true" }  (string, not boolean)
</script>

Conversation session and persistence

Each conversation is tied to a session identifier generated by Smart Agents.

Default mode: the identifier is stored in the browser localStorage under the smartBotSessionId key. The visitor finds their conversation again after a page reload or a navigation, and the key is kept until the browser storage is cleared.
Ephemeral mode (ui.display.isEphemeralConversation: true): the identifier is only kept in memory, so nothing is written to localStorage. Closing Smart Agents regenerates the identifier and clears the dialogue on screen, so reopening it starts a brand new conversation.

info

Ephemeral mode is ignored when ui.display.alwaysOpen is true: there is no real close in that mode, so the conversation is never reset.

caution

Mention the smartBotSessionId entry in your cookie and local storage policy. It carries no personal data, but it is written on the visitor's device as soon as Smart Agents starts a conversation.

Targeting a bot version

Two different settings decide what the visitor gets, and they are often confused:

Setting	What it selects
The script URL (`public/` segment or not)	The front-end build of Smart Agents that is loaded, as described in the snippet page.
The `env` parameter	The published version of the bot the conversation runs against: `production` or `preproduction`.

env is sent to the dialogue API as a request header. It lets you test a bot scenario that is not published yet, while keeping the same integration:

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    e.detail.init({
      botId: 'xxx',
      locale: 'en',
      env: 'preproduction',
    });
  });
</script>

When env is omitted, no version is forced and the dialogue API applies its own default.

caution

Do not ship env: 'preproduction' to your production pages: your visitors would talk to an unvalidated version of the scenario.

Initialization errors

init() validates every parameter before displaying anything. On failure it throws an error prefixed with [Initialization Validator], and Smart Agents stays hidden. The most frequent cases:

Message	Cause
`botId parameter is required`	`botId` was not passed.
`botId parameter should be a string`	`botId` was passed as a number. It is a string, even when it looks numeric.
`locale parameter is required`	`locale` was not passed.
`locale parameter is not a valid locale: "xx"`	The language code cannot be resolved by the browser. Use `en`, `fr`, `en-GB`, ...
`locale parameter must be included in availableLocales`	`availableLocales` was passed without the current `locale` in it.
`availableLocales parameter contains an invalid locale: "xx"`	One of the declared languages is not a valid code.
`env parameter should be one of 'production', 'preproduction'`	`env` received another value, for example `staging` or `prod`.
`variables parameter should be an object of boolean, string or number, X is not a boolean, string or number`	A variable holds an object or an array. Flatten it first.
`ui parameter should be an object of objects, X is not an object`	A `ui` entry was passed as a flat value, for example `ui: { alwaysOpen: true }` instead of `ui: { display: { alwaysOpen: true } }`.

info

These errors are thrown inside your STSmartBotLoaded listener. Wrap the init() call in a try/catch if you want to report them to your own monitoring.

Reserved parameters

init() also accepts three parameters that are reserved for Smart Tribune internal use. They are documented here so they are not mistaken for integration options:

Parameter	Purpose
buildName	Name of the Smart Agents build variant. It drives the `st-smartbot-build-<name>` CSS class and the conditional blocks of a build.
parameterEnv	Overrides the internal environment used to resolve Smart Tribune service URLs. Used for Smart Tribune development environments.
extra	Accepted and validated for consistency with the other Smart Tribune products, but not used by Smart Agents today.

caution

Setting these parameters yourself has no supported effect and may break future upgrades. Leave them out of your snippet unless your Smart Tribune contact asks for them explicitly.

Rendering target​

Dialogue variables​

Setting variables​

Behaviours to know​

Conversation session and persistence​

Targeting a bot version​

Initialization errors​

Reserved parameters​

Rendering target

Dialogue variables

Setting variables

Behaviours to know

Conversation session and persistence

Targeting a bot version

Initialization errors

Reserved parameters