Skip to main content

Configuration

🧩 Overview​

CTA searc

The CTA 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.

alt text

🛠️ Step 2 Name your configuration​

Bot Configuration Screen

Name: Name your configuration. Only used when displaying the list of configurations. The first configuration typically name Default. Description: The description of the configuration. Only used when displaying the list of configurations

Theme Selection​

Choose your CTA'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

  1. Select Custom Theme

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

  2. 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​

Setting CTA control tab

  • CTA Title Naming your CTA, this will show up when the Agent responds to the user

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-cta> 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)
  • 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-cta> 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
  • 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.

Notes and Limitations​

  • These controls are highly effective against basic spamming and many automated scripts.
  • For high-volume or distributed attacks, additional protections may be appropriate (e.g., CDN/WAF rate limiting, IP throttling, or bot management at the edge).

Quick FAQ​

Does “Max Questions per Session” stop abuse completely? It prevents unlimited usage within a single session by enforcing a hard cap. Pairing it with reCAPTCHA improves protection against automated session creation.

Will legitimate users ever hit the limit? Occasionally, yes—especially on support-heavy flows. That’s why adding a friendly “limit reached” message (and a reasonable reset timer) is recommended.

If you want, I can rewrite this in your exact docs voice (short/technical/marketing), and include a small “Suggested Defaults” callout box for the KB page.

Info tab​

Info tab for CTA Config

  • Help text The Welcome screen, When the CTA opens you can insert any HTML, including buttons, see sendMessage, and sendJSON

info tab welcome message for ai12z-cta control

<div class="my-welcome-panel">
  <div class="my-welcome-header">🌴 Welcome to Kaluani Beach Resort!</div>
  <div class="my-welcome-message">
    How can we make your stay unforgettable?
    <div class="my-welcome-sub">Select a question below or ask your own!</div>
  </div>
  <div class="my-btn-row">
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('What rooms and suites are available right now?')"
    >
      Check Room Availability
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('What amenities and activities does the resort offer?')"
    >
      Explore Resort Amenities
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('What local attractions and tours do you recommend?')"
    >
      Discover Local Attractions
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('Are there any current promotions or special packages?')"
    >
      View Special Offers
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('Can I book dining or spa reservations?')"
    >
      Book Dining or Spa
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('What is your cancellation and refund policy?')"
    >
      Ask About Cancellation Policy
    </button>
    <button
      class="ai12zbutton"
      onclick="ai12zCta.sendMessage('How can I arrange airport transfers or transportation?')"
    >
      Arrange Transportation
    </button>
  </div>
</div>
<style>
  .my-welcome-panel {
    background: #f9fafb;
    border-radius: 18px;
    box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.05);
    padding: 32px 28px 18px 28px;
    margin: 16px;
    max-width: 520px;
    text-align: center;
    font-family: inherit;
    border: 1px solid #f0f0f0;
  }
  .my-welcome-header {
    font-size: 1.4rem;
    font-weight: 600;
    margin-bottom: 8px;
    color: #114d3d;
    letter-spacing: 0.02em;
  }
  .my-welcome-message {
    font-size: 1.08rem;
    margin-bottom: 18px;
    color: #2a3342;
  }
  .my-welcome-sub {
    font-size: 0.92rem;
    color: #7685a6;
    margin-top: 2px;
  }
  .my-btn-row {
    display: flex;
    flex-direction: column;
    gap: 10px;
    align-items: stretch;
  }
  .ai12zbutton {
    color: #124d3e;
    background: #e7f6f0;
    font-weight: 500;
    border: 1px solid #b6ded0;
    border-radius: 7px;
    padding: 12px 18px;
    cursor: pointer;
    margin: 0;
    transition: background 0.18s;
    font-size: 1rem;
  }
  .ai12zbutton:hover {
    background: #c6ebe0;
    border-color: #80c7a6;
  }
</style>

Style tab​

Modify the stle for the search tab cta

Example CSS for Search cta. Right click inspect code find the class an add the css to the CSS tab of the control that you are using. It will not work adding this to seperate css, css needs to be added to the style of the control you are using

h1 {
  color: red;
}

#parent-element .non-pending-user p {
  color: blue;
}

form div.searchbar-bgcolor {
  background-color: red;
}

#template-container .carousel-card {
  background-color: green;
}
ai12z-category .cta-search-text {
  color: red;
}

audio-recorder .mic-icon {
  fill: black;
}
.sv-header__background-color--accent .sv-header__description .sd-description {
  color: red;
}
.sd-element__title .sd-element__num {
  display: none;
}

Script tab

Script tag

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).
    1. Then, access the shadow root via .shadowRoot.
    1. 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!
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.

🎨 Style Customization​