Administrator Essentials

Web Agent Configuration

This guide explains how to configure a YouEx.ai web agent

Admin Guide: Web Agent Configuration

This guide explains how to configure a YouEx.ai web agent, what each setting does, and what behavior to expect in live chats.

It is written for customer admins who manage agents in the Agent Configuration area of the admin app.

What A Web Agent Can Do

A web agent can:

answer questions from a connected Knowledge Base
return exact answers for high-priority Q&A pairs
collect lead information from visitors
offer incentives such as links, codes, downloads, or consultation offers
create or update leads from chat
hand off to Gmail auto-replies and Google Calendar scheduling when configured
be embedded on a public website as a chat widget or inline hero experience

How The Agent Behaves In A Live Chat

The agent does not treat every setting equally. It follows a defined order of operations.

Response Priority

In general, the agent behaves like this:

It checks safety and privacy guardrails first.
If a Q&A Pair matches strongly, it returns that configured answer directly.
If no Q&A Pair matches and you have any Info Fields set to importance 10, the agent will ask for one of those before continuing.
Otherwise it answers from the Knowledge Base or configured scheduling tools.
After answering, it may ask for one additional Info Field, present an Offer, or fulfill an already-earned Offer.

Important Considerations

Q&A Pairs can override normal lead-capture flow.
- This is intentional for high-priority cases like privacy requests, compliance responses, refund policies, or contact instructions.
Importance 10 fields are a hard gate.
- If you set a field to 10, the agent will stop and ask for it before normal answering, unless a stronger override like a matching Q&A Pair applies.
The agent asks for one field at a time.
- It should not ask for multiple required fields in one message.
Offers do not reveal their real details until they are earned.
- Before unlock, the agent can preview the value of an offer, but it should not expose the real link, booking URL, code, or raw fulfillment details. This is intended to encourage the visitor to share information.
Known visitor details may be used internally but not disclosed back to the visitor from stored data.

Q&A Matching Is Not Exact-Only

Q&A Pairs support:

exact question matches
optional keyword matching
strong similarity matching

That means a Q&A Pair like:

Question: Delete my personal data

can still match user messages like:

I want you to delete my personal data
Please delete my personal data

This is useful for compliance, privacy, legal, contact, and escalation answers that should take priority.

Recommended Setup Order

When creating a new agent, use this order:

Create the agent with a clear Name and optional Description.
Connect the correct Knowledge Base.
Add high-priority Q&A Pairs for exact business answers.
Add Info Fields for lead capture and gated workflows.
Add Offers if you want the agent to incentivize or fulfill actions after information is collected.
Connect Email / Calendar if the agent should reply by email or schedule meetings.
Test the experience in the Test tab.
Restrict Allowed Embed Domains before going live.
Copy the widget code from Deploy and place it on your site.

Create Agent

When you click New Agent, you set:

Name
- Internal and visible working name for the agent.
- Choose something clear, like Support Bot, Demo Booking Agent, or Privacy Assistant.
Description
- Internal description for admins.
Knowledge Base
- The source the agent uses for knowledge-based answers.

You can create the agent first and refine everything else afterward.

Agent Header / Edit Agent

At the top of the selected agent, you can edit:

Name
- Main admin-facing name.
Popup Title
- Displayed in the widget header.
- If left blank, the agent uses the Name.
Description
- Internal summary for admins.

Config Tab

The Config tab controls baseline behavior.

Welcome Message

The first message shown in the Test tab and widget before the user says anything.
Keep it short and inviting.
Good examples:
- Hello! How can I help you today?
- Hi, I can answer product questions or help you book a demo.

System Prompt

Use this for:

tone and voice
role boundaries
escalation guidance
extra instructions specific to your business

Do not use this as your primary knowledge source.

Best practice:

Put factual content in the Knowledge Base.
Put exact must-use answers in Q&A Pairs.
Use the System Prompt for behavior, tone, and workflow guidance.

Good uses:

Keep answers concise and professional.
If pricing is not in the knowledge base, ask the visitor to contact sales.
Never promise implementation timelines unless explicitly documented.

Avoid:

pasting long documentation into the prompt
putting discount codes or private URLs here
relying on the prompt instead of Q&A Pairs for compliance answers

Conversation Starters

You can set up to 3 starter prompts.

These appear before the first message and help users begin.

Good starter examples:

How does it work?
What integrations do you support?
Book a consultation

Knowledge Base

This is the knowledge source for normal answers.

Expected behavior:

If a user asks a knowledge question, the agent searches the connected Knowledge Base.
If nothing relevant is found, the agent should say it does not have that information in its knowledge base.

Best practices:

assign only one clearly relevant Knowledge Base to each agent
keep the content current
use Q&A Pairs for exact responses that must win even when the KB contains similar content

Create Leads from Chat

When enabled:

collected visitor information can create or update leads
lead information is persisted into CRM records

When disabled:

the agent can still converse and collect context in the chat flow
but it should not create or update CRM leads from the chat

Use cases for turning this off:

pure support or documentation bots
privacy-sensitive assistants where CRM capture is not wanted

Active

On: the agent can respond in the Test tab and embedded widget
Off: the embedded widget will not work for visitors

Recommended practice:

leave the agent inactive until configuration and testing are complete

Allowed Embed Domains

This controls where the public widget is allowed to load.

Supported formats:

full origin: https://example.com
hostname: example.com
wildcard hostname: *.example.com

If left empty:

the widget is allowed on all domains

Recommended production setup:

always add your real production domains
avoid leaving this open unless you have a deliberate reason

Examples:

https://www.example.com
app.example.com
*.example.com

Q&A Pairs Tab

Use Q&A Pairs for answers that should be returned directly and consistently.

Each Q&A Pair contains:

Question
Answer
Keyword Matching (optional)

What Q&A Pairs Are Best For

Use them for:

privacy/compliance requests
refund or cancellation policy responses
support contact instructions
pricing disclaimers
legal or operational responses that should not vary
critical routing answers like Email support@...

How Matching Works

The system tries to match:

the exact question
configured keywords
strong intent similarity

This means admins do not need to guess the exact phrasing a visitor will type.

Best Practices For Q&A Pairs

Write the Question as the clearest version of the user intent.
Write the Answer exactly as you want it returned.
Add keywords for abbreviations, acronyms, or alternate phrasing.

Example:

Question: Delete my personal data
Answer: Absolutely. Please email privacy@yourcompany.com from the address you want removed and include your full name and request.
Keywords: ccpa, gdpr, privacy request, data deletion

When To Prefer Q&A Over The Knowledge Base

Use a Q&A Pair instead of only KB content when:

the answer must be consistent
the answer is procedural
the answer is compliance-sensitive
the answer should override lead capture

Info Fields Tab

Use Info Fields to tell the agent what visitor information to collect.

Each Info Field includes:

Field Name (internal)
Label (what to ask)
Importance
Validation Rules (optional)

Field Name (internal)

This is the stable internal key.

Use a clear, durable name such as:

full_name
email
phone
company
capital_raise
timeline

Best practice:

keep this stable once the agent is live
use names that are easy for admins to understand later

Why it matters:

these keys can map into lead fields and custom fields
changing them later can make reporting and downstream workflows harder to read

Label (what to ask)

This is the question or label the agent uses in conversation.

Examples:

What is your email address?
Could you please share your full name?
What stage are you at in your fundraising journey?

Best practice:

write labels the way you would want the agent to ask them
be specific and natural

Importance

Importance controls how aggressively the agent collects that field.

Guidelines:

10 = required before the agent will continue normal answering
8-9 = very important, should be collected soon after answering
5-7 = gating or lead-qualification information
1-4 = optional or lower-priority enrichment

Recommended usage:

use 10 sparingly
reserve 10 for only truly essential fields

Examples:

email might be 10 for a gated download agent
company might be 6
timeline might be 4

Validation Rules

Validation rules help the agent interpret whether the user has provided an acceptable answer.

Examples:

Must be a valid email format
Must include first and last name
Please provide at least 2 characters

Best practice:

keep rules simple and specific
use them when the field needs stronger validation than normal conversation

Important Runtime Behavior For Info Fields

The agent asks for one field at a time.
If the user replies with a direct answer, the agent should treat it as the answer to the last requested field.
Importance 10 fields block normal conversation until collected.
If there are no missing 10 fields, the agent should answer first and then ask for one missing higher-priority field.

Info Field Design Tips

Use clear labels for common fields:

include the word email for email fields
include phone for phone fields
include full name when you really need both first and last name

This helps the agent interpret and validate user answers more reliably.

Offers Tab

Use Offers when you want the agent to either:

encourage the visitor to share more information
fulfill something valuable after required information is collected

Each Offer includes:

Offer Name
Description
Offer Type
Offer Action
Info Value Required
Offer Details

Offer Name

Internal admin-facing name for the offer.

Examples:

Strategy Call
Pricing Sheet
5% Discount
Early Access Waitlist

Description

This is what the agent says about the offer.

Example:

I can share our pricing guide once I have your business email.

Best practice:

describe the value clearly
do not paste the real fulfillment link or code here

Offer Type

Used to describe the nature of the offer:

Discount
Mailing List
Download
Consultation
Custom

This helps admins organize offers, but the actual fulfillment behavior is controlled mainly by Offer Action.

Offer Action

This determines how the offer is fulfilled.

Options:

Provide Web Link
- used when the final result is a URL
Calendar Scheduler
- used when the offer is a consultation or meeting flow
Provide Offer Code
- used for codes or redemption instructions
Someone Will Follow Up
- used when no self-serve fulfillment is provided

Offer Details

This is the actual fulfillment detail.

Examples:

web link: the destination URL
calendar scheduler: a fallback URL if live scheduling is unavailable
offer code: the code or redemption instructions
follow-up: an internal follow-up note or visitor-facing follow-up message

Important:

the system is designed to keep these details hidden until the offer is earned

Info Value Required

This is one of the most important fields to understand.

The threshold does not mean:

unlock after any one field with this value

It means:

the offer becomes eligible when the visitor has provided all Info Fields with importance greater than or equal to this threshold

Example:

If your fields are:

Email = 10
Full Name = 10
Company = 7
Timeline = 4

And your offer threshold is 7, the visitor must provide:

Email
Full Name
Company

They would not need Timeline, because it is below 7.

This is the most common admin misunderstanding, so plan thresholds carefully.

How Offers Behave In Practice

The agent may present an offer after a few turns if a high-priority field is still missing.
The real offer details stay hidden until the threshold is met.
Once earned, the agent should fulfill the offer automatically.
If the visitor later asks for the already-earned offer again, the agent should re-share it.

Offer Setup Tips

Use offers when you want a clear exchange:

visitor shares information
agent returns a clearly defined benefit

Good examples:

Share your business email and I’ll send the pricing sheet.
Tell me your timeline and I can offer a consultation.

Avoid:

vague offers with no real fulfillment
putting the real destination URL in the Description

Email / Calendar Tab

This tab controls Google integrations for:

Gmail auto-response
Google Calendar scheduling

Gmail Responder

The Gmail section includes:

Connect Google / Reconnect Google
Enabled
Auto-send replies
Label allowlist
Email signature
Disconnect Gmail

Expected Gmail Behavior

When connected and enabled:

inbound email can be processed by the agent
leads can be created or updated
the system can reply in-thread

If Auto-send replies is off:

email is still processed
lead workflows can still run
but no automated reply is sent

Label Allowlist

This limits which Gmail labels/messages are processed.

Default common value:

INBOX

Use this if:

you want to exclude newsletters or internal folders

Email Signature

This signature is appended to email replies.

Example:

--
Jane Doe
Acme Inc.

Google Calendar Scheduling

The Calendar section includes:

Calendar Status
Calendar ID
Calendar Enabled
Disconnect Calendar

Expected Scheduling Behavior

When Google Calendar is connected and enabled:

the agent can offer live booking options
the agent can present available times
the agent can confirm a selected slot after explicit confirmation

When Calendar is not available:

consultation-style offers fall back to the configured offer behavior
if you provided a fallback booking link in the Offer Details, the agent can share that after unlock
otherwise it will say someone will follow up

Scheduling Preferences

These settings define when and how meetings can be booked.

Available settings:

Host Timezone
Your Name on Invite
Default Meeting Duration
Web Meeting
Allowed Durations
Days Eligible For Scheduling
Daily Start Time
Daily End Time
Minimum Notice
Max Booking Horizon
Buffer Before
Buffer After

Host Timezone

synced from connected Google Calendar
used as the source of truth for actual availability

Important:

the system uses the host timezone for availability logic
user timezone may be used for conversational clarity, but it should not override host availability rules

Allowed Durations

This determines what meeting lengths the agent can offer.

Current UI options:

30 minutes
60 minutes

Working Hours

Set:

eligible days
daily start time
daily end time

This tells the scheduling system when the host is available for booking.

Notice, Horizon, And Buffers

Minimum Notice
- how soon someone can book
Max Booking Horizon
- how far into the future someone can book
Buffer Before / After
- protected time around each meeting

Example:

120 minutes minimum notice
21 day booking horizon
15 minutes before and after each meeting

This is a strong default for sales/demo scheduling.

Test Tab

The Test tab lets you chat with the agent before deploying it.

Use it to verify:

knowledge answers
Q&A Pair overrides
info collection flow
offer presentation and unlock behavior
scheduling behavior
link and gated resource behavior

What To Expect

The Test tab is intended to mirror the public web-agent behavior by default.
The welcome message and conversation starters appear here.
Clear Chat resets the current conversation context.

What To Test Before Go-Live

Run at least these checks:

Ask a normal knowledge question.
Ask a Q&A Pair question and confirm the answer is returned directly.
Try a natural paraphrase of a Q&A Pair and confirm it still matches.
Verify importance 10 fields block as expected.
Verify the agent asks for only one field at a time.
Verify offers preview correctly and only unlock after the right information is collected.
Verify scheduling works if Calendar is enabled.
Verify privacy/compliance requests return the expected direct answer.

Deploy Tab

The Deploy tab gives you:

the widget embed code
appearance settings
launcher settings
layout settings

Embed Code

The platform generates an HTML snippet using:

agentId
apiBaseUrl
position
width
height
launcherStyle
mountId
chatBackgroundColor
chatAccentColor
heroMaxHeight
launcherText
primaryColor
secondaryColor

Launcher Style

Options:

Icon Button
- standard floating chat button
Search Prompt
- a more descriptive prompt-style launcher
Hero Placement
- inline chat experience for landing pages or hero sections

Position

Options:

bottom-right
bottom-center
bottom-left
top-right
top-center
top-left

Note:

position is ignored for hero placement

Mount Element ID

Use this for inline embeds.

Example:

<div id="hero-chat"></div>

If you provide mountId: "hero-chat", the widget renders into that element.

Width And Height

Use CSS-like values such as:

380px
520px
90%
80vh

Color Controls

You can customize:

chat background
chat accent
primary color
secondary color

These control the panel appearance and launcher gradient.

Hero Max Height

Optional setting for hero embeds.

Examples:

640px
720px
80vh

Common Setup Patterns

1. FAQ / Support Agent

Recommended setup:

strong Knowledge Base
Q&A Pairs for exact support policies
minimal Info Fields
Create Leads from Chat = off or limited
no offers unless there is a clear next step

2. Lead Capture / Demo Agent

Recommended setup:

Knowledge Base connected
Full Name = 10
Email = 10
Company = 6
Timeline = 4
Create Leads from Chat = on
Offer = consultation or pricing sheet
Calendar connected if booking is desired

3. Privacy / Compliance Agent

Recommended setup:

Q&A Pairs for privacy and deletion requests
clear compliance email instructions
minimal or no lead capture
importance 10 fields only if truly required

Best Practices

Keep the Knowledge Base focused and current.
Use Q&A Pairs for answers that must not drift.
Use importance 10 carefully.
Use one or two strong offers rather than many weak ones.
Restrict Allowed Embed Domains before production launch.
Test natural-language variants, not just perfect admin wording.
Treat the Test tab as a full workflow test, not just a UI preview.

Common Mistakes To Avoid

putting critical compliance answers only in the Knowledge Base instead of Q&A Pairs
setting too many Info Fields to 10
assuming an Offer threshold unlocks after just one field
exposing private URLs or coupon codes in the Offer Description instead of Offer Details
leaving Allowed Embed Domains empty in production
using the System Prompt as a knowledge dump