QR Code Query Parameter Launch

This guide demonstrates how to create QR codes that automatically launch your ai12z bot with predefined messages. This feature allows you to create targeted marketing campaigns, event-specific interactions, and context-aware bot experiences through QR codes that visitors can scan with their mobile devices.

Overview

The QR code query parameter feature enables you to:

Create QR codes that open your website with specific bot queries
Launch the bot automatically with predefined messages
Provide context-aware responses based on QR code content
Create targeted marketing campaigns and event-specific interactions
Enhance user experience with instant, relevant information

Use Cases

Event Information: QR codes on posters that ask "Tell me about tonight's performance"
Product Details: QR codes on products that query specific information
Location Services: QR codes in venues that provide location-specific help
Marketing Campaigns: Targeted QR codes for different audience segments
Emergency Information: Quick access to important information or support

How It Works

When a user scans a QR code, they're directed to your website with a query parameter. The page detects this parameter and automatically:

Opens the ai12z bot
Sends the predefined message to the bot
Displays the relevant response to the user

Implementation Guide

Step 1: Create the Landing Page

Create an HTML page that can handle query parameters and launch your bot:

<!doctype html>
<html>
  <head>
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, maximum-scale=1"
    />
    <title>Riverside Center for the Arts</title>

    <!-- Load the AI12Z bot library and styles -->
    <script
      type="module"
      src="https://cdn.ai12z.net/pkg/ai12z@next/dist/esm/library.js?ver=18"
    ></script>
    <link
      rel="stylesheet"
      href="https://cdn.ai12z.net/pkg/ai12z@next/dist/library/library.css?ver=18"
    />

    <link rel="icon" type="image/png" href="img/eventf.png" />

    <style>
      /* Custom styling for your page */
      body {
        background-image: url("img/riverside.jpg");
        background-repeat: no-repeat;
        background-size: 1387px 1135px;
        margin: 0;
        padding: 0;
        font-family: Arial, sans-serif;
      }

      /* Optional: Add custom buttons for manual interaction */
      .action-button {
        position: fixed;
        top: 70px;
        left: 185px;
        background-color: #8b0000;
        color: white;
        border: none;
        padding: 12px 20px;
        font-size: 16px;
        font-weight: bold;
        border-radius: 8px;
        cursor: pointer;
        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
        transition: background-color 0.3s;
        z-index: 1000;
      }

      .action-button:hover {
        background-color: #a52a2a;
      }

      /* Mobile responsive adjustments */
      @media (max-width: 768px) {
        .action-button {
          position: relative;
          top: 20px;
          left: 20px;
          margin: 20px;
        }

        body {
          background-size: cover;
          background-position: center;
        }
      }
    </style>
  </head>
  <body>
    <!-- Optional: Manual action buttons -->
    <button class="action-button" onclick="showBroadwayShows()">
      Show Upcoming Broadway Shows
    </button>

    <!-- AI12Z Bot Element -->
    <ai12z-bot data-key="your-api-key" data-mode="prod"> </ai12z-bot>

    <script>
      // Function to extract URL parameters
      function getQueryParam(param) {
        const urlParams = new URLSearchParams(window.location.search)
        return urlParams.get(param)
      }

      // Get the query from URL parameter
      const userQuery = getQueryParam("query")

      // Function to open bot with URL parameter query
      async function openBot() {
        try {
          // Wait for the ai12z-bot custom element to be defined
          await customElements.whenDefined("ai12z-bot")
          const botElement = document.querySelector("ai12z-bot")

          // Open the bot (not expanded to show in overlay mode)
          await botElement.action("open", { expanded: false })

          // Send the decoded query message
          botElement.sendMessage(decodeURIComponent(userQuery))

          // Optional: Set data attributes for context
          botElement.dataAttributes = {
            source: "qr-code",
            query: userQuery,
          }
        } catch (error) {
          console.error("Error opening bot with query:", error)
        }
      }

      // Function for manual button interactions
      async function showBroadwayShows() {
        try {
          await customElements.whenDefined("ai12z-bot")
          const botElement = document.querySelector("ai12z-bot")
          await botElement.action("open", { expanded: false })
          botElement.sendMessage("Show upcoming broadway shows")
        } catch (error) {
          console.error("Error opening bot for Broadway shows:", error)
        }
      }

      // Auto-launch bot when page loads with query parameter
      document.addEventListener("DOMContentLoaded", function () {
        if (userQuery) {
          console.log("QR Code query detected:", userQuery)
          openBot()
        }
      })
    </script>
  </body>
</html>

Step 2: Create QR Code URLs

Generate URLs with query parameters that will trigger specific bot responses:

Basic URL Structure

https://your-website.com/bot-page.html?query=YOUR_ENCODED_MESSAGE

Example URLs for Different Use Cases

Event Information:

https://bot.ai12z.net/public/riverside.html?query=Tell%20me%20about%20upcoming%20events

Box Office Hours:

https://bot.ai12z.net/public/riverside.html?query=What%20are%20your%20box%20office%20hours%3F

Parking Information:

https://bot.ai12z.net/public/riverside.html?query=Where%20can%20I%20park%20for%20the%20show%3F

Accessibility Services:

https://bot.ai12z.net/public/riverside.html?query=What%20accessibility%20services%20do%20you%20offer%3F

Step 3: Generate QR Codes

You can use various tools to generate QR codes:

Online QR Code Generators

QR Code Generator (qr-code-generator.com)
QRStuff (qrstuff.com)
Google Charts API
Adobe Express QR Code Generator

Programmatic Generation

// Using a QR code library like qrcode.js
const QRCode = require("qrcode")

const generateQRCode = async (message, filename) => {
  const encodedMessage = encodeURIComponent(message)
  const url = `https://your-website.com/bot?query=${encodedMessage}`

  try {
    await QRCode.toFile(filename, url)
    console.log(`QR code generated: ${filename}`)
  } catch (error) {
    console.error("Error generating QR code:", error)
  }
}

// Generate QR codes for different messages
generateQRCode("Tell me about tonight's performance", "event-info-qr.png")
generateQRCode("What are your box office hours?", "hours-qr.png")
generateQRCode("Where can I park?", "parking-qr.png")

Step 4: URL Encoding Reference

When creating URLs with query parameters, special characters must be encoded:

Character	Encoded
Space	%20
?	%3F
&	%26
'	%27
"	%22
#	%23
%	%25

Encoding Tools

JavaScript: encodeURIComponent(message)
Online: Search "URL encoder" for web tools
Programming: Most languages have built-in URL encoding functions

Advanced Features

Multiple Query Parameters

You can pass additional context through multiple parameters:

// Enhanced parameter extraction
function getQueryParams() {
  const urlParams = new URLSearchParams(window.location.search)
  return {
    query: urlParams.get("query"),
    source: urlParams.get("source"),
    campaign: urlParams.get("campaign"),
    lang: urlParams.get("lang"),
  }
}

// Enhanced bot opening with multiple parameters
async function openBotWithContext() {
  const params = getQueryParams()

  try {
    await customElements.whenDefined("ai12z-bot")
    const botElement = document.querySelector("ai12z-bot")

    // Set language if specified
    if (params.lang) {
      botElement.dataAttributes = { lang: params.lang }
    }

    await botElement.action("open", { expanded: false })

    if (params.query) {
      botElement.sendMessage(decodeURIComponent(params.query))
    }

    // Track campaign source
    if (params.campaign) {
      console.log("Campaign source:", params.campaign)
      // Send analytics data
    }
  } catch (error) {
    console.error("Error opening bot:", error)
  }
}

Example URL with multiple parameters:

https://your-site.com/bot?query=Show%20events&source=qr&campaign=summer2025&lang=es

Conditional Bot Behavior

Customize bot behavior based on the query source:

async function openBot() {
  const params = getQueryParams()

  try {
    await customElements.whenDefined("ai12z-bot")
    const botElement = document.querySelector("ai12z-bot")

    // Different behavior for QR code vs. direct visits
    if (params.source === "qr") {
      // Open in overlay mode for QR code users
      await botElement.action("open", { expanded: false })
    } else {
      // Open expanded for direct visitors
      await botElement.action("open", { expanded: true })
    }

    if (params.query) {
      // Add context for QR code queries
      const contextMessage =
        params.source === "qr"
          ? `QR Code Query: ${decodeURIComponent(params.query)}`
          : decodeURIComponent(params.query)

      botElement.sendMessage(contextMessage)
    }

    // Set tracking attributes
    botElement.dataAttributes = {
      source: params.source || "direct",
      campaign: params.campaign || "none",
      timestamp: new Date().toISOString(),
    }
  } catch (error) {
    console.error("Error opening bot:", error)
  }
}

QR Code Design Best Practices

Visual Design

High Contrast: Use dark QR code on light background
Sufficient Size: Minimum 2cm x 2cm for reliable scanning
Quiet Zone: Leave white space around the QR code
Call to Action: Add "Scan for info" text near the QR code

Content Strategy

Clear Messaging: Make the query specific and actionable
Value Proposition: Explain what users will get by scanning
Context Aware: Tailor messages to the physical location/situation
Language Consideration: Use appropriate language for your audience

Technical Considerations

Error Correction: Use Medium or High error correction levels
Testing: Test QR codes on multiple devices and apps
URL Length: Keep URLs reasonably short for faster scanning
Mobile Optimization: Ensure your landing page is mobile-friendly

Use Case Examples

Theater/Arts Venue

Event Poster QR Code:

https://riverside-arts.com/bot?query=Tell%20me%20about%20today%27s%20show%20times%20and%20ticket%20availability&source=qr&campaign=poster

Lobby Information:

https://riverside-arts.com/bot?query=I%27m%20here%20for%20tonight%27s%20show%2C%20what%20do%20I%20need%20to%20know%3F&source=qr&location=lobby

Restaurant

Table QR Code:

https://restaurant.com/bot?query=Show%20me%20today%27s%20specials%20and%20help%20me%20order&source=qr&table=12

Menu QR Code:

https://restaurant.com/bot?query=I%20have%20dietary%20restrictions%2C%20what%20options%20do%20you%20have%3F&source=qr&location=menu

Retail Store

Product Information:

https://store.com/bot?query=Tell%20me%20about%20this%20product%27s%20features%20and%20warranty&source=qr&product=SKU123

Customer Service:

https://store.com/bot?query=I%20need%20help%20with%20a%20return%20or%20exchange&source=qr&location=service-desk

Analytics and Tracking

Track QR Code Performance

Monitor QR code effectiveness through URL parameters:

// Track QR code scans
document.addEventListener("DOMContentLoaded", function () {
  const params = getQueryParams()

  if (params.source === "qr") {
    // Send analytics event
    if (typeof gtag !== "undefined") {
      gtag("event", "qr_code_scan", {
        campaign: params.campaign || "unknown",
        query: params.query || "none",
        timestamp: new Date().toISOString(),
      })
    }

    // Custom analytics
    fetch("/api/track-qr-scan", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        campaign: params.campaign,
        query: params.query,
        timestamp: new Date().toISOString(),
        userAgent: navigator.userAgent,
      }),
    })
  }
})

A/B Testing QR Codes

Test different queries and campaigns:

// A/B test different QR code messages
const testVariants = {
  a: "Tell me about tonight's show",
  b: "What shows are playing tonight?",
  c: "I want to see a show tonight",
}

// URL: ...?query=test&variant=a&campaign=poster-test
const params = getQueryParams()
if (params.query === "test" && params.variant) {
  const testQuery = testVariants[params.variant]
  if (testQuery) {
    // Use test query instead
    openBotWithMessage(testQuery)

    // Track variant performance
    trackVariant(params.variant, params.campaign)
  }
}

Troubleshooting

Common Issues

QR Code Not Scanning:

Ensure sufficient contrast and size
Test with multiple QR code reader apps
Check for damage or distortion

Bot Not Opening:

Verify the ai12z library is loaded correctly
Check browser console for JavaScript errors
Ensure the bot element is properly configured

Query Not Working:

Verify URL encoding is correct
Check that special characters are properly encoded
Test the URL directly in a browser

Mobile Display Issues:

Ensure viewport meta tag is present
Test responsive design on various devices
Optimize page load speed for mobile networks

Debug Script

Add this debug script to troubleshoot issues:

// Debug QR code functionality
document.addEventListener("DOMContentLoaded", function () {
  const params = getQueryParams()

  console.group("QR Code Debug Info")
  console.log("Full URL:", window.location.href)
  console.log("Query parameter:", params.query)
  console.log(
    "Decoded query:",
    params.query ? decodeURIComponent(params.query) : "None"
  )
  console.log("Source:", params.source)
  console.log("Campaign:", params.campaign)
  console.log("Bot element present:", !!document.querySelector("ai12z-bot"))
  console.groupEnd()

  // Test bot functionality
  if (params.query) {
    console.log("Attempting to open bot with query...")
    openBot()
      .then(() => {
        console.log("Bot opened successfully")
      })
      .catch((error) => {
        console.error("Failed to open bot:", error)
      })
  }
})

This QR code implementation provides a seamless way to bridge physical and digital interactions, allowing users to instantly access relevant information through their mobile devices while providing you with valuable analytics about user engagement.

Overview​

Use Cases​

How It Works​

Implementation Guide​

Step 1: Create the Landing Page​

Step 2: Create QR Code URLs​

Basic URL Structure​

Example URLs for Different Use Cases​

Step 3: Generate QR Codes​

Online QR Code Generators​

Programmatic Generation​

Step 4: URL Encoding Reference​

Encoding Tools​

Advanced Features​

Multiple Query Parameters​

Conditional Bot Behavior​

QR Code Design Best Practices​

Visual Design​

Content Strategy​

Technical Considerations​

Use Case Examples​

Theater/Arts Venue​

Restaurant​

Retail Store​

Analytics and Tracking​

Track QR Code Performance​

A/B Testing QR Codes​

Troubleshooting​

Common Issues​

Debug Script​