AI-Driven URL Navigation

Overview

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

How It Works

When the AI determines that navigating to a specific page would benefit the user, it can include a special directive in its response that triggers client-side navigation:

[urlChange url=https://example.com/pricing]

The platform automatically:

Extracts the URL directive from the AI's response
Sends it to the client via the messageReceived event
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:

Recommended System Prompt

## URL Navigation Capability

You have the ability to guide users to specific pages on the website when appropriate.

**When to Offer Navigation:**

- User asks about specific products, services, or pages
- User shows interest in taking action (e.g., "I want to sign up", "Tell me about pricing")
- User's question would be better answered by viewing a specific page
- Context suggests the user needs detailed information available on another page

**How to Use:**

1. **Ask Permission First** - Before navigating, ask if the user wants guidance:

   - "Would you like me to take you to our pricing page?"
   - "I can direct you to that section - would that be helpful?"
   - "Shall I guide you to the registration page?"

2. **If User Agrees** - Include the urlChange directive in your response:

[urlChange url=https://example.com/target-page]

3. **Provide Context** - Along with the navigation, explain what they'll find:
- "Great! I'm taking you to our pricing page where you can see all plan options and features."
- "Perfect! Navigating to the product demo page now - you'll be able to try it out immediately."

**Important Rules:**
- NEVER navigate without asking first (except for explicit requests like "show me pricing")
- ALWAYS use full absolute URLs (include https://)
- Only navigate to pages within the same domain/website
- Include the urlChange directive AFTER your explanatory text
- Keep your response natural - the user won't see the directive

**Example Interaction:**

User: "How much does this cost?"
AI: "I'd be happy to show you our pricing options. Would you like me to take you to the pricing page where you can compare all plans?"

User: "Yes please"
AI: "Perfect! Taking you to the pricing page now where you'll see detailed plan comparisons and features. [urlChange url=https://yoursite.com/pricing]"

For explicit navigation requests, you can configure the AI to navigate immediately:

**For Explicit Requests:**
When users explicitly ask to go to a page (e.g., "take me to pricing", "show me the contact page"), navigate directly:

User: "Take me to your pricing page"
AI: "Taking you to our pricing page now! [urlChange url=https://yoursite.com/pricing]"

Client-Side Implementation

Detecting and Handling URL Changes

Add the following JavaScript to your webpage to listen for URL change directives:

// 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

  // 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');
  }
})

Advanced Implementation with Confirmation

For additional control, you can implement a confirmation dialog:

bot.addEventListener("messageReceived", (event) => {
  const data = event.detail.data

  if (data && data.urlChange) {
    const targetUrl = data.urlChange

    // Optional: Show confirmation to user
    const userConfirmed = confirm(`Navigate to ${targetUrl}?`)

    if (userConfirmed) {
      window.location.href = targetUrl
    } else {
      // User cancelled - optionally send feedback to bot
      bot.sendMessage("I'd prefer to stay on this page for now.")
    }
  }
})

bot.addEventListener("messageReceived", (event) => {
  const data = event.detail.data

  if (data && data.urlChange) {
    const targetUrl = data.urlChange

    // Option 1: Same tab navigation (default)
    window.location.href = targetUrl

    // Option 2: New tab
    window.open(targetUrl, "_blank")

    // Option 3: Replace history (no back button)
    window.location.replace(targetUrl)

    // Option 4: Smooth scroll for anchor links
    if (targetUrl.includes("#")) {
      const anchor = targetUrl.split("#")[1]
      const element = document.getElementById(anchor)
      if (element) {
        element.scrollIntoView({ behavior: "smooth" })
      }
    }
  }
})

Use Cases

1. Product Guidance

User: "I'm interested in your enterprise features"
AI: "Our enterprise plan includes advanced security, dedicated support, and custom integrations. Would you like me to show you the full details on our enterprise page?"
User: "Yes"
AI: "Great! Taking you there now. [urlChange url=https://yoursite.com/enterprise]"

2. Lead Capture

User: "Can someone from sales contact me?"
AI: "Absolutely! I can take you to our contact form where you can schedule a call with our sales team. Would that work for you?"
User: "Sure"
AI: "Perfect! Directing you to the contact form now. [urlChange url=https://yoursite.com/contact-sales]"

User: "How do I integrate this with Salesforce?"
AI: "We have a detailed integration guide for Salesforce. Would you like me to take you to the step-by-step tutorial?"
User: "Yes please"
AI: "On my way! You'll find complete setup instructions and code examples. [urlChange url=https://yoursite.com/docs/salesforce-integration]"

4. Checkout Flow

User: "I'd like to purchase the pro plan"
AI: "Excellent choice! The Pro plan includes unlimited users and advanced analytics. Shall I take you to checkout?"
User: "Yes"
AI: "Taking you to the checkout page for the Pro plan now. [urlChange url=https://yoursite.com/checkout?plan=pro]"

Best Practices

Do's

✅ Ask permission before navigating (conversational consent)
✅ Explain what the user will find on the target page
✅ Use full absolute URLs (include protocol and domain)
✅ Stay within your domain for seamless experience
✅ Provide context about why navigation is helpful
✅ Handle explicit requests immediately ("show me X")

Don'ts

❌ Don't navigate unexpectedly without user consent
❌ Don't use relative URLs - always use full URLs
❌ Don't navigate to external sites without clear warning
❌ Don't overuse - only navigate when it adds value
❌ Don't navigate mid-conversation without completing the thought

Security Considerations

URL Validation

Implement URL validation to prevent malicious navigation:

bot.addEventListener("messageReceived", (event) => {
  const data = event.detail.data

  if (data && data.urlChange) {
    const targetUrl = data.urlChange

    // Validate URL is from your domain
    const allowedDomains = ["yoursite.com", "www.yoursite.com"]
    const url = new URL(targetUrl)

    if (allowedDomains.includes(url.hostname)) {
      window.location.href = targetUrl
    } else {
      console.warn("Navigation blocked: URL not in allowed domains")
    }
  }
})

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:

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

Directive Visible in Response

Problem: User sees [urlChange url=...] in the chat

Solutions:

The server-side extraction should remove this automatically
Verify the backend is processing the directive correctly
Check that the response is passing through the URL extraction function

Problem: Browser prevents navigation (popup blocker)

Solutions:

Ensure navigation happens directly from user interaction
Use window.location.href instead of window.open() when possible
Request popup permissions if opening new tabs

Complete Example

<!doctype html>
<html>
  <head>
    <title>AI Navigation Demo</title>
    <script src="https://cdn.ai12z.net/@latest/ai12z.js"></script>
  </head>
  <body>
    <ai12z-bot api-key="your-api-key" agent-id="your-agent-id"> </ai12z-bot>

    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const bot = document.querySelector("ai12z-bot")

        bot.addEventListener("messageReceived", (event) => {
          const data = event.detail.data

          // Handle URL changes
          if (data && data.urlChange) {
            const targetUrl = data.urlChange

            // Log for debugging
            console.log("AI navigating to:", targetUrl)

            // Validate domain
            try {
              const url = new URL(targetUrl)
              const currentDomain = window.location.hostname

              if (url.hostname === currentDomain) {
                // Same domain - navigate
                window.location.href = targetUrl
              } else {
                // External domain - warn and open in new tab
                console.warn("External URL detected, opening in new tab")
                window.open(targetUrl, "_blank")
              }
            } catch (error) {
              console.error("Invalid URL:", targetUrl, error)
            }
          }
        })
      })
    </script>
  </body>
</html>

AI-Driven URL Navigation

Overview

How It Works

System Prompt Configuration

Recommended System Prompt

Alternative: Direct Navigation for Explicit Requests

Client-Side Implementation

Detecting and Handling URL Changes

Advanced Implementation with Confirmation

Navigation Options

Use Cases

1. Product Guidance

2. Lead Capture

3. Documentation Navigation

4. Checkout Flow

Best Practices

Do's

Don'ts

Security Considerations

URL Validation

CSP Considerations

Troubleshooting

URL Not Changing

Directive Visible in Response

Navigation Blocked by Browser

Complete Example

Overview​

How It Works​

System Prompt Configuration​

Recommended System Prompt​

Alternative: Direct Navigation for Explicit Requests​

Client-Side Implementation​

Detecting and Handling URL Changes​

Advanced Implementation with Confirmation​

Navigation Options​

Use Cases​

1. Product Guidance​

2. Lead Capture​

3. Documentation Navigation​

4. Checkout Flow​

Best Practices​

Do's​

Don'ts​

Security Considerations​

URL Validation​

CSP Considerations​

Troubleshooting​

URL Not Changing​

Directive Visible in Response​

Navigation Blocked by Browser​

Complete Example​

Overview

How It Works

System Prompt Configuration

Recommended System Prompt

Alternative: Direct Navigation for Explicit Requests

Client-Side Implementation

Detecting and Handling URL Changes

Advanced Implementation with Confirmation

Navigation Options

Use Cases

1. Product Guidance

2. Lead Capture

3. Documentation Navigation

4. Checkout Flow

Best Practices

Do's

Don'ts

Security Considerations

URL Validation

CSP Considerations

Troubleshooting

URL Not Changing

Directive Visible in Response

Navigation Blocked by Browser

Complete Example