URL and panel change

Overview

The ai12z platform allows your AI assistant to intelligently navigate users to different pages on your website by using URL change directives. This creates a seamless, guided experience where the AI can proactively direct users to relevant content.

This feature uses the ai12z directive system. For comprehensive information about how directives work, extensibility, and security best practices, see AI Response Directives System.

How It Works

When the AI determines that navigating to a specific page would benefit the user, it includes a standardized directive in its response:

[directive=urlChange data="https://example.com/pricing"]

The platform automatically:

1. Extracts the urlChange directive from the AI's response using the centralized directive parser
2. Removes the directive syntax from the visible response text
3. Sends the clean text and URL data to the client via the messageReceived event as urlChange: "https://example.com/pricing"
4. Allows the client to trigger the urlChange directive from the AI's response using the standardized directive parser
5. Sends it to the client via the messageReceived event with the URL in the urlChange field
6. Triggers browser navigation to the specified URL

System Prompt Configuration

To enable your AI to use this capability, add the following instructions to your agent's system prompt.

Note: The auto-navigate approach (no confirmation) is the most common use case and provides the smoothest user experience.

AnswerAI System Prompt: Answer-first + Auto-Navigate (Recommended)

Important Configuration:

• Update Allowed domains to match your website domains
• Update Panel IDs array to match your actual panel structure (if using panels)
• Always include citations in content for mobile users who may not see page changes

## AnswerAI: Answer-first + Auto-Navigate (no confirmation)

You ALWAYS answer the question FIRST using RAG/integration results.
Then you ALWAYS switch panel and navigate to the best URL (no questions asked).

Allowed domains ONLY:

- https://ai12z.com/
- https://docs.ai12z.net/

### Panel IDs

["main","platform","industries","features","resources","pricing","support","blog"]

Keyword hints (non-exhaustive):

- pricing: pricing, cost, plan, tier, quote, budget, subscription
- platform: platform, how it works, architecture, reasoning engine, orchestration
- features: features, agents, connectors, RAG, forms, web control, personalization
- industries: healthcare, finance, retail, travel, hospitality, manufacturing, higher-ed
- resources: docs, documentation, guide, tutorial, webinar, demo, video, case study
- support: help, support, troubleshooting, contact, issue, bug
- blog: blog, posts, articles, news, updates

### Target URL selection (context-first, aggressive)

Choose exactly ONE targetUrl using this priority:
If RAG context includes one or more source URLs on allowed domains, pick the single best match:

- Prefer the URL whose content most directly answers the question
- Prefer deeper/more specific URLs (e.g., /pricing/enterprise over /pricing/)

### RAG alignment requirement (important)

When you select targetUrl, your answer must be consistent with that page.
Prefer facts/details from the RAG chunks that came from targetUrl (or the closest matching URL).

### Directives (always)

- If panel confidence >= 0.60, ALWAYS emit:
  [directive=changePanel data="panelId"]
- If you have a valid targetUrl (allowed domain), ALWAYS emit:
  [directive=urlChange data="targetUrl"]
- Do NOT ask any navigation question.
- Suppress urlChange if targetUrl equals currentUrl (don't emit the directive).

### Insert the Directive

Example: When asked "who is Bill Rogers", if the answer came from https://ai12z.com/about/,
your response should:

1. Include the citation link in the content (for mobile users)
2. ALWAYS emit the directive: [directive=urlChange data="https://ai12z.com/about/"]

### Directive placement

Put directives at the VERY END of the message, each on its own line.
Emit changePanel first, then urlChange.

### Example Response

User: "What are your pricing options?"

AI: "We offer three pricing tiers to fit different needs:

**Basic Plan** - $99/month

- Up to 1,000 conversations
- Standard AI models
- Email support

**Pro Plan** - $299/month

- Up to 5,000 conversations
- Advanced analytics
- Priority support

**Enterprise** - Custom pricing

- Unlimited conversations
- Dedicated account manager
- Custom integrations

See complete details at https://ai12z.com/pricing/

[directive=changePanel data="pricing"]
[directive=urlChange data="https://ai12z.com/pricing/"]"

React LLM System Prompt

## React: Router LLM

You are the ai12z Router LLM. You DO NOT answer the user.
The only time React inserts [directive=urlChange data="https://..."] is if in your context
you know the URL the user is asking about.

### Directive placement

Put directives at the VERY END of the message, each on its own line.
Emit changePanel first, then urlChange.

Alternative: Permission-First Navigation Pattern

For use cases where you want to ask permission before navigating:

## AnswerAI: Answer-first + Navigation Offer (with confirmation)

When the user asks about topics, you must:

1. Answer the question FIRST (use RAG/AnswerAI content).
2. Provide a helpful link to the most relevant page.
3. Ask ONE clear question: "Want me to open that page for you?"

### Allowed domains (only these)

- https://ai12z.com/
- https://docs.ai12z.net/

### Pending navigation rule

If your last message included a navigation-offer question, treat the next user reply:

- Yes/ok/sure/please → navigate immediately (no repeat question)
- No/not now → do not offer again in this conversation

Example: [directive=urlChange data="https://ai12z.com/pricing/"]

Client-Side Implementation

Complete Implementation with Panel Changes and URL Navigation

Add the following JavaScript to your webpage to handle both panel changes and URL navigation:

Welcome Script tab

function ai12zShowPanel(panel) {
  // save selected panel
  sessionStorage.setItem("ai12z-active-panel", panel)

  bot.setAttribute("active-panel", panel)

  var root =
    window.ai12zCtrl && typeof ai12zCtrl.shadowRoot === "function"
      ? ai12zCtrl.shadowRoot()
      : document

  var panels = [
    "main",
    "platform",
    "industries",
    "features",
    "resources",
    "pricing",
    "support",
    "blog",
  ]

  for (var i = 0; i < panels.length; i++) {
    var el = root.querySelector("#ai12z-" + panels[i] + "-panel")
    if (el) {
      el.style.display = "none"
    }
  }

  var target = root.querySelector("#ai12z-" + panel + "-panel")

  if (target) {
    target.style.display = "block"
  } else {
    var main = root.querySelector("#ai12z-main-panel")
    if (main) {
      main.style.display = "block"
    }
  }
}

function isRendered(el) {
  if (!el) return false
  const style = getComputedStyle(el)
  return (
    style.display !== "none" &&
    style.visibility !== "hidden" &&
    style.opacity !== "0" &&
    el.offsetHeight > 0
  )
}

customElements.whenDefined("ai12z-bot").then(() => {
  const panel = sessionStorage.getItem("ai12z-active-panel") || "main"
  const bot = document.querySelector("ai12z-bot")
  if (!bot || !bot.shadowRoot) return

  const root = bot.shadowRoot

  // Wait until Shadow DOM has any panels
  function waitForPanels() {
    const panelsExist = root.querySelector("#ai12z-main-panel") // just check main panel exists
    if (panelsExist && isRendered(panelsExist)) {
      // Now we can safely show the correct panel
      bot.setAttribute("active-panel", panel)
    } else {
      requestAnimationFrame(waitForPanels)
    }
  }

  waitForPanels()
})

// Get reference to the ai12z bot element
const bot = document.querySelector("ai12z-bot")

// Listen for messages from the AI
bot.addEventListener("messageReceived", (event) => {
  const data = event.detail.data
  // Handle panel changes
  if (data && data.changePanel) {
    console.log("Switching to panel:", data.changePanel)
    ai12zShowPanel(data.changePanel)
  }

  // Check if the response includes a URL change directive
  if (data && data.urlChange) {
    const targetUrl = data.urlChange

    console.log("AI requesting navigation to:", targetUrl)

    // Navigate to the URL
    window.location.href = targetUrl

    // Alternative: Open in new tab
    // window.open(targetUrl, '_blank');
  }
})

Developer Notes:

• Update the panels array in ai12zShowPanel() to match your actual panel IDs
• Ensure panel IDs in your HTML match the format: #ai12z-{panelId}-panel
• Update the Allowed domains in your system prompt to match your website

CSP Considerations

Ensure your Content Security Policy allows navigation:

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; navigate-to 'self';"
/>

Troubleshooting

URL Not Changing

Problem: The page doesn't navigate when AI provides a URL

Solutions:

1. Verify the messageReceived event listener is registered
2. Check browser console for JavaScript errors
3. Confirm the URL format is correct (absolute URL with protocol)
4. Ensure the bot element is properly initialized

Directive Visible in Response

Problem: User sees [directive=urlChange data="..."] in the chat

Solutions:

1. The server-side extraction should remove this automatically
2. Verify the backend is processing directives correctly
3. Check that the response is passing through the extract_directives() function
4. Ensure you're using the correct directive format with proper escaping

---

Related Documentation

• AI Response Directives System - Complete directive system overview and implementation

---

Configuration Checklist:

1. ✅ Update allowedDomains array to match your website
2. ✅ Update panels array in ai12zShowPanel() to match your panel IDs
3. ✅ Update system prompt Panel IDs to match your panels
4. ✅ Update system prompt Allowed domains to match your website
5. ✅ Ensure HTML panel elements use format: id="ai12z-{panelId}-panel"