Published on

How to Use contextVariables in Your Chatbot Prompt

Authors

A chatbot becomes much more useful when it knows a little bit about the page, visitor, or account it is helping with.

That does not mean you need to create a different chatbot for every page. With Predictable Dialogs, you can pass dynamic values into the widget using contextVariables, then reference those values in your chatbot's system instructions with {{variableName}} placeholders.

For example, your website can pass:

contextVariables: {
  name: 'Jai',
  plan: 'Pro',
  currentPage: 'pricing',
}

Then your chatbot instructions can say:

The visitor's name is {{name}}.
The visitor is currently on the {{currentPage}} page.
The visitor's plan is {{plan}}.

At runtime, the widget sends those values with the session, and Predictable Dialogs uses them when preparing the chatbot instructions.

The official widget docs cover this option for the Standard widget, Popup widget, and Bubble widget. The FAQ also includes short examples for greeting users by name and passing custom variables into instructions.

What contextVariables Is For

Use contextVariables when your chatbot should adapt to the current session.

Good examples include:

  • The visitor's name.
  • The page the visitor is currently viewing.
  • The user's plan or account tier.
  • The user's locale or preferred language.
  • A product, category, or workspace ID from your app.
  • Whether the visitor is logged in.

The value should be a simple object. The documented type is:

Record<string, string | number | boolean>

Every key can be referenced in your system instructions with the same name inside double curly braces. If you pass currentPage, write {{currentPage}} in the prompt.

Using contextVariables in a React App

If you are using React, install and use the Predictable Dialogs React package. The React integration guide walks through the basic setup here: How to Implement an OpenAI Chatbot in React.

Once the widget is installed, pass contextVariables as a prop.

import React from 'react'
import { Standard } from '@agent-embed/react'

export default function SupportChat({ currentUser }) {
  const contextVariables = {
    name: currentUser?.name || 'visitor',
    plan: currentUser?.plan || 'free',
    loggedIn: Boolean(currentUser),
    currentPage: window.location.pathname,
  }

  return (
    <Standard
      agentName="Support Assistant"
      contextVariables={contextVariables}
      style={{ width: '100%', height: '600px' }}
    />
  )
}

You can use the same idea with Popup or Bubble from @agent-embed/react. The important part is that the keys you pass in React match the placeholders you write in the chatbot instructions.

For example:

Session facts:
- Logged in: {{loggedIn}}
- Visitor name: {{name}}
- Current page: {{currentPage}}
- Plan: {{plan}}

Use the "Logged in" value as a boolean.
When it is true, greet the user by name if the visitor name is not "visitor".
When it is false, greet the visitor normally and do not claim to know their account.
Use the current page and plan only when they are relevant to the user's question.

Using contextVariables in Plain JavaScript

For a regular HTML or JavaScript website, import the widget from the CDN and pass contextVariables during initialization.

If you have not added the widget before, start with the HTML/JavaScript setup guide: Adding an OpenAI Chatbot to HTML.

Here is a standard widget example:

<script type="module">
  import Agent from 'https://cdn.jsdelivr.net/npm/@agent-embed/js@latest/dist/web.js'

  Agent.initStandard({
    agentName: 'Support Assistant',
    contextVariables: {
      currentPage: window.location.pathname,
      pageTitle: document.title,
      referrer: document.referrer || 'direct',
      loggedIn: Boolean(window.currentUser),
      name: window.currentUser?.name || 'visitor',
    },
  })
</script>

<agent-standard style="width: 100%; height: 600px;"></agent-standard>

For a popup widget, the same option goes inside Agent.initPopup. The popup widget docs explain the other popup configuration options here: Popup widget documentation.

<script type="module">
  import Agent from 'https://cdn.jsdelivr.net/npm/@agent-embed/js@latest/dist/web.js'

  Agent.initPopup({
    agentName: 'Website Welcomer',
    autoShowDelay: 3000,
    contextVariables: {
      name: window.currentUser?.name || 'visitor',
      currentPage: window.location.pathname,
      locale: navigator.language,
    },
  })
</script>

This is useful for product pages, pricing pages, onboarding flows, logged-in dashboards, and support pages where the same chatbot should behave slightly differently depending on where the user is.

Using contextVariables in WordPress

For WordPress, start with the normal WordPress setup first. This guide explains both supported paths: How to Connect a Predictable Dialogs AI Agent to WordPress.

Most WordPress sites should use the Predictable Dialogs WordPress plugin first. The plugin is the easiest way to connect an agent, choose a widget type, and control the widget from inside WordPress.

When you need to pass custom contextVariables, use one of these advanced paths:

  1. Open the plugin's manual initialization snippet and add the contextVariables object there.
  2. Copy the embed code from Predictable Dialogs and paste it into a Custom HTML block, theme template, or snippet plugin that supports script tags.

For example:

<script type="module">
  import Agent from 'https://cdn.jsdelivr.net/npm/@agent-embed/js@latest/dist/web.js'

  Agent.initBubble({
    agentName: 'WordPress Site Assistant',
    contextVariables: {
      pageTitle: document.title,
      currentPage: window.location.pathname,
      loggedIn: document.body.classList.contains('logged-in'),
      source: 'wordpress',
    },
  })
</script>

If your WordPress theme exposes more data to JavaScript, you can pass that too. For example, your theme or snippet plugin might define window.pdVisitorContext before the chatbot loads:

<script>
  window.pdVisitorContext = {
    membershipLevel: 'gold',
    preferredTopic: 'billing',
  }
</script>

<script type="module">
  import Agent from 'https://cdn.jsdelivr.net/npm/@agent-embed/js@latest/dist/web.js'

  Agent.initBubble({
    agentName: 'WordPress Site Assistant',
    contextVariables: {
      pageTitle: document.title,
      currentPage: window.location.pathname,
      membershipLevel: window.pdVisitorContext?.membershipLevel || 'unknown',
      preferredTopic: window.pdVisitorContext?.preferredTopic || 'general',
    },
  })
</script>

The Bubble, Popup, and Standard widgets all support contextVariables. You can compare the widget options in the official widget documentation.

How to Write Your Prompt

Passing contextVariables is only half of the work. The chatbot also needs instructions that use those values clearly.

Here is a practical system prompt template:

You are the support assistant for COMPANY_NAME.

Session context:
- Visitor name: {{name}}
- Current page: {{currentPage}}
- Account plan: {{plan}}
- Locale: {{locale}}
- Logged in: {{loggedIn}}

Use the session context to make the conversation more relevant.

Rules:
1. If the visitor name is available and is not "visitor", greet the user by name.
2. Use the current page to infer what the user is likely trying to do, but do not pretend the user asked about that page unless it is relevant.
3. If the account plan is available, tailor plan-specific guidance to that plan.
4. Use the "Logged in" value as a boolean. When it is false, avoid mentioning private account details.
5. If any context value looks missing or generic, continue naturally without calling attention to it.

You can make the prompt more specific for your use case. For a pricing assistant:

The visitor is currently on {{currentPage}} and their known plan is {{plan}}.
If they ask about pricing, compare options against their current plan.
If their plan is "free", explain the upgrade path.
If their plan is "enterprise", recommend contacting support for account-specific pricing.

For an onboarding chatbot, you can combine this with the prompt pattern from AI Chatbots as Website Onboarding UI, which already shows a simple popup widget using contextVariables: { name: 'Jai' }.

Best Practices

Keep variable names obvious. currentPage is easier to maintain than cp, and membershipLevel is clearer than level.

Pass only context that helps the chatbot answer better. Page, plan, locale, and logged-in state are usually useful. Large objects, private tokens, and sensitive account data should not be passed unless the chatbot genuinely needs them.

Write prompts that degrade gracefully. The docs note that missing properties leave placeholders unchanged, so your instructions should not depend on every value always being present.

Use strings, numbers, and booleans. If you need to pass richer data, reduce it to the specific value the chatbot needs, such as selectedProduct: 'Starter CRM' instead of a full product object.

Quick Checklist

Before you publish:

  1. Decide which values the chatbot needs.
  2. Pass those values in contextVariables when initializing the widget.
  3. Use matching {{variableName}} placeholders in your Predictable Dialogs system instructions.
  4. Test the chatbot on pages where the values change.
  5. Check the session in Predictable Dialogs to confirm the expected context was stored.

For the full list of widget options, use the official docs for Standard, Popup, and Bubble.