Administrator Guide

Agent Configuration

Configure web agents, Q&A pairs, info fields, offers, and website engineering APIs in YouEx.ai.

Agent Configuration

The Agents page is where you create and manage web agents.

Your Web Agent is the front door of your revenue workflow. It's what captures inbound leads from your website and kicks off the automated research, scoring, and routing that follows.

Once it's live, every conversation the agent has will create a new lead, trigger research, and surface hot leads it in your seller inbox — no manual work required.

Pro tip: Create separate agents for different entry points — your homepage, pricing page, and contact page often attract different types of visitors with different intent levels. Here's how to get your first one up and running in 3 steps and 5 minutes:

Setting up your agent

When you create a new agent, you'll fill in a handful of settings that control how it looks and behaves. The basics are straightforward — give it a name, write a welcome message, and set a system prompt that describes how you want it to handle conversations. You can also add conversation starters (suggested questions visitors can tap) and restrict which domains the agent is allowed to appear on.

Q&A pairs — for answers that can't drift

Some questions need an exact, consistent answer every time — pricing disclaimers, privacy requests, support redirects, policy questions. Q&A pairs are how you handle those. Think of them as hardcoded responses that always fire before the AI has a chance to improvise. Use them sparingly, but use them for anything where the wording actually matters.

Info fields — what you want to collect

Info fields tell the agent what to ask visitors. This is how you capture lead details, qualify prospects, gate content behind a form, or collect the information needed before booking a meeting. Set up the fields you need and the agent handles the rest — it knows when and how to ask without being pushy about it.

Offers — what happens after they engage

Once a visitor has shared enough useful information, you can have the agent present an offer — a download, a link, a promo code, or a consultation booking. Offers are the natural payoff at the end of a productive conversation.

Proactive messages (Beckons)

Beckons are short invitations that appear near the collapsed chat on specific website pages. Enable them on the agent, then author page-specific messages under Knowledge via the megaphone button on each web page.

See Proactive messages (Beckons) for the full setup guide.

A few things worth keeping in mind:

Your system prompt should focus on how the agent behaves, not what it knows. For facts about your product, use the knowledge base — that's what it's there for. For anything where you need word-for-word consistency, use Q&A pairs. And always test after making significant changes before you push anything live.

Website Engineering

Use this section when you’re embedding an agent on your own site or wiring CTAs/forms to open the chat with context. Copy the deploy snippet from Agent Manager → Deploy, then customize as needed.

Where to put the embed snippet

Load the widget script in your site <head> (recommended) or early in <body>, so window.YouExWidget is available before your init code runs.
Call YouExWidget.create({ ... }) after the script loads — often in a small script near the end of <body>, or right after the script tag if you prefer.
For a hero / inline agent, place an empty mount element in the page where the chat should appear, and pass that element’s id as mountId.

Allow your domain in the agent’s deploy settings before going live. Use the exact script URL from Deploy if yours differs from the example below.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://engage.youex.ai/embed/youex-widget.js"></script>
  </head>
  <body>
    <!-- your page content -->

    <script>
      window.YouExWidget.create({
        agentId: "YOUR_AGENT_ID",
        apiBaseUrl: "https://engage.youex.ai",
        placement: "popup",
        position: "bottom-right",
        launcherStyle: "prompt",
        launcherText: "Hey there... ask me anything!",
        width: "700px",
        height: "600px",
        primaryColor: "#00B4D8",
        secondaryColor: "#9333EA",
      });
    </script>
  </body>
</html>

Hero / inline mount (`mountId`)

For hero placement, the agent renders inside a page element instead of floating over the site.

Add an empty container where the chat should appear: <div id="hero-chat"></div>
Set placement: "hero" and mountId: "hero-chat" (use whatever id you chose)
Put the mount element in the DOM before calling create(). If mountId isn’t found, the widget logs a warning and falls back to document.body.
position is ignored for hero placement — size the chat with width, height, and optionally heroMaxHeight.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://engage.youex.ai/embed/youex-widget.js"></script>
  </head>
  <body>
    <div id="hero-chat"></div>

    <script>
      window.YouExWidget.create({
        agentId: "YOUR_AGENT_ID",
        apiBaseUrl: "https://engage.youex.ai",
        placement: "hero",
        mountId: "hero-chat",
        launcherText: "Ask me anything",
        width: "100%",
        height: "520px",
        heroMaxHeight: "720px",
        primaryColor: "#00B4D8",
        secondaryColor: "#9333EA",
      });
    </script>
  </body>
</html>

Configuration options

agentId — Your agent's unique identifier (required)
apiBaseUrl — The API server URL (use your deployed app URL)
placement — Panel placement: "popup", "pinned", or "hero"
pinnedAutoOpen — Optional. When true with pinned placement, opens the side panel on page load.
position — Widget position: "bottom-right", "bottom-left", "bottom-center", "top-right", "top-left", "top-center" (ignored for hero)
launcherStyle — Launcher style: "icon", "search", or "prompt"
mountId — DOM element id to mount inline (optional)
chatBackgroundColor — Panel background (hex or CSS color)
chatAccentColor — Borders and separators (hex or CSS color)
chatTextColor — Optional assistant message text color
chatLinkColor — Optional assistant link color (defaults to primary brand color)
promptTheme — Prompt card theme: "dark" or "light"
launcherTextSizePx — Launcher copy size in pixels
promptTextColor — Optional prompt card headline text color
heroMaxHeight — Max height for hero chat (e.g., "720px", "80vh")
launcherText — Text for the search button or hero input placeholder
width — Default widget width (e.g., "380px" or "90%")
height — Default widget height (e.g., "520px" or "80%")
primaryColor — Primary gradient color (hex)
secondaryColor — Secondary gradient color (hex)

Open the agent with a message

After the embed script is on the page and the widget is created, you can open the agent and send a message programmatically — for example from a form submit, CTA click, or page action.

JavaScript API

window.YouExWidget.sendMessage(
  "I've submitted the free trial signup form and my email address is user@company.com, what's next?"
);

Behavior:

Opens the chat panel (unless you’re using a hero-style inline embed, which is already visible)
Sends the string as a visitor message and starts the conversation
If the widget isn’t ready yet, the message is queued and sent as soon as create() finishes

Optional second argument:

// Send without opening the panel
window.YouExWidget.sendMessage("Hello", { open: false });

Typical pattern: form → open agent with context

async function onTrialSignup(email) {
  // 1) Your own signup / CRM / API call
  await fetch("/your-signup-endpoint", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email }),
  });

  // 2) Hand the visitor to the Web Agent with context
  if (window.YouExWidget?.sendMessage) {
    window.YouExWidget.sendMessage(
      `I've submitted the free trial signup form and my email address is ${email}, what's next?`
    );
  }
}

No-JS option: `data-youex-message`

Any clickable element can open/send a message:

<button data-youex-message="I'd like to book a demo.">
  Talk to the agent
</button>

The widget listens for clicks on [data-youex-message] and calls sendMessage with that attribute’s value.

Instance API (advanced)

create() returns an instance with:

open() — Open the chat panel
close() — Close the chat panel
sendMessage(message, options?) — Open (by default) and send a message
destroy() — Remove the widget from the page

Prefer the global window.YouExWidget.sendMessage(...) for most sites — it works even if create() hasn’t finished yet.

Administrator Guide

Configure workspaces, knowledge, agents, conversations, and routing operations in YouEx.ai.

Proactive messages (Beckons)

Enable and configure Beckons so your web agent can invite visitors to chat with page-specific proactive messages.