Configuration

Overview

The ai12z CTA (Call-to-Action) Search is a powerful modal dialog component that provides AI-powered search capabilities with a rich, customizable interface. It can serve multiple purposes:

AI Search Dialog: Full conversational AI search with natural language understanding
Quick Answer Interface: Display commonly asked questions as quick-action buttons
Welcome Screen: Present navigation shortcuts or featured content
Multi-panel Experience: Create custom layouts with multiple information panels

CTA search

Key Features

Flexible Input Options: Audio input, image upload, and text search
Customizable Layout: Position input field at top or bottom, control dialog dimensions
Complete Control: Custom CSS and JavaScript for full design control
Quick Answers: Pre-configured question buttons for common queries
Mobile Optimized: Responsive design that adapts to any screen size

The modal dialog approach offers significant advantages over embedded search interfaces:

1. Clean Page Design with On-Demand Access

Add a simple magnifying glass icon or search button anywhere on your page. When clicked, the full-featured AI search interface appears as a modal dialog, keeping your page layout clean and uncluttered while providing powerful search capabilities when needed.

Example: A header navigation bar with a search icon that opens the complete AI search experience.

2. Wizard-Based Query Generation

Create interactive wizards or forms that collect user inputs, then programmatically construct an AI query from those selections. The modal dialog displays the AI-generated answer based on the wizard's output.

Example: A product finder wizard where users select preferences (price range, features, use case), and when they click "Find Products," the CTA dialog opens with an AI-generated recommendation based on their selections.

// Collect wizard inputs
const preferences = {
  priceRange: "$500-$1000",
  skill: "intermediate",
  terrain: "all-mountain",
}

// Generate query and open dialog with AI answer
const query = `Recommend ski boots for ${preferences.skill} skier, ${preferences.terrain} terrain, budget ${preferences.priceRange}`
ctaDialog.setAttribute("question", query)
ctaDialog.action() // Opens dialog with AI answer

3. Context-Specific Help Dialogs

Trigger the search dialog from anywhere on your page with pre-populated questions or context. Different buttons or links can open the same dialog with different initial queries.

Example: Multiple "Learn More" links throughout a product page, each opening the dialog with a specific question relevant to that section.

4. Space-Efficient Mobile Experience

On mobile devices, the modal takes over the full screen, providing an optimal user experience without compromising functionality or requiring dedicated page real estate.

5. Focused User Attention

The modal overlay focuses user attention on the search interaction, reducing distractions and improving engagement with AI-generated answers.

Common Use Cases:

Global site search: Magnifying glass icon in navigation
Product recommendations: Wizard-based product finders
Customer support: Context-sensitive help buttons
Documentation search: Quick access to knowledge base
Lead generation: Interactive quizzes that provide AI-powered recommendations

The CTA Search provides an elegant way to offer AI-powered assistance without cluttering your page. Users can access comprehensive search functionality on-demand through a modal dialog, maintaining clean page layouts while providing powerful search capabilities.

Managing Configurations

Creating a New Configuration

To create a new CTA Search configuration:

Navigate to your Agent dashboard
Select Web Controls from the left navigation panel
Click on <ai12z-cta> Search
Click the Add Web Config button in the top right

List of Configurations

The configuration list displays all your CTA Search configurations. Each entry shows:

Field	Description
Name	A descriptive identifier for the configuration
Config ID	Unique identifier used to reference this configuration in your code with the `config-id` attribute
Description	Brief explanation of the configuration's purpose
Modified	Last update date and time
Default	Badge indicating which configuration is the default
Action	Menu with options to edit, preview, or delete the configuration

Using a Configuration

When you have multiple configurations, specify which one to use by adding the config-id attribute:

<!-- Using a specific configuration -->
<ai12z-cta data-key="<API_KEY>" config-id="6966a41c3486371232adc421">
</ai12z-cta>

<!-- Using the default configuration -->
<ai12z-cta data-key="<API_KEY>"></ai12z-cta>

Configuration Tabs

Each configuration consists of five main tabs: Display, Settings, Welcome, Style, and Script. These tabs allow you to control different aspects of the CTA Search behavior and appearance.

Display Tab

The Display tab controls the visual appearance and layout of your CTA Search dialog.

CTA Display Configuration

Basic Information

Setting	Description	Example
Name	Configuration identifier (used only in admin list view)	"Default", "Mobile Search", "Help Dialog"
Description	Brief explanation of configuration purpose (admin only)	"Main search for homepage", "Kalauni resort"

Dialog Layout

Setting	Description	Default/Example
Heading	Text displayed at the top of the dialog	Leave blank or "How can we help you today?"
Dialog Width	Width of the dialog box	"70%"
Dialog Max Width	Maximum width constraint	"40rem"
Dialog Top Margin	Space from top of viewport to dialog	"5rem"
Dialog Minimum Height	Minimum height of the dialog	"300px"
Input Field Position	Where to place the search input	"Top" or "Bottom"

Options

CTA Options

The Options section provides checkboxes to control various features:

Option	Description
Auto Search	When enabled, automatically executes search when text is sent via JavaScript. When disabled, only populates the search box
Categorize	When enabled, shows search results grouped by category as you type
Allow Close	When enabled, displays a close icon (X) in the dialog
Enable Mobile view	When enabled (default), dialog takes over entire screen on small devices for optimal mobile experience
Clear Memory	When enabled, provides option in the + menu to clear conversation history
Image Upload	When enabled, allows users to upload images via the + menu for visual analysis with their query
Mic	When enabled, provides voice input capability for hands-free search
Show Message Icons	When enabled, displays icons alongside messages (uses default icons if custom ones aren't uploaded)

Theme Color

The Theme Color dropdown allows you to choose a visual theme for your CTA Search dialog. The theme controls colors, styling, and overall appearance.

Available Options:

Preset Themes: Pre-configured color schemes including Default, Cyan, Amber, Orange, Purple, Red, Pink, Brown, Slate, Sky, Lime, Yellow, and Indigo
Custom: Create a personalized theme using your brand colors and CSS variables

Custom Theme Creation

Selecting Custom enables the Theme tab in the CTA configuration. The Theme tab displays a CSS variables editor on the left, pre-populated with your CTA's current theme values, and a Vibe Coding panel on the right.

Theme tab with CSS editor and Vibe Coding panel

Tip: Before creating a custom theme, complete the AI Brand Creation process first. Your saved brand guidelines are automatically referenced when generating a custom theme, so the output will already reflect your brand's colors, fonts, and style.

To create a custom theme:

Set up Brand Guidelines (Recommended)
- Navigate to AI Settings → Brand Guidelines
- Follow the AI Brand Creation guide to paste your Figma Design Tokens JSON, plain text brand guidelines, or upload screenshots of your website
- Save your brand guidelines
Select Custom Theme
- Return to your CTA configuration
- Choose Custom from the Theme Color dropdown
Customize with Vibe Coding or Manual Editing
- The Theme tab opens with a CSS variables editor pre-loaded with the default custom theme
- To use Vibe Coding: Type your instructions in the Instruction box on the right panel — for example, "Update the primary color to match our teal brand" or "Apply our brand guidelines to this theme." You can also paste Figma Design Tokens JSON directly into the instruction box, or attach screenshots for the AI to match. Click Submit Instructions and the AI updates the CSS variables for you
- To edit manually: Modify the CSS variable values directly in the editor on the left
- Review AI feedback in the Feedback panel, then click Save

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

The Settings tab controls behavior, limits, voice settings, and search parameters.

CTA Settings tab

Configuration Settings

Setting	Description	Default/Example
No Results Text	Message shown when no search results are found	"No results found"
Placeholder	Placeholder text in the search input field	"AI search"
Link Target	How search result links open	`_blank` (new tab)
Max questions per session	Maximum number of questions allowed per session (prevents abuse)	5
Auto Reset Timer	Minutes of inactivity before resetting the session	0 (disabled)
Message when reach the limit	Text shown when question limit is reached	"Sorry, you have reached your message limit"
Audio Type	Audio feedback style	"Default"
Voices	Text-to-speech voice selection	"Google US English"
Max Results	Maximum number of search results to display	4
Score	Minimum relevance score threshold (0-1 slider)	0.6

Preventing Chatbot Abuse and Token Drain

Overview

If a public-facing CTA Search is targeted by automated spam (bots/scripts), it can generate excessive AI requests and consume tokens. ai12z provides controls to mitigate this:

Max Questions per Session - Hard usage cap per session
Auto Reset Timer - Automatically reset sessions after inactivity
reCAPTCHA v3 - Bot detection (can be configured separately)

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.

Note: See Directives [directive=badActor] for one of the best ways to eliminate a bad actor.

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)

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)

Welcome Tab

The Welcome tab allows you to create custom welcome screens with Quick Answer buttons, FAQs, or multi-panel layouts.

Welcome tab for CTA Config

Features

Custom HTML: Insert any HTML content in the welcome screen
Quick Answer Buttons: Create pre-configured question buttons that users can click
Multi-panel Support: Build complex layouts with multiple information panels
Interactive Elements: Use sendMessage() and sendJSON() for dynamic interactions
Dedicated Styling: Welcome panel has its own Styles and Scripts tabs for customization

Select Panel

Choose which panel to edit from the dropdown (e.g., "Main" panel).

Preview Tabs

Preview: See how your welcome screen looks
HTML: Edit the HTML content
Styles: Add custom CSS for the welcome panel - this Styles is just for the welcome screen
Scripts: Add custom JavaScript for welcome panel interactions - this Scripts is just for the welcome screen,

The sytles and Scripts in the top menu is the global scripts and styles, often has nothing it it. The vibe coding for welcome screen only effects the Styles and Scripts for the welcome screen. If it is not meant for the welcome screen put it in the global.

Feedback Panel

Displays real-time feedback as you make changes to help you understand the results of your customizations.

Instruction Panel

Use AI to generate or modify your welcome panels:

Describe what you want to create or change
Optionally attach an image for design reference
Click Submit Instructions
The AI will generate the panel layout based on your description

Example: Kalauni Resort Welcome Screen

The screenshot shows a hospitality-focused welcome screen with:

Heading: "How can we help you today?"
Quick Answer Buttons: Common questions organized in three rows:
- Row 1: Room availability, Resort amenities, Spa services
- Row 2: Restaurant & dining, Activities, Special offers
- Row 3: Cancellation policy, Transportation, Check-in times
Action: Each button triggers an instant AI response

This provides guests with immediate access to frequently requested information.

Style Tab, Global styles

The Style tab allows you to add custom CSS to further customize the appearance of your CTA Search beyond the theme settings. Don't put Styles for the Wecome screen

Note: The Welcome tab has its own dedicated Styles sub-tab for welcome panel-specific styling.

Custom CSS

Use the Custom CSS editor to:

Override default styles
Add responsive design rules
Customize specific elements within the dialog
Match your site's design system

Script Tab, Global styles

The Script tab enables you to add custom JavaScript to enhance or modify the CTA Search behavior. Don't put welcome screen script in this tab.

Note: The Welcome tab has its own dedicated Scripts sub-tab for welcome panel-specific functionality.

Custom JavaScript

Use the Custom JS editor to:

Add event listeners for user interactions
Integrate with analytics or tracking tools
Implement custom business logic
Extend functionality beyond default capabilities

View Tab

The View tab manages the visual identity assets for your CTA Search — the images and branding elements that appear within the interface — as well as the privacy statement shown to users.

Bot Logo

Upload a logo image that appears inside the CTA dialog. This is typically your primary brand mark or wordmark.

Button: Click Change logo to upload or replace the current logo
Accepted formats: JPG, GIF, PNG, or SVG
Max file size: 128KB

Avatar

The avatar is the icon or image that represents the AI assistant within the conversation. It appears alongside AI responses to give the assistant a visual identity.

Button: Click Change avatar to upload or replace the current avatar
Accepted formats: JPG, GIF, PNG, or SVG
Max file size: 128KB

Bot Launch Icon

The launch icon is the image displayed on the button or trigger that users click to open the CTA dialog. Customize this to integrate seamlessly with your site's design.

Button: Click Change launch Icon to upload or replace the current icon
Accepted formats: JPG, GIF, PNG, or SVG
Max file size: 128KB

Privacy Statement

The Privacy Statement is an HTML field that displays a brief privacy notice to users within the CTA interface. Use this to communicate your data practices or link to your full privacy policy.

Example:

<p>Privacy Policy</p>

Best Practices:

Keep the message short and clear
Link to your complete privacy policy page using an anchor tag
Use reassuring language about data protection

Example with link:

<p>
  Your privacy is important to us.
  <a href="/privacy-policy" target="_blank">View our Privacy Policy</a>
</p>

reCAPTCHA V3 Tab

reCaptcha dialogo

reCAPTCHA v3 is a frictionless, invisible tool from Google that detects and blocks bots on your website by assigning a risk score to user interactions — without requiring user challenges like checkboxes or image puzzles. It helps protect your CTA Search from automated abuse while providing a seamless experience for real users.

When enabled, every interaction with the CTA Search is scored by Google. Interactions falling below your configured threshold are blocked before any AI request is made, protecting against token drain and spam.

Fields

Field	Required	Description
Site Key	Yes	The public key from your Google reCAPTCHA v3 registration. Used in the front-end to load the reCAPTCHA script
Secret Key	Yes	The private key from your Google reCAPTCHA v3 registration. Used server-side to verify the token score
Failed Message	Yes	The message displayed to the user when their interaction is blocked due to a low reCAPTCHA score
Score Threshold	Yes	A value between 0.0 and 1.0. Interactions scoring below this threshold are blocked. Google recommends starting at `0.5`

Getting Your reCAPTCHA v3 Keys

Go to Google reCAPTCHA Admin Console
Click + to create a new site
Select reCAPTCHA v3 as the type
Add your domain(s)
Copy the Site Key and Secret Key into the fields above

Score Threshold Guide

Score	Meaning
`1.0`	Very likely a human
`0.5`	Recommended starting threshold
`0.3`	More permissive — allows more borderline traffic
`0.0`	No filtering (effectively disabled)

Start at 0.5 and adjust based on your traffic patterns. If legitimate users are being blocked, lower the threshold slightly. If you're still seeing abuse, raise it.

Failed Message Example

Our system detected unusual activity. Please try again or contact support if this continues.

Keep the message user-friendly — legitimate users can occasionally receive a low score on restricted networks or with VPNs.

Best Practice: Combine with Max Questions per Session

reCAPTCHA v3 blocks automated traffic before AI requests are made. Pairing it with Max Questions per Session (in the Settings tab) provides two layers of protection:

reCAPTCHA v3 — blocks bots at the entry point
Max Questions per Session — caps usage for any session that gets through

Together they significantly reduce the risk of token drain from automated abuse.

Liveagent Tab

Live Agent

The Liveagent tab allows you to connect your CTA Search to a live agent platform, enabling seamless handoff from the AI assistant to a human agent when needed. When configured, the CTA can escalate conversations to a live support channel based on user intent or explicit request.

Provider Settings

The Provider Settings field accepts a JSON configuration object that defines your live agent provider and connection details. The structure varies by provider.

Salesforce Example

{
  "salesforce": {
    "instanceUrl": "https://instance.salesforce.com",
    "orgId": "ORG_ID_HERE",
    "messagingChannelId": "CHANNEL_ID_HERE"
  }
}

Field	Description
`instanceUrl`	The URL of your Salesforce instance (e.g., `https://yourorg.my.salesforce.com`)
`orgId`	Your Salesforce Organization ID, found in Setup → Company Information
`messagingChannelId`	The Messaging Channel ID for the Salesforce Messaging for In-App and Web channel configured for live agent handoff

Getting Your Salesforce Values

Instance URL — Log in to Salesforce and copy the base URL from your browser (e.g., https://yourorg.my.salesforce.com)
Org ID — Go to Setup → Company Information and copy the Salesforce Organization ID
Messaging Channel ID — Go to Setup → Messaging Settings, open your Messaging for In-App and Web channel, and copy the Channel ID from the URL or channel detail page

How It Works

Once configured, the CTA Search can route users to a live agent when:

The user explicitly requests a human agent
The AI detects a conversation topic that should be handled by a human
A configured directive or rule triggers an escalation

The live agent chat session opens within the same CTA dialog, providing a continuous experience without redirecting the user to a separate support page.

Best Practices

Configuration Management

Use Descriptive Names: Name configurations based on their use case (e.g., "Homepage Search", "Support Dialog", "Mobile CTA")
Set a Default: Always designate one configuration as default for fallback behavior
Test Responsive Design: Verify dialog appearance on desktop, tablet, and mobile devices

Welcome Screen Design

Limit Quick Answers: Use 6-12 buttons maximum to avoid overwhelming users
Organize by Topic: Group related questions together
Use Clear Labels: Make button text concise and action-oriented
Consider Context: Tailor quick answers to the page or section where the CTA appears

Performance Optimization

Set Question Limits: Protect against abuse with reasonable session limits
Enable Auto Reset: Use Auto Reset Timer for better user experience
Optimize Welcome HTML: Keep welcome screen HTML lightweight
Test Load Times: Ensure dialog opens quickly on slower connections

Voice and Audio

Choose Appropriate Voice: Select a voice that matches your brand personality
Test Audio Type: Verify audio feedback works across different browsers
Consider Accessibility: Voice features help users with visual impairments

CTA Search Component - Main component documentation
Agent Settings - Managing your agent and API keys
AI Brand Creation - Customizing theme with brand guidelines

Overview​

Key Features​

Why Use a Modal Dialog Search?​

1. Clean Page Design with On-Demand Access​

2. Wizard-Based Query Generation​

3. Context-Specific Help Dialogs​

4. Space-Efficient Mobile Experience​

5. Focused User Attention​

Managing Configurations​

Creating a New Configuration​

List of Configurations​

Using a Configuration​

Configuration Tabs​

Display Tab​

Basic Information​

Dialog Layout​

Options​

Theme Color​

Custom Theme Creation​

Settings Tab​

Configuration Settings​

Preventing Chatbot Abuse and Token Drain​

Overview​

Max Questions per Session​

Why it prevents token drain​

Where to configure​

Recommended settings (baseline)​

Welcome Tab​

Features​

Select Panel​

Preview Tabs​

Feedback Panel​

Instruction Panel​

Example: Kalauni Resort Welcome Screen​

Style Tab, Global styles​

Custom CSS​

Script Tab, Global styles​

Custom JavaScript​

View Tab​

Bot Logo​

Avatar​

Bot Launch Icon​

Privacy Statement​

reCAPTCHA V3 Tab​

Fields​

Getting Your reCAPTCHA v3 Keys​

Score Threshold Guide​

Failed Message Example​

Best Practice: Combine with Max Questions per Session​

Liveagent Tab​

Provider Settings​

Salesforce Example​

Getting Your Salesforce Values​

How It Works​

Best Practices​

Configuration Management​

Welcome Screen Design​

Performance Optimization​

Voice and Audio​

Related Documentation​

Overview

Key Features

Why Use a Modal Dialog Search?

1. Clean Page Design with On-Demand Access

2. Wizard-Based Query Generation

3. Context-Specific Help Dialogs

4. Space-Efficient Mobile Experience

5. Focused User Attention

Managing Configurations

Creating a New Configuration

List of Configurations

Using a Configuration

Configuration Tabs

Display Tab

Basic Information

Dialog Layout

Options

Theme Color

Custom Theme Creation

Settings Tab

Configuration Settings

Preventing Chatbot Abuse and Token Drain

Overview

Max Questions per Session

Why it prevents token drain

Where to configure

Recommended settings (baseline)

Welcome Tab

Features

Select Panel

Preview Tabs

Feedback Panel

Instruction Panel

Example: Kalauni Resort Welcome Screen

Style Tab, Global styles

Custom CSS

Script Tab, Global styles

Custom JavaScript

View Tab

Bot Logo

Avatar

Bot Launch Icon

Privacy Statement

reCAPTCHA V3 Tab

Fields

Getting Your reCAPTCHA v3 Keys

Score Threshold Guide

Failed Message Example

Best Practice: Combine with Max Questions per Session

Liveagent Tab

Provider Settings

Salesforce Example

Getting Your Salesforce Values

How It Works

Best Practices

Configuration Management

Welcome Screen Design

Performance Optimization

Voice and Audio

Related Documentation