Smart Agents Snippet

info

Smart Agents is the current name of the product formerly called Smart Bot. Both names refer to the same solution. The script, the CSS classes and the JavaScript API keep their historical smartbot / STSmartBot naming: this is expected, and nothing has to be changed in an existing integration.

Integration

The installation of the Smart Agents solution on the customer's site is done by integrating a snippet of javascript code within the desired page.

JS

The JavaScript snippet must be inserted immediately before the closing </body> tag. This is essential: the Smart Tribune script must be loaded as late as possible in the script loading chain to avoid any conflicts with third-party scripts present on the client page.

The client shall be solely responsible for any deviation from this instruction. Smart Tribune cannot be held liable for malfunctions, script conflicts or performance issues resulting from non-compliant integration.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    e.detail.init({
      botId: 'xxx',
      locale: 'en',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

The integration of the code snippet above is sufficient to allow the partial display of Smart Agents within the page. You must also communicate your domain name to your Smart Tribune contact point so that we allow the product to be displayed completely on your environment.

Please note, the link to smartbot.main.js is a demonstration of the product, the smart-tribune folder in the url will be replaced by the one that will be communicated to you. The url changes completely during the transition from pre-production (public) to production. The complete url is communicated by your Smart Tribune contact point in charge of your account.

info

The domains calling on the specified bot must be declared beforehand directly in the bot configuration in Smart Dashboard by your Account Manager.

Validation environment

caution

The path to the smartbot.main.js file evolves according to the environment: public or production. This url differs depending on the environment on which the solution is to be installed at the customer site. It is customary to use PUBLIC for pre-production and to use PRODUCTION for production at the customer site. All this information is communicated by Smart Tribune after the development phase.

PRODUCTION script

<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

PRE-PRODUCTION script

<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/public/smartbot.main.js"
></script>

Variables list

Variable	Type	Condition	Example	Description
botId	string	required	`botId: "xxx"`	Variable specific to each customer, it corresponds to the identifier of the bot to use. This is available in Smart Dashboard, the content administration interface. It will be provided by your Account Manager.
locale	string	required	`locale: "en"`	It allows the customer to specify in which language the solution should be displayed. This only applies to multilingual bots. The value must be a language code the browser can resolve (`en`, `fr`, `en-GB`, ...); an unknown code makes `init()` fail.
availableLocales	string[]	optional	`availableLocales: ["fr","en"]`	List of languages you allow Smart Agents to switch to at runtime. `locale` must be part of this list. See the Multilingual page. Defaults to `[locale]`.
containerId	string	optional	`containerId: "my-bot"`	Identifier of the HTML element in which Smart Agents will be rendered. By default, the value is `st-smartbot`. If no element carries that identifier, Smart Agents is appended to `<body>` instead. See Rendering target.
env	string	optional	`env: "preproduction"`	Which published version of the bot the conversation runs against: `production` or `preproduction`. This is not the same setting as the script URL. See Targeting a bot version.
variables	object	optional	`variables: { key: value }`	Object containing custom variables (string, number or boolean) that will be passed to the dialogue. Values are converted to strings before being sent. See Dialogue variables.
botIntent	string	optional	`botIntent: "welcome"`	Intent played when the conversation starts, instead of the bot default entry point. Useful to open Smart Agents directly on a given step depending on the page.
auth	bool	optional	`auth: true`	Enables or disables the authentication system. When enabled, the visitor must log in before the dialogue is available. The default value is `false`.
ui	object	optional	`ui: { display: {...} }`	User interface parameters (see dedicated section below).

caution

botId and locale are the only two required parameters. Every parameter is validated when init() is called: a missing required parameter or a wrong type throws an error prefixed with [Initialization Validator] in the browser console, and Smart Agents is not displayed. See Initialization errors.

info

extra, parameterEnv and buildName are also accepted by init(). They are reserved for Smart Tribune internal use and should not be set by the integrator. See Reserved parameters.

UI Parameters

The ui parameter allows you to configure the Smart Agents user interface. Every property is optional; only pass the ones you want to change.

ui: {
  display: {
    alwaysOpen: true,
    displayAiGenerationVoteSatisfaction: true,
    displayAiGenerationLoader: true,
    isEphemeralConversation: false,
    header: {
      buttons: 'menu'
    }
  },
  authentication: {
    defaultLoginMethod: "sso",
    account: "my-account",
    SSOMode: "sso_popup",
    SSOPopupUrl: "https://login.example.com/sso"
  }
}

`ui.display`

Property	Type	Default	Description
alwaysOpen	bool	`false`	If `true`, Smart Agents always stays open without the ability to close it. The toggle button and `hide()` no longer remove the conversation from the screen.
displayAiGenerationVoteSatisfaction	bool	`false`	If `true`, displays the satisfaction vote for AI-generated responses.
displayAiGenerationLoader	bool	`true`	Displays the loader shown while an AI answer is being generated. Set it to `false` to hide that indicator.
isEphemeralConversation	bool	`false`	Ephemeral mode. The conversation identifier is kept in memory only, and closing Smart Agents starts a brand new conversation the next time it is opened. Ignored when `alwaysOpen` is `true`. See Conversation session.
header.buttons	string	`list`	How the header actions are laid out: `list` displays them side by side, `menu` groups them in a dropdown menu.

`ui.authentication`

These properties only have an effect when auth: true.

Property	Type	Default	Description
defaultLoginMethod	string	`password`	Login form displayed first. Possible values: `password`, `sso` (full page redirection) or `sso_popup` (dedicated popup window).
account	string	–	Account identifier for authentication. When set, it is forwarded to the SSO provider as the `org` query parameter.
SSOMode	string	`sso`	SSO flow expected when the provider redirects back to your page with `?ssocallback`. Possible values: `sso` or `sso_popup`. It must match the flow the visitor actually started.
SSOPopupUrl	string	Smart Tribune URL	URL opened in the popup window in `sso_popup` mode. `openerOrigin` (and `org` when `account` is set) are appended to it automatically.

Optional functions

Use the `show()` function

The show() function will allow you to open Smart Agents.

From a...	Description
button	Just call the `show()` function on your button.

<button onclick="window.stSmartBot.show()">Open chat</button>

From a...	Description
timer	Place a `setTimeout` in a `<script>` tag after initializing Smart Agents.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'en',
    });
    setTimeout(() => {
      window.stSmartBot.show();
    }, 3000);
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

From a...	Description
scroll	Place a listener after initializing Smart Agents.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'en',
    });
    window.addEventListener(
      'scroll',
      function (e) {
        window.stSmartBot.show();
      },
      false,
    );
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

If you need to use these functions outside the script (on a button for example), you will need to store stSmartBot inside window which is a global variable:

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'en',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Use the `hide()` function

The hide() function will allow you to close Smart Agents.

From a...	Description
button	Just call the `hide()` function on your button.

<button onclick="window.stSmartBot.hide()">Close chat</button>

Use the `read()` function

The read() function will allow you to retrieve the current initialization parameters.

From a...	Description
script	Call the `read()` function to get the configuration.

<script type="text/javascript">
  var config = window.stSmartBot.read();
  console.log(config);
</script>

Use the `updateVariables()` function

The updateVariables() function will allow you to update the variables of the current dialogue.

From a...	Description
script	Call the `updateVariables()` function with an object containing the new values.

<script type="text/javascript">
  window.stSmartBot.updateVariables({
    userName: 'John',
    isVIP: true,
    accountAge: 5,
  });
</script>

Use the `getVariables()` function

The getVariables() function will allow you to retrieve the current dialogue variables.

From a...	Description
script	Call the `getVariables()` function to get the variables.

<script type="text/javascript">
  var variables = window.stSmartBot.getVariables();
  console.log(variables);
</script>

Use the `setLocale()` function

The setLocale() function will allow you to switch Smart Agents to another language at runtime, without reloading the page.

From a...	Description
button	Just call the `setLocale()` function with the target language code.

<button onclick="window.stSmartBot.setLocale('en')">English</button>
<button onclick="window.stSmartBot.setLocale('fr')">Français</button>

caution

The target language must be declared in availableLocales, and calling setLocale() resets the current conversation. See the Multilingual page for the complete behaviour.

Events

Smart Agents emits custom events that you can listen to:

STSmartBotLoaded

Triggered when the Smart Agents script is loaded and ready to be initialized.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    console.log('Smart Agents loaded', e.detail);
  });
</script>

STSmartBotInitialized

Triggered when Smart Agents has been successfully initialized.

<script type="text/javascript">
  window.addEventListener('STSmartBotInitialized', function (e) {
    console.log('Smart Agents initialized', e.detail);
  });
</script>

STSmartBotLocaleChanged

Triggered when the language has actually been changed by setLocale(). Its detail contains the new language code.

<script type="text/javascript">
  window.addEventListener('STSmartBotLocaleChanged', function (e) {
    console.log('Smart Agents language is now', e.detail.locale);
  });
</script>

STSmartBotClickableButtonClicked

Triggered when the visitor clicks a clickable button configured inside Smart Agents. Its detail contains the name of the button, which lets you plug your own behaviour (opening a form, tracking a conversion, ...) on a bot interaction.

<script type="text/javascript">
  window.addEventListener('STSmartBotClickableButtonClicked', function (e) {
    console.log('Button clicked inside Smart Agents:', e.detail);
  });
</script>

info

STSmartBotLoaded is dispatched once per page load, before any init() call. Register your listener before the smartbot.main.js script tag, otherwise the event may already have been dispatched when your listener is attached.

Complete example

Here is a complete integration example with all options:

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'en',
      availableLocales: ['en', 'fr'],
      containerId: 'st-smartbot',
      env: 'production',
      botIntent: 'welcome',
      variables: {
        userName: 'John',
        userType: 'premium',
      },
      auth: true,
      ui: {
        display: {
          alwaysOpen: false,
          displayAiGenerationVoteSatisfaction: true,
          displayAiGenerationLoader: true,
          isEphemeralConversation: false,
          header: {
            buttons: 'list',
          },
        },
        authentication: {
          defaultLoginMethod: 'sso',
          account: 'my-account',
          SSOMode: 'sso',
        },
      },
    });
  });

  window.addEventListener('STSmartBotInitialized', function (e) {
    console.log('Smart Agents ready!');
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Going further

Multilingual — switching languages at runtime.
Advanced — rendering target, dialogue variables, conversation session, bot version targeting and initialization errors.

Integration​

JS​

Validation environment​

PRODUCTION script​

PRE-PRODUCTION script​

Variables list​

UI Parameters​

ui.display​

ui.authentication​

Optional functions​

Use the show() function​

Use the hide() function​

Use the read() function​

Use the updateVariables() function​

Use the getVariables() function​

Use the setLocale() function​

Events​

STSmartBotLoaded​

STSmartBotInitialized​

STSmartBotLocaleChanged​

STSmartBotClickableButtonClicked​

Complete example​

Going further​

Integration

JS

Validation environment

PRODUCTION script

PRE-PRODUCTION script

Variables list

UI Parameters

`ui.display`

`ui.authentication`

Optional functions

Use the `show()` function

Use the `hide()` function

Use the `read()` function

Use the `updateVariables()` function

Use the `getVariables()` function

Use the `setLocale()` function

Events

STSmartBotLoaded

STSmartBotInitialized

STSmartBotLocaleChanged

STSmartBotClickableButtonClicked

Complete example

Going further