Navigate Component

Overview

The Navigate component allows your agent to send users to specific pages on your website - perfect for directing to pricing, product pages, checkout, documentation, or any URL.

WebChat/LuaPop Only

This component only works with the website chat widget (LuaPop). It triggers the onNavigate callback you configure.

Deep Linking

Send users to any page on your site

Query Parameters

Pass data via URL parameters

Seamless UX

Navigation without leaving chat

Trackable

Know what users are clicking

Format

::: navigate
![navigate](pathname?param1=value1&param2=value2)
:::

Important: The Navigate component does not render visually in the chat. It triggers the onNavigate callback directly, causing immediate navigation. Users won’t see a button or link - they’ll be navigated automatically to the specified page.

Parts:

pathname - The page path (e.g., /pricing, /products/laptop, /checkout)
?param1=value1 - Optional query parameters

How It Works

Agent Uses Navigate Component

::: navigate
![navigate](/pricing?channel=web)
:::

Widget Calls onNavigate

onNavigate: (pathname, options) => {
  // pathname: "/pricing"
  // options: { query: { channel: "web" } }
}

Your Code Handles Navigation

// React Router
navigate(pathname, { state: options.query });

// Next.js
router.push({ pathname, query: options.query });

// Simple
window.location.href = pathname;

User Navigates

User is taken to the specified page

Examples

Navigate to Pricing Page

Agent Response:

Our pricing scales with your monthly expenses, starting at $300/month 
for companies under $30k in monthly spend, with a free 30-day trial 
and special YC founder discounts.

Here's the full breakdown:

::: navigate
![navigate](/pricing?channel=web)
:::

What happens:

No visual rendering - The navigate component does not display as a button or link. Instead, it immediately triggers the onNavigate callback and navigates the user to the specified page.

onNavigate called with:

onNavigate("/pricing", {
  query: { channel: "web" }
});

Navigate to Product Page

User: “Tell me more about the UltraBook Pro” Agent:

The UltraBook Pro is our premium laptop with 16GB RAM and 512GB SSD.
Perfect for developers and content creators.

See full specifications and reviews:

::: navigate
![navigate](/products/ultrabook-pro?source=chat)
:::

Screenshot: “View Product Details” button onNavigate called with:

onNavigate("/products/ultrabook-pro", {
  query: { source: "chat" }
});

Navigate to Checkout

Agent:

Perfect! I've added 2 items to your cart. Total: $149.98

Ready to complete your purchase?

::: navigate
![navigate](/checkout?items=2&total=149.98)
:::

Screenshot: “Proceed to Checkout” button onNavigate called with:

onNavigate("/checkout", {
  query: { items: "2", total: "149.98" }
});

Navigate to Documentation

Agent:

I can help you get started! Here's our comprehensive guide:

::: navigate
![navigate](/docs/getting-started?ref=chat)
:::

Navigate to Account Settings

Agent:

You can update your preferences in account settings:

::: navigate
![navigate](/account/settings?tab=preferences)
:::

Navigate to Order Status

Agent:

Your order #12345 is being processed. Track it here:

::: navigate
![navigate](/orders/12345?view=tracking)
:::

Complete Use Cases

E-commerce Example

persona: `
  You are a shopping assistant.
  
  When users ask about products, after providing info, 
  direct them to the product page:
  
  ::: navigate
  ![navigate](/products/PRODUCT_ID?source=chat)
  :::
  
  When ready to checkout:
  
  ::: navigate
  ![navigate](/checkout?from=chat)
  :::
  
  For pricing questions:
  
  ::: navigate
  ![navigate](/pricing?channel=chat)
  :::
`

Example conversation:

User: "Show me laptops"

Agent: We have several great options!

[Shows product list-items]

Want to see full details? Visit our laptop collection:

::: navigate
![navigate](/products/laptops?category=professional)
:::

SaaS Product Example

context: `
  When explaining features, link to documentation:
  
  ::: navigate
  ![navigate](/docs/FEATURE_NAME?ref=agent)
  :::
  
  For account issues:
  
  ::: navigate
  ![navigate](/account/settings?section=RELEVANT_SECTION)
  :::
  
  For billing questions:
  
  ::: navigate
  ![navigate](/billing?view=invoices)
  :::
`

Booking System Example

persona: `
  After showing available options, direct to booking page:
  
  ::: navigate
  ![navigate](/book?date=DATE&guests=COUNT)
  :::
  
  For viewing reservations:
  
  ::: navigate
  ![navigate](/reservations/CONFIRMATION_CODE)
  :::
`

Setup onNavigate Handler

window.LuaPop.init({
  agentId: "your-agent-id",
  position: "bottom-right",
  
  // Navigation handler
  onNavigate: (pathname, options) => {
    console.log('Navigate to:', pathname);
    console.log('Query params:', options.query);
    
    // Handle navigation based on your framework
  }
});

React Router

import { useNavigate } from 'react-router-dom';

function App() {
  const navigate = useNavigate();
  
  window.LuaPop.init({
    agentId: "your-agent-id",
    onNavigate: (pathname, options) => {
      // Navigate with query params
      navigate({
        pathname: pathname,
        search: new URLSearchParams(options.query).toString()
      });
    }
  });
}

Next.js Router

import { useRouter } from 'next/router';

export default function Layout() {
  const router = useRouter();
  
  useEffect(() => {
    window.LuaPop?.init({
      agentId: process.env.NEXT_PUBLIC_AGENT_ID,
      onNavigate: (pathname, options) => {
        router.push({
          pathname: pathname,
          query: options.query
        });
      }
    });
  }, [router]);
}

Vue Router

import { useRouter } from 'vue-router';

export default {
  setup() {
    const router = useRouter();
    
    window.LuaPop.init({
      agentId: process.env.VUE_APP_AGENT_ID,
      onNavigate: (pathname, options) => {
        router.push({
          path: pathname,
          query: options.query
        });
      }
    });
  }
}

window.LuaPop.init({
  agentId: "your-agent-id",
  onNavigate: (pathname, options) => {
    // Build URL with query params
    const params = new URLSearchParams(options.query);
    const url = pathname + (params.toString() ? '?' + params.toString() : '');
    
    // Navigate
    window.location.href = url;
  }
});

Query Parameters

Pass data through URL parameters:

::: navigate
![navigate](/products/laptop?source=chat&campaign=spring)
:::

Receives:

onNavigate("/products/laptop", {
  query: {
    source: "chat",
    campaign: "spring"
  }
});

Use cases:

Tracking: ?source=chat - Know users came from chat
Context: ?product=123 - Pre-fill forms
Campaigns: ?promo=SAVE10 - Auto-apply discounts
State: ?tab=specifications - Open specific tab
Filters: ?category=electronics&price=1000 - Pre-filter results

Advanced Examples

Navigate with User Context

::: navigate
![navigate](/products/recommendations?userId={{user.id}}&preferences={{user.preferences}})
:::

Navigate with Cart Data

::: navigate
![navigate](/checkout?items={{cart.itemCount}}&total={{cart.total}})
:::

Navigate with Search Query

User: "Show me running shoes"

Agent: Here are our running shoes:

::: navigate
![navigate](/search?q=running+shoes&category=footwear)
:::

Navigate with Booking Data

::: navigate
![navigate](/book?checkIn=2025-10-15&checkOut=2025-10-17&guests=2&room=deluxe)
:::

Best Practices

✅ Descriptive Button Text

The widget generates button text from context:

::: navigate
![navigate](/pricing)
:::

Becomes: "View Pricing" or "See Pricing Details"

Provide context before the component so widget can generate appropriate text.

✅ Include Query Parameters

✅ Good:
![navigate](/products/laptop?source=chat&ref=agent)

Why: You can track that users came from chat

✅ Use Relative Paths

✅ Good:
![navigate](/pricing)
![navigate](/products/123)

❌ Bad:
![navigate](https://yoursite.com/pricing)

Relative paths work better with onNavigate

✅ Test Navigation

// Test your onNavigate handler
onNavigate: (pathname, options) => {
  console.log('Would navigate to:', pathname);
  console.log('With params:', options.query);
  
  // Verify it works before deploying
}

How to Configure

In Persona

persona: |
  You are a sales assistant for our e-commerce site.
  
  When discussing products, direct users to product pages:
  
  ::: navigate
  ![navigate](/products/PRODUCT_SLUG?source=chat)
  :::
  
  For pricing questions:
  
  ::: navigate
  ![navigate](/pricing?channel=web)
  :::
  
  When user is ready to buy:
  
  ::: navigate
  ![navigate](/checkout?from=chat)
  :::
  
  Always include source=chat parameter for tracking.

In Skill Context

const ecommerceSkill = new LuaSkill({
  context: `
    After showing products, direct to product page:
    
    ::: navigate
    ![navigate](/products/{{product.slug}}?ref=agent)
    :::
    
    After adding to cart:
    
    ::: navigate
    ![navigate](/cart?action=review)
    :::
    
    For checkout:
    
    ::: navigate
    ![navigate](/checkout?items={{itemCount}})
    :::
  `
});

Troubleshooting

Navigation not working

Query parameters not received

Format:

✅ Correct:
![navigate](/page?param1=value1&param2=value2)

❌ Wrong:
![navigate](/page?param1=value1?param2=value2)

Agent not using navigate

Cause: Not instructed in persona/contextSolution: Add explicit navigate instructions with examples

Complete Example: E-commerce Agent

import { useRouter } from 'next/router';

window.LuaPop.init({
  agentId: "ecommerce-agent",
  position: "bottom-right",
  
  onNavigate: (pathname, options) => {
    // Track navigation event
    analytics.track('chat_navigation', {
      path: pathname,
      params: options.query
    });
    
    // Navigate using Next.js router
    router.push({
      pathname: pathname,
      query: options.query
    });
  }
});

Persona Configuration

persona: |
  You are a shopping assistant for TechStore.
  
  NAVIGATION GUIDELINES:
  
  When users ask about products:
  - Show product info
  - Direct to product page: ![navigate](/products/SLUG?source=chat)
  
  When discussing pricing:
  - Explain pricing tiers
  - Link to pricing: ![navigate](/pricing?channel=chat)
  
  When cart questions:
  - Summarize cart
  - Link to cart: ![navigate](/cart?action=review)
  
  When ready to checkout:
  - Confirm items
  - Link to checkout: ![navigate](/checkout?from=agent)
  
  Example response:
  "The UltraBook Pro is $1,299 with free shipping. 
  
  See full specs and reviews:
  
  ::: navigate
  ![navigate](/products/ultrabook-pro?source=chat&ref=agent)
  :::"

Example Conversation

User: "How much does the UltraBook Pro cost?"

Agent:
The UltraBook Pro is $1,299.00 with free 2-day shipping.

It includes:
- 16GB RAM
- 512GB SSD
- 14" Retina Display
- 12-hour battery life

See full specifications and customer reviews:

::: navigate
![navigate](/products/ultrabook-pro?source=chat)
:::

[User clicks button]
[onNavigate called: ("/products/ultrabook-pro", { query: { source: "chat" } })]
[User navigated to product page]
[Chat widget minimizes or stays open based on your implementation]


User: "What's your return policy?"

Agent:
We offer a 45-day return policy with free return shipping.

View our complete return policy and start a return:

::: navigate
![navigate](/policies/returns?ref=agent)
:::


User: "I'm ready to buy"

Agent:
Great! I've added the UltraBook Pro to your cart.

Review your cart and complete checkout:

::: navigate
![navigate](/checkout?product=ultrabook-pro&quantity=1)
:::

1. Product Discovery

User asks about products
  ↓
Agent describes product
  ↓
::: navigate
![navigate](/products/PRODUCT_ID?source=chat)
:::

2. Pricing Inquiry

User asks about pricing
  ↓
Agent explains pricing tiers
  ↓
::: navigate
![navigate](/pricing?channel=chat)
:::

3. Documentation Request

User asks "how do I..."
  ↓
Agent provides quick answer
  ↓
::: navigate
![navigate](/docs/TOPIC?ref=agent)
:::

4. Account Management

User needs to update settings
  ↓
Agent explains what to change
  ↓
::: navigate
![navigate](/account/settings?section=SETTING)
:::

5. Support Resources

User has issue
  ↓
Agent provides solution
  ↓
::: navigate
![navigate](/support/ISSUE_CATEGORY?from=chat)
:::

Tracking & Analytics

window.LuaPop.init({
  agentId: "your-agent-id",
  onNavigate: (pathname, options) => {
    // Google Analytics
    gtag('event', 'agent_navigation', {
      path: pathname,
      source: options.query.source,
      channel: options.query.channel
    });
    
    // Mixpanel
    mixpanel.track('Agent Navigation', {
      pathname,
      query: options.query
    });
    
    // Your analytics
    fetch('/api/analytics', {
      method: 'POST',
      body: JSON.stringify({
        event: 'chat_navigation',
        pathname,
        query: options.query,
        timestamp: new Date()
      })
    });
    
    // Then navigate
    router.push({ pathname, query: options.query });
  }
});

A/B Testing with Navigate

onNavigate: (pathname, options) => {
  // Add experiment tracking
  const params = {
    ...options.query,
    experiment: 'chat_nav_v2',
    variant: getUserVariant()
  };
  
  router.push({
    pathname,
    query: params
  });
}

Combine with Actions component:

::: list-item
![image](product.jpg)
#UltraBook Pro
##$1,299 - In Stock
Professional laptop with amazing specs.
:::

::: actions
- Add to Cart
- View Details
- Compare Similar
:::

::: navigate
![navigate](/products/ultrabook-pro?source=chat&action=view)
:::

Screenshot: List item + actions + navigate button together

Best Practices

✅ Provide Context Before Navigate

✅ Good:
"Our pricing starts at $300/month. Here's the full breakdown:"
::: navigate
![navigate](/pricing)
:::

❌ Bad:
::: navigate
![navigate](/pricing)
:::
(No context about what they'll see)

✅ Use Descriptive Paths

✅ Good:
/products/ultrabook-pro
/pricing/enterprise
/docs/getting-started

❌ Bad:
/p/123
/page1
/info

✅ Include Tracking Parameters

Always add source tracking:
![navigate](/page?source=chat&ref=agent)

Helps you measure:
- How many users click
- Which pages are popular
- Conversion from chat

✅ Handle Navigation Gracefully

onNavigate: (pathname, options) => {
  // Validate path exists
  if (validPaths.includes(pathname)) {
    router.push({ pathname, query: options.query });
  } else {
    console.error('Invalid path:', pathname);
    // Fallback to home or show error
  }
}

Troubleshooting

Button doesn't navigate

Check:

onNavigate is defined in widget init
Console for JavaScript errors
Pathname is valid
Router is properly configured

Query parameters missing

Debug:

onNavigate: (pathname, options) => {
  console.log('Pathname:', pathname);
  console.log('Query:', options.query);
  // Verify query object has expected keys
}

Agent not using navigate

Solution:

lua persona → Edit
# Add explicit navigate instructions
# Show format examples
# Test with lua chat

Summary

No Visual Render

Doesn’t display as button - triggers navigation immediately

WebChat Only

Only works with LuaPop widget

onNavigate Required

Must configure handler

Query Params

Pass data via URL

Trackable

Analytics integration

Next Steps

Widget Configuration

Set up onNavigate handler

Configure Persona

Add navigate instructions

Actions Component

Combine with other components

Widget Events

Learn about all widget events

Getting Started

Configuration

Integration

Features

Help

​Overview

WebChat/LuaPop Only

Deep Linking

Query Parameters

Seamless UX

Trackable

​Format

​How It Works

​Examples

​Navigate to Pricing Page

​Navigate to Product Page

​Navigate to Checkout

​Navigate to Documentation

​Navigate to Account Settings

​Navigate to Order Status

​Complete Use Cases

​E-commerce Example

​SaaS Product Example

​Booking System Example

​Widget Configuration

​Setup onNavigate Handler

​React Router

​Next.js Router

​Vue Router

​Simple Navigation

​Query Parameters

​Advanced Examples

​Navigate with User Context

​Navigate with Cart Data

​Navigate with Search Query

​Navigate with Booking Data

​Best Practices

​How to Configure

​In Persona

​In Skill Context

​Troubleshooting

​Complete Example: E-commerce Agent

​Widget Setup

​Persona Configuration

​Example Conversation

​Common Navigation Patterns

​1. Product Discovery

​2. Pricing Inquiry

​3. Documentation Request

​4. Account Management

​5. Support Resources

​Tracking & Analytics

​Track Navigation Events

​A/B Testing with Navigate

​Multiple Navigation Options

​Best Practices

​Troubleshooting

​Summary

No Visual Render

WebChat Only

onNavigate Required

Query Params

Trackable

​Next Steps

Widget Configuration

Configure Persona

Actions Component

Widget Events

Overview

Format

How It Works

Examples

Navigate to Pricing Page

Navigate to Product Page

Navigate to Checkout

Navigate to Documentation

Navigate to Account Settings

Navigate to Order Status

Complete Use Cases

E-commerce Example

SaaS Product Example

Booking System Example

Widget Configuration

Setup onNavigate Handler

React Router

Next.js Router

Vue Router

Simple Navigation

Query Parameters

Advanced Examples

Navigate with User Context

Navigate with Cart Data

Navigate with Search Query

Navigate with Booking Data

Best Practices

How to Configure

In Persona

In Skill Context

Troubleshooting

Complete Example: E-commerce Agent

Widget Setup

Persona Configuration

Example Conversation

Common Navigation Patterns

1. Product Discovery

2. Pricing Inquiry

3. Documentation Request

4. Account Management

5. Support Resources

Tracking & Analytics

Track Navigation Events

A/B Testing with Navigate

Multiple Navigation Options

Best Practices

Troubleshooting

Summary

Next Steps