Configuration

🧩 Overview

Bot configuration help us to allow the user to customize the bot corresponding to the width, name, avatar and logo of the bot. Bot configuration screen is designed to simplify the process of creating and configuring bots tailored to your specific business needs. Here, you can create, edit, set default, and delete your custom bots.

🛠️ Step 1 Create a Configuration

Go to the Agent, select the Controls menu from the left navigation panel, and click on the Bot menu to create a new bot configuration.

🛠️ Step 2 Name your configuration & Theme

Name: Name your configuration. This is only used when displaying the list of configurations. The first configuration is typically named "Default".

Description: The description of the configuration. This is only used when displaying the list of configurations and helps identify the purpose of each configuration.

Display tab

Manage the width and height of the Bot, and the mode of how the Bot opens. The check box for Expanded view, changes the behavior of the Bot when the page loads. If unchecked it will display as

Expanded view Checked

Bot

Expanded view Unchecked

Theme Selection

Choose your bot's visual theme from the dropdown list. The theme controls the overall appearance, colors, and styling of your bot interface.

Available Theme Options:

• Default Themes: Pre-built themes with standardized color schemes and styling
• Custom Theme: Create a personalized theme that matches your brand identity

Custom Theme Creation

When you select "Custom" from the theme dropdown, ai12z will automatically begin the theme creation process.

Important: Before creating a custom theme, we strongly recommend completing the AI Brand Creation process first. This will analyze your brand assets and automatically generate appropriate colors, fonts, and styling guidelines that will be used in your custom theme.

To create a custom theme:

1. Complete Brand Guidelines First (Recommended)

   • Navigate to AI Settings → Brand Guidelines

• Follow the AI Brand Creation guide to upload your brand images
• Generate and save your brand guidelines

2. Select Custom Theme

   • Return to your bot configuration
   • Choose "Custom" from the Theme dropdown
   • The system will automatically create a theme based on your saved brand guidelines

3. Theme Auto-Generation

   • If you have completed brand guidelines, the custom theme will automatically inherit:
     • Primary and secondary brand colors
     • Accent colors for highlights and interactions
     • Typography preferences
     • Overall visual style consistency
   • If no brand guidelines exist, a default custom theme template will be created that you can manually customize

Benefits of Custom Theme with Brand Guidelines:

• Brand Consistency: Automatically matches your website's visual identity
• Professional Appearance: Cohesive design that reflects your brand personality
• Time Saving: No manual color picking or style configuration needed
• Responsive Design: Optimized for all device sizes while maintaining brand integrity

Settings tab

• Bot Title Naming your Bot, this will show up when the Agent responds to the user
• Bot Placeholder Text The text seen in the search text input
• Link Target When clicking on an anchor tag, does it replace the page, does it open a new tab

Preventing Chatbot Abuse and Token Drain

Overview

If a public-facing chatbot is targeted by automated spam (bots/scripts), it can generate a large number of rapid AI requests and consume tokens. ai12z provides two primary controls to mitigate this:

1. Max Questions per Session (hard usage cap)
2. reCAPTCHA v3 (bot detection and blocking before AI calls)

Used together, they significantly reduce the risk of runaway token usage.

---

Control 1: Max Questions per Session

What it does

Max Questions per Session sets a hard ceiling on how many questions a single chat session can send to the AI. Once the limit is reached, the bot stops issuing additional AI requests, preventing further token spend from that session.

Why it prevents token drain

Even if a bot attempts to spam the chat UI, it cannot generate unlimited AI calls within the same session—usage is capped.

Where to configure

In your <ai12z-bot> configuration:

• Go to Settings
• Set Max questions per session
• (Optional) Set Message when reach the limit (recommended for clear UX)
• (Optional) Configure Auto Reset Timer to reset the session after a defined period of inactivity (or leave at 0 if you want the cap to effectively require a new session)

Recommended settings (baseline)

• Max questions per session: 10–25 (start at 20 for most sites)
• Message when reach the limit: “You’ve reached the question limit for this session. Please try again later.”
• Auto Reset Timer: 30–60 minutes (or 0 if you prefer stricter behavior)

---

Control 2: reCAPTCHA v3

What it does

reCAPTCHA v3 helps detect automated traffic and assigns a risk score. Low-trust requests can be blocked or restricted before the chatbot sends an AI request.

Why it helps

reCAPTCHA reduces the chance that scripted traffic can repeatedly trigger AI calls, which protects against rapid token drawdown.

Where to configure

In your <ai12z-bot> configuration:

• Open the reCaptcha V3 tab
• Enable reCAPTCHA v3 and enter the required reCAPTCHA settings (e.g., keys) as prompted
• Apply the recommended scoring/allow rules for your environment

Recommended approach (baseline)

• Turn on reCAPTCHA v3 for any bot exposed on a public site
• Start with a moderate threshold and tighten if you see abuse (exact threshold depends on your site traffic patterns)

---

Best Practice: Use Both Together

• Max Questions per Session guarantees a hard stop per session.
• reCAPTCHA v3 reduces automated traffic before it becomes token spend.

Together, they provide strong protection against common “spam the chatbot” abuse patterns.

View tab

By default none are needed.

Style tab

div.modal {
  background-image: unset;
  background-color: #2095ae;
}
p {
  color: red;
}
fieldset.user-input-fieldset {
  background: red;
}
#template-container .carousel-card {
  background-color: yellow;
}
audio-recorder .mic-botIcon {
  fill: red;
}
.sv-header__background-color--accent .sv-header__description .sd-description {
  color: red !important;
}

Privacy Statement

The Privacy Statement displays privacy information to users, typically as a brief notice with a link to your full privacy policy. Keep this concise and user-friendly.

Best Practices for Privacy Statement:

• Keep the message short and clear
• Link to your complete privacy policy page
• Include essential information about data collection
• Use reassuring language about data protection

Example Privacy Statement:

<p>
  Your privacy is important to us. We collect minimal information to provide
  better assistance.
  <a href="/privacy-policy" target="_blank">View our Privacy Policy</a>
</p>

Script tab

Note all integrations and even welcome message have there own script tab. Put general purpose script here.

ai12z runs in a shadow dom, so to access a function it will not work if it exists in a js file.

The code below will not work

<input type="text" id="myTextField" value="hello" /> const textField =
document.getElementById('myTextField');

In a shadow dom, you need to access using querySelector

• 1. First, get the host element (the element to which the shadow root is attached).
• 2. Then, access the shadow root via .shadowRoot.
• 3. After that, use regular DOM methods (like .querySelector) inside the shadow root.

Accessing and Manipulating HTML Elements in ai12z Bot Custom Scripts

ai12z allows you to add custom JavaScript functions to your bot for actions such as “Add to Cart,” opening links, or interacting with the page. When your function needs to interact with HTML elements (such as reading the value of a dropdown), you need to reference those elements relative to the button or UI element that triggered your script.

---

Example: Add to Cart Button With Quantity

Suppose you have an "Add to Cart" button and a quantity dropdown in your UI. You want your script to:

• Find the quantity selected by the user, and
• Show a confirmation with the title and selected quantity.

Here’s how you can do this:

function addToCart(button, title) {
  // Find the nearest select[name="qnty"] within the same container as the button
  var select = button.parentNode.querySelector('select[name="qnty"]')
  var qty = select ? select.value : 0
  alert("Added to cart: " + title + ", Quantity: " + qty)
}

How it works:

• button is a reference to the button element that was clicked (passed by the bot’s event system).
• button.parentNode gets the container (parent) of the button.
• .querySelector('select[name="qnty"]') looks for the <select> dropdown for quantity within that container.
• select.value gets the selected quantity value.

This pattern ensures your script only accesses the dropdown that belongs to the same “card” or UI block as the button clicked—avoiding confusion if there are multiple product cards on the page.

---

General Guidance for Accessing HTML Elements

• Always use the button or element that triggers your function as the starting point.
• Use parentNode, closest(), or other DOM traversal methods to reliably locate the relevant input, dropdown, or other element.
• Avoid using document.querySelector globally unless there is only ever one matching element—otherwise, you might get the wrong one!

Example: Open Link in a New Tab

function openLink() {
  window.open("https://www.google.com", "_blank")
}

---

Best Practices

• Keep selectors specific to the UI structure: Use parentNode or .closest() to scope your queries to the right container.
• Check for nulls: Always check if the element exists before using its value.
• Use clear, descriptive function names: So it’s obvious what each script does when editing later.

---

Summary

When writing custom JavaScript for ai12z bot controls:

• Functions can be called by the bot when events occur (like button clicks).
• To access UI fields, use the triggering element as a reference point and traverse the DOM as needed.
• This keeps your code robust even when there are many interactive elements on the page.