Skip to main content

Configuration

Overview​

The <search-result-page> component is designed for traditional search page implementations where the search interface is embedded directly into a dedicated page (e.g., /search or /search-results). Unlike modal dialogs, this component provides a full-page search experience with AI-powered results, categorized content, and quick answer buttons.

Typical Use Case: Create a dedicated search page at www.example.com/search where users land after entering a query from a search box elsewhere on your site.

Search result page

Search bar that directs to search

Key Features​

  • URL Parameter Support: Automatically reads search queries from URL parameters (e.g., ?searchText=Can+you+wash+your+clothes)
  • Real-Time Search Results: As users type, displays categorized results with titles and descriptions in the right column, allowing navigation without clicking submit
  • Flexible Input Options: Audio input, image upload, and text search
  • AI Overview: Displays AI-generated summaries at the top of search results
  • Quick Answer Buttons: Pre-configured question buttons for common queries
  • As you type results: Results organized by category (e.g., Safety Gear, Seasonal Gear Guides, Layered Apparel, Cold Weather Gear) links to pages without asking AI.
  • Mobile Optimized: Responsive design that adapts to any screen size
  • Complete Control: Custom CSS and JavaScript for full design control

Why Use a Dedicated Search Page?​

The <search-result-page> component is ideal for implementing traditional search functionality where users expect a full-page experience:

Users enter a query in a search box (in your header or sidebar), and are directed to a dedicated search page that displays results. The component automatically reads the query from the URL parameter.

Example Implementation:

<!-- Search form on any page -->
<form action="/search" method="get">
  <input
    type="text"
    name="searchText"
    placeholder="Search Atlas... ski boots, helmets, ski goggles"
  />
  <button type="submit">Search</button>
</form>

<!-- On /search page -->
<search-result-page
  data-key="YOUR_API_KEY"
  config-id="68c76887ff56ea304ecb7d55"
>
</search-result-page>

Result: User submits "ski boot sizing" → redirected to /search?searchText=ski+boot+sizing → AI results appear automatically

Create a dedicated search results page for your online store. Users can search for products and get AI-powered recommendations along with traditional product listings.

Example URL: www.atlasstore.com/search?searchText=beginner+ski+boots+under+400

Features:

  • AI overview at top: "Here are the best beginner ski boots under $400..."
  • Categorized results: Boots by brand, price range, or skill level
  • Quick answer buttons: "Shop goggles", "Shop Helmets", "Gear rentals"

Build a knowledge base search page where users can find articles, guides, and get AI-generated answers to their questions.

Example: docs.example.com/search?searchText=How+do+I+clean+my+skis

4. Multi-Step Search Flows​

Use wizards or forms to collect user preferences, then redirect to the search page with a constructed query:

// Product finder wizard collects preferences
const userPreferences = {
  activity: "all-mountain skiing",
  experience: "intermediate",
  budget: "$500-$800",
}

// Construct query and redirect to search page
const query = `Recommend ${userPreferences.activity} equipment for ${userPreferences.experience} skier, budget ${userPreferences.budget}`
window.location.href = `/search?searchText=${encodeURIComponent(query)}`

Add quick search links throughout your site that redirect users to pre-populated searches:

<!-- Link from product page -->
<a href="/search?searchText=How+to+wash+and+care+for+ski+jacket"
  >Care Instructions</a
>

<!-- Link from guide article -->
<a href="/search?searchText=storing+skis+and+snowboards+for+off+season"
  >Storage Tips</a
>

Common Use Cases:

  • E-commerce stores: Product search and discovery
  • Content websites: Article and blog search
  • Documentation sites: Knowledge base and help content
  • Community forums: Topic and discussion search
  • Corporate websites: Company information and resources

The <search-result-page> provides a familiar, full-page search experience while leveraging AI to enhance result quality and provide intelligent overviews.

Managing Configurations​

Creating a New Configuration​

To create a new Search Result Page configuration:

  1. Navigate to your Agent dashboard
  2. Select Web Controls from the left navigation panel
  3. Click on <search-result-page>
  4. Click the Add Search Result Config button in the top right

Search result configurations list

List of Configurations​

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

FieldDescription
NameA descriptive identifier for the configuration
Config IDUnique identifier used to reference this configuration in your code with the config-id attribute
DescriptionBrief explanation of the configuration's purpose
ModifiedLast update date and time
DefaultBadge indicating which configuration is the default
ActionMenu 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 -->
<search-result-page data-key="<API_KEY>" config-id="68c76887ff56ea304ecb7d55">
</search-result-page>

<!-- Using the default configuration -->
<search-result-page data-key="<API_KEY>"></search-result-page>

Reading Search Queries from URL​

The component automatically reads the search query from the URL parameter searchText:

/search?searchText=Can+you+wash+your+clothes
/search?searchText=ski+boot+sizing+guide
/search?searchText=best+helmets+for+beginners

Configuration Tabs​

Each configuration consists of four main tabs: Display, Settings, Welcome, and View. These tabs allow you to control different aspects of the Search Result Page behavior and appearance.

Display Tab​

The Display tab controls the visual appearance and layout of your Search Result Page.

Search Result Display Configuration

Basic Information​

SettingDescriptionExample
NameConfiguration identifier (used only in admin list view)"Default", "Atlas Search Page", "eComm demo search page"
DescriptionBrief explanation of configuration purpose (admin only)"Main search for homepage", "eComm demo search page for Atlas Store"

Display Options​

SettingDescriptionDefault/Example
PlaceholderPlaceholder text shown in the search input field"Search for Atlas products or information"
Input Field PositionWhere to place the search input"Top" (recommended for search pages)

Options​

Search Result Options

The Options section provides checkboxes to control various features:

OptionDescription
Auto SearchWhen enabled, automatically executes search on page load if searchText URL parameter exists
Load ResultsWhen enabled, automatically loads search results on page load
CategorizeWhen enabled, shows search results grouped by category
MicWhen enabled, provides voice input capability for hands-free search
Image UploadWhen enabled, allows users to upload images for visual search queries
Clear MemoryWhen enabled, provides option to clear conversation history
Show Message IconsWhen enabled, displays icons alongside messages

Theme Color​

The Theme Color dropdown allows you to choose a visual theme for your Search Result Page. 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​

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​

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

CTA Settings tab

Configuration Settings​

SettingDescriptionDefault/Example
No Results TextMessage shown when no search results are found"No results found"
PlaceholderPlaceholder text in the search input field"AI search"
Link TargetHow search result links open_blank (new tab)
Max questions per sessionMaximum number of questions allowed per session (prevents abuse)5
Auto Reset TimerMinutes of inactivity before resetting the session0 (disabled)
Message when reach the limitText shown when question limit is reached"Sorry, you have reached your message limit"
Audio TypeAudio feedback style"Default"
VoicesText-to-speech voice selection"Google US English"
Max ResultsMaximum number of search results to display4
ScoreMinimum 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:

  1. Max Questions per Session - Hard usage cap per session
  2. Auto Reset Timer - Automatically reset sessions after inactivity
  3. 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)
  • 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 categorized shortcuts. This appears when users first land on the search page or when no search is active.

Welcome tab for Search Result Page

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
  • Scripts: Add custom JavaScript for welcome panel interactions

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:

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

Example: Atlas Store Welcome Screen​

The screenshot shows an outdoor gear e-commerce welcome screen with:

  • Heading: "Quick Answers"
  • Quick Action Buttons: Organized in three rows:
    • Row 1: Shop goggles, Shop Helmets, Gear rentals, Winter apparel
    • Row 2: Track order, Returns & exchanges, Tune & repair, Find a store
    • Row 3: Sales & deals, Contact support
  • Categories: Safety Gear, Seasonal Gear Guides, Layered Apparel, Cold Weather Gear
  • Action: Each button triggers either a pre-populated search or navigates to a specific section

This provides shoppers with immediate access to popular categories and common tasks, improving the search page experience even before they enter a query.

View Tab​

The View tab provides a preview of your configured search page and allows you to test the search functionality before deploying it to your live site.

Preview Mode​

Use the View tab to:

  • Test search queries and see results in real-time
  • Verify Quick Answer buttons work correctly
  • Check mobile responsive design
  • Test voice input and image upload features
  • Ensure theme and styling appear as expected

Best Practices​

Configuration Management​

  1. Use Descriptive Names: Name configurations based on their use case (e.g., "Main Site Search", "Product Search", "Help Center Search")
  2. Set a Default: Always designate one configuration as default for fallback behavior
  3. Test Responsive Design: Verify search page appearance on desktop, tablet, and mobile devices
  4. Test URL Parameters: Ensure searchText parameter is properly read and executed

Welcome Screen Design​

  1. Limit Quick Answers: Use 6-12 buttons maximum to avoid overwhelming users
  2. Organize by Category: Group related buttons together (e.g., "Shop", "Support", "Account")
  3. Use Clear Labels: Make button text concise and action-oriented
  4. Consider User Intent: Tailor quick answers to common searches for your site

URL Integration​

  1. Use Standard Parameter: Stick with searchText as the URL parameter name for consistency
  2. Encode Queries: Always use encodeURIComponent() when constructing URLs with queries
  3. Handle Empty Queries: Show the welcome screen when no searchText parameter is present
  4. Test Deep Links: Verify shared search URLs work correctly

Performance Optimization​

  1. Set Reasonable Limits: Protect against abuse with session limits if needed
  2. Enable Auto Search: Turn on "Auto Search" and "Load Results" for immediate results on page load
  3. Optimize Welcome HTML: Keep welcome screen HTML lightweight
  4. Test Load Times: Ensure search page loads quickly with various query types

Voice and Audio​

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