AI Agents¶
The Agents section is where you manage all of your CrafterQ agents — from their configuration and connected data sources to testing, usage, and deployment.
Clicking on the Agents menu item will give you a list of your agents. From here, you can click on the Create Agent button to create a new agent (assuming your Plan has unused agents available).
Creating New Agents¶
The Create Agent screen allows you to build a new AI agent from scratch. Here you’ll define its name, appearance, behavior, and user interface — everything needed to shape how your agent will interact with users once deployed.
When you click Create Agent from the Agents page, you’ll be asked for the following fields:
Field | Description |
|---|---|
Name | The internal name of your agent. This is how the agent will appear in your dashboard and project listings. Choose a name that clearly describes its function, such as Support Bot or Product Assistant. |
Description | An optional short description to help you identify the agent’s purpose. |
These fields define your agent’s basic information and are primarily for internal use within your organization.
Saving and Next Steps¶
After completing the required fields:
Click Create to create your agent.
After creating the agent, CrafterQ opens Create knowledge source and asks “What type of knowledge source do you want to create?” Choose from the following options:
Website: Allows CrafterQ to crawl and index content directly from your website or other web pages.
Field
Description
Title
A friendly name for the source (e.g., “Company Docs Site” or “Help Center”).
URL
The starting URL for the crawler (e.g., https://www.example.com/docs/). CrafterQ will automatically follow internal links from this page unless otherwise restricted.
File: Lets you upload documents directly into CrafterQ for indexing.
Use the drag-and-drop area labeled “Drop files here or browse files” to upload your content.Text: Allows you to add raw text content manually — perfect for concise policies, team FAQs, or short reference material.
Field
Description
Title
The internal name for this text source (e.g., “Return Policy”).
Content
The body text you want your agent to learn from. Paste or type any content here, such as plain text, bullet points, or short paragraphs.
Q&A: Defines one or more question-and-answer pairs that your agent can recall exactly as provided.
Field
Description
Title
A descriptive name for the Q&A group (e.g., “Pricing FAQs”).
Question(s)
One or more related questions that users might ask. You can enter multiple variations separated by new lines.
Answer
The response your agent should give for the questions listed above. This text is indexed verbatim.
Fill in the required fields then click the Save button.
Once saved, CrafterQ takes you back to the new agent’s Knowledge screen. From here, you can start customizing your agent from Agents → Settings.
Note
You can edit or add any of the knowledge sources listed above later from Agents → Knowledge.
Create Agent Summary¶
The Create Agent screen is the starting point for building intelligent, branded conversational experiences. By defining both internal details and sources options, you lay the foundation for your agent — ready for customizing how your agent looks, sounds, and interacts and ready for testing, training, and deployment on your digital channels.
Managing Agents¶
Each agent has its own set of configurable screens accessible through the sidebar menu that you’ll see after clicking on an agent listed on the Agent screen:
Tip
New to the Console? Use the Tour item in the sidebar for an overview, or click ? next to Settings or Playground for a guided walkthrough of those screens.
Usage – View chat and credit usage specific to this agent.
Chat Logs – Review past user conversations for training and quality assurance.
Settings – Configure your agent’s core parameters (identity, AI behavior, and interface).
Knowledge – Connect or update the knowledge sources your agent uses.
Playground – Interactively test your agent’s performance and tune its behavior.
Deploy Agent – Deploy or share your agent on websites and applications.
Actions – Install interactive capabilities such as lead capture and escalate to human.
Leads – View and export contact details captured by the Lead Capture action.
Usage Screen¶
The Usage screen provides detailed analytics on how your agent is performing over time. It helps you understand user engagement, monitor message quality, and identify geographic patterns of interaction.
All metrics on this screen reflect data for the time period selected using the calendar control at the top of the page.
Selecting a Time Period¶
At the top of the screen, use the date range selector to specify the time window for your usage data.
The dashboard will automatically refresh to show chat and message statistics for your selected timeframe.
1. Chat Detail Summary¶
This section summarizes your agent’s total activity and feedback within the chosen period.
Metric | Description |
|---|---|
Chats | The total number of chat sessions initiated by users, shown along with the number of countries where they originated. |
Messages | The total number of messages exchanged between users and your agent during the selected timeframe. This includes both user messages and AI responses. |
Thumbs Up | The number of agent messages that users rated positively. This indicates user satisfaction and helps assess agent quality. |
Thumbs Down | The number of agent messages that users rated negatively. Use this to identify responses that need improvement or retraining. |
Pro Tip
A high ratio of chats to thumbs-up feedback suggests users are engaging frequently but not rating responses — consider prompting for feedback in your Agent Instructions.
2. Chats Started (Line Graph)¶
Below the summary metrics, a line graph visualizes the number of chat sessions started per day during the selected period.
Use this chart to:
Identify daily or weekly engagement trends.
Measure how product launches, content updates, or campaigns impact chat volume.
Spot peaks or drops that may indicate seasonal changes or performance issues.
Hovering over a data point shows:
Date
Number of chats started on that day
Example: You might see a spike of 15 chats on October 12 following a new website update, indicating higher user interest or discovery.
3. Chats by Country (Global Map)¶
This interactive world map shows where your chats are coming from, with countries shaded according to their chat volume.
The darker the color, the higher the engagement from that region.
How to use:¶
Hover over any country to view the exact number of chats and percentage of total sessions.
Use this data to identify where your audience is most active.
Combine with chat language settings to localize responses or add multilingual agents.
Example: If you see most chats originating from the U.S. and Germany, you might consider training your agent on support content for those markets (the agent will automatically translate the language for its responses based on the language of user queries.
4. Insights and Next Steps¶
Regularly reviewing your Usage screen helps you:
Track agent adoption and engagement growth.
Identify underperforming regions or timeframes.
Evaluate the quality of interactions using user feedback metrics.
Next Steps:¶
Visit the Chat Logs screen to view individual conversations and assess specific responses.
Revisit the Knowledge or AI Settings screens to retrain or fine-tune your agent based on insights from usage data.
Chat Logs Screen¶
The Chat Logs screen provides a detailed record of all conversations between users and your agent. Use this screen to review real user interactions, understand how your agent is performing in the field, and identify areas where responses can be improved.
Overview¶
Each chat session is automatically logged by CrafterQ and displayed in a searchable, filterable list.
Logs include key information such as:
The date and time of the chat
The messages exchanged
Feedback (Thumbs Up / Down) received from users
This screen is essential for training and continuous improvement — it gives you direct visibility into what your users are asking and how your agent is responding.
Selecting a Time Period¶
At the top of the page, use the calendar widget to choose the date range for the logs you want to view.
Once selected, the chat list will automatically update to show only the sessions that occurred within the chosen timeframe.
Filtering by Feedback¶
You can narrow down your logs by user feedback type, allowing you to focus on either successful or problematic interactions.
Filter options:
Show all: Displays every recorded chat session.
Contains thumbs up: Shows only chats containing messages that received positive feedback.
Contains thumbs down: Shows only chats containing messages that received negative feedback.
Contains either up or down: Shows chats containing messages that received negative or positive feedback.
Pro Tip
Use the “Thumbs Down” filter regularly to identify conversations where your agent underperformed. Reviewing these chats helps pinpoint missing data or prompt issues.
Chat Log List¶
Each entry in the list represents one chat session and includes the following:
Field | Description |
|---|---|
Date/Time | The timestamp when the chat session started. |
Messages | The messages exchanged in the session. |
Feedback | Displays a ✓ Helpful or x Not helpful icon if any message in that chat received feedback. If no feedback was given, nothing is shown. |
Viewing a Chat Transcript¶
Click the on any chat entry on the left side to open the full conversation log. Within the transcript view, you’ll see:
User messages and AI responses, displayed in chronological order.
Any feedback icons beside specific responses (✓ Helpful or x Not helpful).
Message-level metadata such as timestamps and token usage (if applicable).
Use this view to:
Analyze how well the agent understood the user’s intent.
Identify gaps in your content or training data.
Refine prompts and AI settings for improved responses.
Pro Tip
Combine feedback filtering with the transcript view to create a targeted quality review workflow — for example, reviewing only the “Thumbs Down” sessions from the past week.
Exporting Chat Logs¶
You can export the currently filtered chat list as CSV for reporting, auditing, or external analytics.
Use the date range and feedback filters first, then click Export CSV at the top-right of the Chat Logs screen. The file has one row per message. A chat with no messages is still included, as one row with the message columns left empty.
The columns are:
Chat ID
Message ID
Chat Source
Geography
Message Timestamp
Sender (
useroragent)Message
Feedback (
thumbs_up,thumbs_down, or empty)Message Kind
Qna Hit
Success
Confidence
Chat Logs Summary¶
The Chat Logs screen is your direct window into how users are engaging with your agent:
Use time filters to focus on recent or historical sessions.
Use feedback filters to identify high- or low-performing conversations.
Export CSV of the filtered list for external analysis.
Review transcripts to guide prompt updates and retraining decisions.
Next Steps¶
After reviewing chat logs:
Visit the Knowledge screen to add or refine data for poorly answered questions.
Adjust your Agent Instructions or Expressiveness in AI Settings to improve tone or precision.
Re-test improvements in the Playground before redeploying.
Settings Screen¶
The Settings screen defines your agent’s personality, configuration, and user experience. It is divided into three main sections:
General
User Interface
AI Settings
Security
Preview
Each section controls a different aspect of how your agent operates and interacts with users.
1. General¶
This section defines the basic information used to identify and describe your agent within CrafterQ.
Field | Description |
|---|---|
Name | The internal name for your agent, not to be confused with the display name. This appears in the Dashboard, Playground, and Deploy interfaces. |
Description | A short summary of the agent’s purpose. This is for internal use to help your team distinguish between multiple agents. |
Enabled | Allows you to enable/disable the agent. |
Pro Tip
Use clear, descriptive names if you manage multiple agents — e.g., “Website Chatbot – English,” “E-Commerce Assistant,” etc.
2. User Interface¶
These controls customize the look and feel of your chat experience, ensuring the agent matches your brand and provides a user-friendly interaction.

The Avatar control in the User Interface section of Agent Settings.¶
Field | Description |
|---|---|
Display Name | The name shown to the end users in the chat header of the chat widget. Examples: Ask CrafterQ or Support Bot. |
Avatar | A custom image that replaces the default sparkles icon in the chat widget. Click Upload to pick a JPG, PNG, or WebP image — you’ll be able to crop it to the 512×512 target size. After an avatar is set, use Change to replace it or Remove to restore the default icon. |
User Prompt Field Placeholder | Placeholder text that appears in the input box before the user types. Example: “Ask me anything about our services…” |
Welcome Message | The initial greeting message shown when a user first opens the chat window. Example: “Hi there! How can I help you today?” |
Quick Messages (line separated) | Predefined, clickable suggestions that help users start conversations. Enter one per line. – “Show me pricing” |
Out of Credits Messages | The message displayed to end-users when the message quota is exceeded. |
Collect Feedback (on/off) | Enables or disables thumbs-up/down feedback for each message. Turning this on helps track response quality in Analytics. |
Follow-up Messages (on/off) | When enabled, the agent can send follow-up suggestions or clarifications after responding. |
Theme | Sets the chat widget theme. Options: System, Light, or Dark.
|
Brand Color (color selector) | Defines the primary accent color used for buttons, highlights, and header. Typically your brand’s main color. Click Reset to revert to the default. |
User Message Bubble Color (Light Theme) | Customizes the color of the user’s message bubbles in Light Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default. |
User Message Bubble Color (Dark Theme) | Customizes the color of the user’s message bubbles in Dark Mode. This helps differentiate messages and maintain visual consistency. Click Reset to revert to the default. |
UI Mode | The layout/look used for the chat agent on the screen. Options include:
|
Bubble Horizontal Position | The horizontal position of bubble (floating button) on the screen. Options include:
|
Bubble Vertical Position | The vertical position of bubble (floating button) on the screen. Options include:
|
Design Tip
Use your brand’s primary or secondary color for the Brand Color setting, and ensure message bubbles have enough contrast for readability.
3. AI Settings¶
These settings control how the AI model generates responses — influencing expressiveness, tone, role, structure and guardrails.
Field | Description |
|---|---|
Expressiveness (slider) | Expressiveness controls how much variation the AI uses in its wording and phrasing when responding to users.
Note: Expressiveness affects how answers are phrased, not what information is used. The AI always remains data-bounded to its configured sources and instructions (see Agent Instructions below). Under the hood, Expressiveness maps to the LLM’s response variability (aka LLM’s temperature setting). It influences:
It does not:
Important caveat: When a user question matches a Q&A source, the answer is returned verbatim regardless of the Expressiveness setting. |
Agent Instructions (a.k.a. System Prompt) | The foundational instruction that defines your agent’s role, tone, and knowledge boundaries. Example: “You are CrafterQ, a professional AI assistant that only answers based on connected company sources.” The default system prompt is set to the following:
|
Pro Tip
Test prompt variations in the Playground to observe how changes affect tone, accuracy, and context retention.
4. Security¶
This section allows you to configure your agent’s security so it only works on your allowed domains.
Field | Description |
|---|---|
Allowed Domains | Comma-separated entries of domains supported by your agent. Examples include: https://example.com OR https://example.com,https://anotherexample.com OR http://localhost:[8000,3000]
|
5. Preview¶
Use the Preview on the right side of the Settings screen (or the tab next to Settings on mobile devices) to test your agent’s responses at any time. In addition to the agent responses, the Preview will also give you AI diagnostic information, described next.
AI Response Diagnostics (Preview)¶
CrafterQ includes built-in AI Response Diagnostics information inside the Agent Preview experience to help you better understand how your AI agent is generating responses.
This feature is especially useful during setup, tuning, testing, troubleshooting, and optimization of your AI agent.
When enabled, the diagnostics bar appears below each AI response in the Preview chat interface and provides insight into:
AI inference success
Confidence level
Response expressiveness
Inference speed
Retrieved source chunks (RAG)
Agent instructions used during generation
This visibility helps you validate content quality, debug retrieval issues, optimize prompts, and better understand how your AI agent reasons over your training data.
AI Response Diagnostics Metrics¶
Inference Status¶
Displays whether the AI inference completed successfully.
Example:
OK— Response generated successfullyError— The response generation failed or encountered an issue
This helps identify transient LLM/API issues or prompt-processing failures.
Confidence Level¶
Shows the AI system’s estimated confidence in the generated response.
Example: 95% confidence
Higher confidence generally indicates:
Strong semantic relevance
Better source alignment
Higher retrieval quality
Greater answer certainty
Lower confidence may indicate:
Weak or ambiguous source material
Missing training content
Broad or unclear user questions
Conflicting information across sources
Confidence metrics are especially useful when evaluating support, compliance, or product-answering quality.
Expressiveness¶
Displays the current Expressiveness setting used for the response.
Example: 0.75 expr.
Expressiveness controls the balance between:
Precise / deterministic responses
Creative / conversational responses
Lower values produce:
More concise
More factual
More deterministic answers
Higher values produce:
More conversational
More flexible
More creative responses
This metric helps you understand which personality configuration influenced the generated answer.
Inference Time¶
Displays the total response generation time in milliseconds.
Example: 1550ms
Inference time includes:
Retrieval processing
Prompt orchestration
LLM generation
Response assembly
Monitoring inference speed can help monitor and optimize:
User experience
Prompt size
Source complexity
Knowledge source chunks¶
Displays the retrieved source chunks used to generate the answer.
The diagnostics bar shows a chip labeled with how many sources were used (for example, 3 sources). Selecting it opens Knowledge source chunks, which shows:
Source name
Source type
Matching chunk text
Relevance score
This allows you to inspect:
Which content was retrieved
Why a response was generated
Whether the correct sources were used
Retrieval quality and ranking
This panel is extremely useful for debugging RAG (Retrieval-Augmented Generation) behavior and improving training data quality.
Example Use Cases¶
Identify missing documentation
Detect weak content retrieval
Validate AI support accuracy
Troubleshoot hallucinations
Agent Instructions¶
Displays the system-level Agent Instructions used during inference.
This helps you verify:
Prompt engineering configuration
Persona behavior
Guardrails
Tone settings
Reviewing instructions alongside generated responses makes it easier to refine agent behavior and improve consistency.
Why This Matters¶
CrafterQ provides transparent diagnostics that help teams understand:
How responses were generated
Which sources were used
Why certain answers were returned
How retrieval and prompting influenced results
Best Practices¶
Use Diagnostics During Initial Training¶
After adding website or document sources, test common customer questions and inspect:
Confidence scores
Retrieval chunks
Missing source coverage
Validate Important Business Answers¶
Test:
Pricing questions
Product capability questions
Support scenarios
Compliance responses
Ensure the retrieved chunks contain accurate and current information.
Optimize Weak Retrieval¶
If confidence scores are consistently low:
Add more relevant content
Improve content structure
Add targeted Q&A entries
Reduce duplicate or conflicting content
Tune Expressiveness Carefully¶
For support and technical agents:
Lower expressiveness often produces more precise answers
For marketing and engagement agents:
Higher expressiveness may improve conversational quality
Saving Changes¶
After adjusting any field, click Save at the bottom of the Settings screen. Your updates will apply immediately in the Preview next to your agent settings (use tab on mobile) for testing. You can also use the Playground for testing. Note: changes saved will also take effect on your live, deployed agent (if it’s been deployed to your website or other channels).
Next Steps¶
Once you’ve configured your agent’s basic settings:
Visit the Knowledge screen to connect data your agent will use.
Use the Playground to test and fine-tune its responses before deploying.
Explore the Deploy Agent screen to publish your agent on your website or app.
Knowledge Screen¶
The Knowledge screen is where you connect your agent to the information it needs to provide accurate, contextual responses. Each knowledge source is a collection of content that CrafterQ uses to train your agent through advanced, proprietary AI engineering techniques ensuring that every response is based on your own verified data.
Overview¶
From this screen, you can:
Add, edit, or delete knowledge sources
View the status of existing knowledge sources (for example, Pending, Crawling, Training, or Trained)
Retrain knowledge sources if the underlying data changes
To create a new knowledge source, click Create knowledge source at the top of the page.
Creating a Knowledge Source¶
Clicking Create knowledge source opens a dialog titled Create knowledge source. It asks “What type of knowledge source do you want to create?” and lets you select the type of content you want to add.
CrafterQ supports four source types:
Website
File
Text
Q&A
Each type is described below.
1. Website¶
A Website Source allows CrafterQ to crawl and index content directly from your website or other web pages.
Fields¶
Field | Description |
|---|---|
Title | A friendly name for the source (e.g., “Company Docs Site” or “Help Center”). |
URL | The starting URL for the crawler (e.g., https://www.example.com/docs/). CrafterQ will automatically follow internal links from this page unless otherwise restricted. |
Advanced Options¶
Expand the Advanced Options panel to refine what the crawler includes or excludes:
Option | Description |
|---|---|
How should CrafterQ discover content? | Here are the options:
|
Include linked documents | Enables including documents (PDF, txt, doc, docx, ppt, pptx) that are linked from discovered pages. |
Auto-refresh | Toggle on/off automatic refresh of the source based on the plan refresh frequency |
Include only | (Optional) Specify URL patterns or paths that should be included in the crawl. Example: /docs/* or /support/*. For more complex patterns, use regular expressions by prefixing each pattern with regex:. Example: regex:^/products/.*,regex:^/blog/.* |
Exclude | (Optional) List any URLs or patterns that should be excluded from the crawl (e.g., /privacy, /blog). For more complex patterns, use regular expressions by prefixing each pattern with regex:. Example: regex:^/products/.*,regex:^/blog/.* |
Selector(s) | (Optional) Target specific portions of each page by providing CSS selectors such as #main-content, div.article-body, or main. This helps limit the crawl to meaningful content areas and avoid navigation or footer text. |
Pro Tip
Use the CSS selectors option to focus indexing on structured content regions and reduce noise from headers, menus, or ads.
When a website cannot be crawled or trained on (bot protection)¶
Some sites use bot protection (for example Cloudflare Bot Fight Mode, Imperva, or similar WAF products) that block automated crawlers. When that happens, CrafterQ may finish training with little or no content and show an error similar to:
0 bytes crawled. The site may be blocked by anti-bot protection, robots.txt, or element selectors.
To allow CrafterQ to train on the site, your web / security admin must either temporarily turn off bot protection, or allowlist CrafterQ’s crawler IP addresses in the bot-protection / WAF configuration. Note that Cloudflare Free Bot Fight Mode applies at the domain level and does not support WAF custom-rule Skip actions; path-scoped exceptions require Super Bot Fight Mode (or another WAF product that supports path-scoped allow rules).
CrafterQ crawler IP addresses¶
Allowlist all of the following IPv4 addresses:
3.219.114.93
100.50.81.86
3.234.29.20
After the allowlist (or bot-protection change) is in place, open the website knowledge source in CrafterQ and click Retrain knowledge source.
Note
The same error can also appear when robots.txt disallows crawling, or when Selector(s) exclude all meaningful page content. Check those settings if allowlisting does not resolve the issue.
Example: Cloudflare bot protection¶
Cloudflare is a common cause of blocked crawls. Use one of the approaches below, depending on your Cloudflare plan and how aggressively bot protection is configured.
Option A — Allowlist CrafterQ IPs (recommended)
Keep bot protection enabled for everyone else, and exempt only CrafterQ’s crawler IPs.
Super Bot Fight Mode (Pro, Business, and Enterprise)
Cloudflare’s preferred way to create exceptions for Super Bot Fight Mode is a WAF custom rule with the Skip action:
In the Cloudflare dashboard, select your account and domain.
Go to Security → Security rules.
Select Create rule → Custom rules.
Enter a descriptive name (for example,
Allow CrafterQ crawler).Under When incoming requests match, select Edit expression and enter an expression that matches the CrafterQ crawler IPs and your site’s hostname and crawl path. Replace the hostname and path with the values from your CrafterQ website source (starting URL / include patterns):
(ip.src eq 3.219.114.93 or ip.src eq 100.50.81.86 or ip.src eq 3.234.29.20) and http.host eq "www.example.com" and starts_with(http.request.uri.path, "/docs")
Under Then take action, choose Skip, then select All Super Bot Fight Mode rules only. Add rate limiting or Managed Rules to the Skip options only if those features also block the crawl after Super Bot Fight Mode is skipped.
Place the rule near the top of your custom rules list so it runs before blocking rules.
Select Deploy.
For a reusable allowlist, create an IP list containing the three CrafterQ addresses, then match ip.src in $your_list_name in the expression instead.
Bot Fight Mode (Free) and IP Access Allow rules
Bot Fight Mode cannot be skipped with custom-rule Skip actions. To exempt specific IPs while Bot Fight Mode (or other default security checks) is enabled, create an IP Access rule with action Allow for each CrafterQ IP:
In the Cloudflare dashboard, go to Security → Security rules.
Select Create rule → IP access rules.
For each CrafterQ IP above:
Enter the IP address.
Set Action to Allow.
Set Zone to the current website only (do not apply the rule to all websites in the account).
Optionally add a note such as
CrafterQ crawler.Select Create.
The Allow action excludes matching visitors from most Cloudflare security checks (including challenges that often block crawlers). See Cloudflare’s docs on IP Access rules and handling bot false positives.
Option B — Turn off bot protection (last resort)
Use this only if you cannot create allowlist exceptions. Prefer a temporary, documented change: note the current bot-protection settings, turn protection off just long enough for CrafterQ to crawl and train, then restore the original settings.
In the Cloudflare dashboard, go to Security → Settings.
Filter by Bot traffic.
Record the current values (for example, Bot Fight Mode on/off, or each Super Bot Fight Mode grouping and option).
For Bot Fight Mode (Free): turn it Off.
For Super Bot Fight Mode (Pro and above): set Definitely automated, Likely automated, and related options to Allow, and turn off extra options such as JavaScript detections if they still interfere with the crawl/training.
Also confirm the site is not in I’m Under Attack Mode (Security → Settings → Security Level), which challenges almost all visitors and will block training crawls. If you lower Security Level for the crawl/training, note the previous value.
After training completes successfully in CrafterQ, restore the bot-protection settings (and Security Level, if changed) to the values you recorded.
Important
Cloudflare’s dashboard labels and menu paths change over time. If the steps above do not match your account, search Cloudflare’s documentation for Skip Super Bot Fight Mode, IP Access rules, or Bot Fight Mode false positives, and apply the same allowlist IPs.
Other bot-protection / WAF products¶
For Imperva, AWS WAF, Akamai, Sucuri, or similar products, add the three CrafterQ crawler IPs to the product’s IP allowlist / whitelist / trusted sources so requests from those addresses are not challenged or blocked. The goal is the same: CrafterQ must be able to fetch HTML without an interstitial challenge page.
2. File Source¶
A File Source lets you upload documents directly into CrafterQ for indexing.
Upload Box¶
Use the drag-and-drop area labeled “Drop files here or browse files” to upload your content.
Supported file formats typically include:
.pdf
.doc
.docx
.txt
.csv
.xls
.xlsx
.ppt
.pptx
.html
.htmlx
Once uploaded, CrafterQ automatically extracts and indexes the file text so your agent can use it during conversations.
Pro Tip
Group related documents together in a single source (e.g., Product Manuals) to simplify management.
3. Text Source¶
A Text Source allows you to add raw text content manually — perfect for concise policies, team FAQs, or short reference material.
Fields¶
Field | Description |
|---|---|
Title | The internal name for this text source (e.g., “Return Policy”). |
Content | The body text you want your agent to learn from. Paste or type any content here, such as plain text, bullet points, or short paragraphs. |
This option is ideal for quick knowledge additions without uploading files or web links.
4. Q&A Source¶
A Q&A Source defines one or more question-and-answer pairs that your agent can recall exactly as provided.
This is useful for specific responses that require precise wording or compliance-approved language.
Fields¶
Field | Description |
|---|---|
Title | A descriptive name for the Q&A group (e.g., “Pricing FAQs”). |
Question(s) | One or more related questions that users might ask. You can enter multiple variations separated by new lines. |
Answer | The response your agent should give for the questions listed above. This text is indexed verbatim. |
Example:
Question: “What are your business hours?”
Question: “Business hours?”
Answer: “Our offices are open Monday through Friday, 9 AM to 5 PM EST.”
Saving and Training¶
Once you’ve filled in the required fields for any source type, click Save.
After saving:
CrafterQ automatically begins a training step, where the content is indexed and vectorized for retrieval.
The status indicator under the source will show progress (e.g., “Crawling,” “Training,” or “Trained”).
Once training completes, the data becomes immediately available for your agent to use in chat responses.
Note
If you later update or replace the source data, your agent will automatically be retrained. If you update your website content through your CMS, then your agent will automatically find the new content and retrain itself on a schedule based on your Billing Plan; you can also click Retrain knowledge source to force a retraining operation.
Managing Existing Sources¶
Filter the list with the type tabs: All Types, Website, File, Text, and Q&A. On a small screen those choices are in a list instead of tabs.
Each row shows:
The knowledge source name
Its size
For a Website source, the number of links (
1 linkorN links)Last crawled and the date when a crawl time is recorded; otherwise Last updated and the date
A status badge, such as Pending, Crawling, Training, or Trained
A type badge (Website, File, Text, or Q&A)
The menu on the row (the more-options icon) includes Edit and Delete when your role allows them.
Retrain knowledge source is on that menu for Website, Text, and Q&A sources. It is not offered for a File source. It is unavailable while the source is Pending, Crawling, or Training.
Cancel Training is on the menu for a Website source only, and it can be used only while that source is Crawling.
Use these controls to maintain your agent’s knowledge base and ensure accuracy over time.
Bulk actions¶
Each row has a checkbox. The checkbox at the top of the list selects every listed knowledge source, up to 25. The hint reads Select all, or Select up to 25 when the list is longer than 25. Selecting all of a longer list shows “Selected maximum 25 sources for bulk action.” Checking one more than 25 shows “You can select at most 25 sources for a bulk action.” If any rows are already selected, that click clears the selection. Click it again to select up to 25.
When at least one row is selected, Retrain and Delete appear. Retrain skips the selection when it includes a File source or a source that is still processing, and it shows: “File sources and sources being processed can’t be retrained.” Delete asks you to confirm. The dialog title is “Delete N knowledge source?” (or “sources” when more than one is selected). The message is “Are you sure you want to delete this knowledge source?” Confirm with Delete, or leave the sources in place with Cancel.
Best Practices¶
Keep each source focused (one topic or type of document per source).
Use Advanced Options on website sources to filter out irrelevant content.
Combine multiple source types for a well-rounded dataset (e.g., website + PDF + Q&A).
Knowledge Summary¶
The Knowledge screen is where your agent’s intelligence begins. By connecting relevant and high-quality data here, you enable CrafterQ to generate accurate, context-aware responses tailored to your organization’s knowledge.
Actions Screen¶
The Actions screen lets you extend your agent beyond Q&A with structured, in-chat capabilities. Actions appear as inline forms inside the chat widget when the AI determines they are relevant to the conversation.
Overview
From Agents → Actions, you can:
Browse the action catalog and install actions on the selected agent
Configure each action’s behavior, form fields, and delivery options
Enable or disable an installed action without uninstalling it
Preview how the form will look in the chat widget
Actions require a paid subscription plan. Your plan sets how many actions you may install per agent; an Additional Actions add-on can increase that limit. If your plan does not include actions, the screen prompts you to upgrade.
Installing an Action
Click Install Action and choose an action from the catalog.
Complete the configuration form (see below).
Click Save to install the action on your agent.
Each action type can be installed once per agent. To change configuration later, click Edit on the installed action card.
Configuration Sections
Most form-based actions share these configuration areas:
Section | Description |
|---|---|
When to use | Instructions that tell the AI when to show the form during a conversation. Be specific about the user intent or topics that should trigger the action (e.g., “when the visitor asks to speak with a person” or “when they request a demo or pricing follow-up”). |
General | Form presentation: title, description, featured message, button labels, and success/dismiss messages shown in the chat widget. |
Fields | The inputs collected from the visitor. Reorder fields, mark them required, and add custom field names. |
Delivery | How submission data is delivered after the visitor submits the form (varies by action type). |
Preview | A live preview of the form as visitors will see it in the chat widget. |
Lead Capture
Collects visitor contact information through an inline form.
Delivery options:
Email — send a notification to one or more email addresses (includes a link to the conversation in the Console)
Webhook — POST the lead data to your endpoint (optional HMAC signature for verification)
After installation: captured leads appear on the Leads screen for this agent. You can export them as CSV or delete individual records.
Escalate to Human
Lets visitors request human support through an inline form. Your team is notified when a submission is received.
Delivery options:
Email — send a notification to one or more email addresses
Webhook — POST an escalation payload to your endpoint (includes a link to the conversation in the Console)
Submission limits: configure a maximum number of successful submissions per chat per day (default: 1). When the limit is reached, the visitor sees a configurable message instead of the form.
After a successful escalation in a chat, Lead Capture is suppressed for that conversation.
Testing Actions
Install and configure actions, then test them in the Playground using queries that match your When to use instructions.
If you are testing Lead Capture repeatedly, the Playground may show a notice that your test profile already submitted or dismissed the form. Use Clear on that notice to reset your playground lead-capture state and test the form again.
Uninstalling
Click Uninstall on an installed action to remove it from the agent. Uninstalling Lead Capture does not delete leads already captured — they remain on the Leads screen.
Leads Screen¶
The Leads screen lists contact records captured by the Lead Capture action for the selected agent.
Overview
Use this screen to:
Browse captured leads with date filtering
Open a lead to view all submitted field values
Export leads to CSV for use in your CRM or marketing tools
Delete selected leads in bulk
If Lead Capture is not installed, or no visitors have submitted the form yet, the screen shows an empty state.
Lead Data
Each lead includes the field values configured on your Lead Capture action (e.g., email, name, custom fields), the capture timestamp, and the source channel (e.g., Web, API, WhatsApp, Facebook, Instagram, Slack).
Playground Screen¶
The Playground screen is where you can test your AI agent in real time — just as your users would experience it on your website or app. It provides an interactive chat environment to evaluate how well your agent performs based on its Settings, Knowledge, and AI configurations.
Overview
The Playground is a single, live instance of your selected agent.
You can use it to:
Experiment with different types of user queries
Evaluate how your agent responds based on its data sources and agent instructions
Test Actions (lead capture, escalate to human) when installed and configured
Adjust the Settings (agent instructions, expressiveness, etc.) and retest to fine-tune results
Note
In future releases, the Playground will support multiple side-by-side testing instances, allowing you to compare different configurations (e.g., varying prompts, temperatures, or models) for more advanced optimization.
How It Works
When you open the Playground, you’ll see:
A chat interface identical to the deployed chat widget
An input field to type your messages
The conversation history displaying your queries and the agent’s responses
This environment uses the exact same parameters you configured under the Settings screen — including:
Agent Instructions
Expressiveness
User Interface options (avatar, welcome message, placeholder text, etc.)
That means the Playground replicates the live user experience, ensuring your tests reflect how the agent will behave once deployed.
Testing Your Agent
Type a query or request in the input field (e.g., “What products do you offer?” or “Summarize our privacy policy.”)
Observe the agent’s response.
Evaluate for:
Accuracy — Does the response correctly reflect your content sources?
Tone — Is it aligned with your intended personality or brand voice?
Structure — Is the message clear, concise, and complete?
If the agent’s answers need improvement:
Go back to the Settings screen to adjust prompts, temperature, or model options.
Open Knowledge and use Retrain knowledge source if content has changed or needs refinement.
Return to the Playground and test again.
Pro Tip
Keep a short list of benchmark questions to test consistency after making configuration changes.
Quota and Billing Usage¶
All interactions within the Playground use live API calls and therefore count toward your organization’s quota and billing plan.
Specifically:
Each message exchange consumes credits under your agent’s Usage plan.
These credits are reflected in both the Usage screen (per agent) and your Dashboard totals.
Important
Treat Playground testing as production usage. While it’s a safe space for experimentation, frequent testing will consume your plan’s credit allowance.
When to Use the Playground¶
Use the Playground whenever you:
Create a new agent and want to confirm it’s working correctly
Add or update sources and want to validate the new knowledge
Modify prompts or temperature settings and want to observe behavioral changes
Need to demonstrate your agent’s functionality before deployment
Playground Summary¶
The Playground gives you an accurate preview of how your agent will perform in the real world — using the same configuration, data, and tone defined in its settings. It’s the best place to refine your agent before deploying it live.
Deploy Agent Screen¶
The Deploy Agent screen is where you publish the agent. It asks How do you want to use your agent?
Overview¶
Under the heading, Agent ID is the agent’s id on its own line, with a button that copies it. That id is the data-q-id in the chat widget script.
Two choices are shown first. The install steps stay hidden until you pick one.
Add Q to your website — Add a chat widget, or place the chat within your page layout. The next step is Chat widget or Embedded chat.
Use Q as your website — Marked No website needed. Give your agent its own website — ready to share with anyone. No coding or existing website required. This is the AI website.
The chat widget can also send open and message events to Google Analytics 4 and Google Tag Manager. See Analytics Integration.
1. Add Q to your website¶
After you choose Add Q to your website, pick Chat widget or Embedded chat.
Chat widget¶
Chat widget adds your agent to any website.
Open the HTML template that includes your
<body>tag.Paste the script immediately before the closing
</body>tag. The button label is Copy widget code; the button itself says Copy.
<script src=”https://chat.crafterq.ai/embed.js” data-q-id=”YOUR_AGENT_ID”></script>
data-q-id is the Agent ID under the heading. The Console fills in the chat site for your environment. The standard host is https://chat.crafterq.ai.
On this panel, open Widget settings to save stacking, links, custom CSS, and analytics. Open Advanced embed options for page-specific code. Both are below. Embedded chat follows those sections.
Advanced embed options¶
For developers who want more control over widget behavior, CrafterQ supports advanced initialization through JavaScript. The panel title is Advanced embed options. Turn on Show all embed options to see values that can also be set in Widget settings. A value in the snippet wins over Widget settings for each property the snippet sets.
Use the following template for custom setup:
<script src="https://chat.crafterq.ai/embed.js"></script>
<script>
window.crafterq.init({
/** agentKey {string} - Required. Your agent key. */
agentKey: '0198ed35-9f87-7711-8a93-2dfdc027e007',
/** onMount {function} - Optional.
* Function executed after the chat widget is fully mounted.
*/
onMount() {
// Custom logic here
},
/** openLinksInNewTab {boolean | function} - Optional.
* Determines how external links are handled.
* - true: always open links in a new tab
* - false: open links in the same window
* - function: provides fine-grained control
*/
openLinksInNewTab(e) {
const href = e.currentTarget.getAttribute('href');
if (!href) return;
try {
const url = new URL(href);
if (window.location.hostname !== url.hostname) {
e.preventDefault();
window.open(href, '_blank', 'noopener noreferrer');
}
} catch {
// Invalid URL - ignore
}
},
/** emitGoogleAnalytics {boolean} - Optional. Default: true.
* Calls gtag('event', name) when the page already defines gtag.
* Message text is not sent. Set false to opt out.
*/
emitGoogleAnalytics: true,
/** emitGTM {boolean} - Optional. Default: false.
* Pushes {event: name} to window.dataLayer for Google Tag Manager.
*/
emitGTM: false
});
</script>
Passing options with data-init-config¶
The script tag can carry the JSON-serializable options in data-init-config, next to data-q-id. Use it when every value is data: booleans, strings, and plain objects. window.crafterq.init() is the way to pass function values such as onMount and a custom openLinksInNewTab handler.
data-q-id is the agent id. An agentKey inside the JSON is ignored. An empty data-init-config loads from data-q-id alone, with no warning. The widget logs [CrafterQ] data-init-config contains invalid JSON; falling back to basic init. only when the attribute is non-empty and is not valid JSON, then loads from data-q-id alone.
A property you include overrides the matching Widget settings value saved on the agent. Omit a property to keep the saved value. Defaults for the analytics flags are in Analytics Integration.
<script
src="https://chat.crafterq.ai/embed.js"
data-q-id="0198ed35-9f87-7711-8a93-2dfdc027e007"
data-init-config='{"emitGoogleAnalytics":true,"emitGTM":false,"css":":host { font-size: 14px; }"}'>
</script>
Widget settings¶
On Deploy Agent, open Add Q to your website → Chat widget → Widget settings. The values are saved on the agent. The two analytics switches (Analytics Integration) sit in this panel with three other fields:
Widget stacking z-index — Lifts the widget above sticky menus and buttons. New agents use WordPress (100,000). Agents with no saved embed config, including agents created before this setting existed, show System Default (no change) until you pick another preset and save. The other presets are High (10,000) and Extreme (999,999), or a custom whole number from 0 to 2,000,000. This field is saved on the agent and is not an
init()option. For a page-specific MUI z-index, pass theme in the table below. The saved stacking value still sets the widget host element’s z-index.Open links in a new tab — The saved form of openLinksInNewTab. When it has never been set, the chat widget keeps links in the same tab. Embedded chat and the AI website open links in a new tab.
Custom CSS — CSS injected into the widget shadow DOM after the built-in styles. It cannot change the rest of the host page. Maximum length is 16,000 characters. Embed css is applied after this saved CSS.
Embed settings (embedded chat) and Page behavior (the AI website) include Open links in a new tab and Chat unavailable message. Those panels do not include the analytics switches. A value saved on the agent still applies inside those pages; see Limits in Analytics Integration for what that means for Google tags on the host site.
The same saved values can also be edited from the agent’s Settings → User Interface → Widget hosting & embed overrides. That dialog includes every field (analytics, stacking, links, the unavailable message, and custom CSS) and notes that embed init values override them when both are set. On Deploy Agent, Advanced embed options says the same thing: a value in the embed snippet wins over Widget settings for each property the snippet sets. Leave a property out of the snippet to keep the saved value.
Available Options¶
Option | Type | Required | Description |
|---|---|---|---|
agentKey | String | ✅ Yes | The unique identifier for your CrafterQ agent. |
context | Object | ❌ No | Optional host/page metadata (string values) sent with each chat turn. Valid, non-empty host values override auto-captured fields (blank values are ignored; invalid or relative |
chatUnavailableMessage | String | ❌ No | When the hosted AI website or an iframe embed detects a disabled agent, it displays this text. A direct |
onMount() | Function | ❌ No | Runs after the chat widget mounts. Use for analytics, UI tweaks, or logging. Not available in data-init-config. |
openLinksInNewTab | Boolean / Function | ❌ No | Controls how the widget handles links. Accepts true, false, or a custom function. A function is only available through |
css | String | ❌ No | CSS injected into the widget shadow DOM after the built-in styles and after Custom CSS saved in Widget settings. It cannot style the rest of the host page. |
theme | Object | ❌ No | MUI theme options, deep-merged on top of the widget theme and the saved stacking z-index. |
emitGoogleAnalytics | Boolean | ❌ No | When |
emitGTM | Boolean | ❌ No | When |
Pro Tip
The onMount callback can be used to automatically open the chat when a user lands on a page, track widget engagement, or log initialization events to your analytics system.
Embedded chat¶
Embedded chat places the chat within your page layout, right where you want it. The snippet is an <iframe> whose address is the AI website URL.
Before you copy it, the page shows Allow the website before embedding: “The iframe host must be listed under Settings → Security → Allowed Domains.” Use Review agent settings to open Settings.
Open the HTML for the page where the chat should appear.
Paste the code where you want the chat to show within the page. The button label is Copy iframe code; the button itself says Copy.
The note under the steps says: “The “Size and appearance” section below helps you customize this snippet. Adjust there, then copy the updated code onto your page.”
Size and appearance¶
These options change the iframe code above. Copy the updated snippet onto your website after you edit them.
Field | What it does |
|---|---|
Accessible title | Describes the chat to screen reader users. It starts as “Chat with” plus the agent name. |
Width | A number and a unit, % or px. Percent is limited to 100. Pixels are limited to 2,000. The snippet starts at 100%. |
Height | Pixels, from 200 to 2,000. The snippet starts at 700. |
Corner radius | Pixels, from 0 to 100. The snippet starts at 0. |
Show a subtle border | Adds a neutral one-pixel border around the iframe. Off unless you turn it on. |
Lazy load | Defers loading until the iframe approaches the viewport. On unless you turn it off. |
Embed settings¶
Embed settings is saved on the agent. Click Save settings to keep your changes.
Open links in a new tab — Applies to the widget, embedded chat, and AI website. When it has never been set, embedded chat and the AI website open links in a new tab. When off, links open in the same tab.
Chat unavailable message — Shown when the agent is disabled on the AI website and in Embedded chat (the iframe loads that same page). The chat widget does not show it; the widget stays hidden while the agent is disabled. The saved text is limited to 500 characters. If you leave it empty, the page uses “This agent is currently unavailable.”
2. Use Q as your website¶
Choose Use Q as your website when the agent should have its own page. The panel title is AI website: “Give your agent its own website — ready to share with anyone. No coding or existing website required.”
Copy the URL with Copy (Copy AI website URL) or open it with Open page. The address looks like https://chat.crafterq.ai/ followed by the Agent ID.
Page behavior on this panel has the same two saved fields as Embed settings: Open links in a new tab and Chat unavailable message. The unavailable message is shown on this page when the agent is disabled, and in an iframe of this page. It is not shown in the chat widget. Click Save settings to keep a change.
3. Analytics Integration (Google Analytics & Tag Manager)¶
The chat widget dispatches three browser events for visitor activity. It can forward those events to Google Analytics 4, to Google Tag Manager, or to both. The same events stay available to your own scripts.
The script embed (embed.js) runs on the host page. Its browser events, gtag calls, and dataLayer pushes use that page’s window. The Playground does not emit them. The hosted AI website and an embedded-chat iframe are covered under Limits below.
Console Widget settings¶
Open Deploy Agent → Add Q to your website → Chat widget → Widget settings. The same switches are under the agent’s Settings → User Interface → Widget hosting & embed overrides. On Deploy Agent they are shown only for the chat widget.
Switch | Default | What it does |
|---|---|---|
Emit Google Analytics events (emitGoogleAnalytics) | On | Calls |
Emit Google Tag Manager events (emitGTM) | Off | Pushes |
The panel shows an analytics notice. Google Analytics is on by default and Tag Manager is opt-in. With both switches on, that notice is an error. See Choosing a destination below.
The other fields in this panel (stacking z-index, open links, and custom CSS) are documented in Widget settings.
Embed options and precedence¶
A value in data-init-config or window.crafterq.init() replaces the saved agent value for that property. Omit the property to keep the saved value. The attribute itself, including the invalid-JSON fallback, is documented in Passing options with data-init-config above. The same keys belong in that JSON object.
When neither the snippet nor the agent sets emitGoogleAnalytics, it stays on. When neither sets emitGTM, it stays off. Pass true or false to override.
<script src="https://chat.crafterq.ai/embed.js"></script>
<script>
window.crafterq.init({
agentKey: '0198ed35-9f87-7711-8a93-2dfdc027e007',
// Opt out of gtag. The browser events below still fire.
emitGoogleAnalytics: false,
// Opt in to dataLayer pushes for Tag Manager.
emitGTM: true
});
</script>
Event reference¶
Each event is a CustomEvent dispatched on window. Listen on window:
window.addEventListener('crafterq_user_message', (e) => {
console.log('User sent:', e.detail.message);
});
window.addEventListener('crafterq_agent_message', (e) => {
console.log('Agent replied:', e.detail.message);
});
window.addEventListener('crafterq_open_chat', () => {
console.log('Chat was opened');
});
These browser events are dispatched whether the Google switches are on or off. The switches only control forwarding to gtag and dataLayer.
Event | When it fires | Browser event | What reaches GA and GTM |
|---|---|---|---|
| When the visitor sends a message: typed text, a quick message, a follow-up suggestion, or a retry. It fires as the message is sent, including when the reply later fails. Restoring an earlier chat does not fire it again. The Playground does not fire it. |
| The event name only. Google Analytics, when enabled and |
| Once, when a reply finishes successfully, with the full reply text. Tokens are not separate events while the reply streams. A reply the visitor stops, and a reply that fails, do not fire it. The Playground does not fire it. |
| The event name only: |
| Each time the chat window goes from closed to open. Sending a message while the window is closed opens it, so this event fires together with |
| The event name only: |
Google Analytics 4¶
Use this path when the host site already has a Google tag and you want the three event names in GA4.
Install your own Google tag (
gtag.js) for the GA4 web stream on the host site, sowindow.gtagexists before visitors chat. CrafterQ does not inject a tag and has no place to enter a measurement ID. A call made whilewindow.gtagis missing is skipped. The widget does not queue it for later. If the Google tag is deployed through Tag Manager,window.gtagis usually not defined, so use the Tag Manager path below instead.Leave Emit Google Analytics events on, or pass emitGoogleAnalytics as
true.Each forwarded event arrives in GA4 as a custom event. The event name is
crafterq_user_message,crafterq_agent_message, orcrafterq_open_chat. CrafterQ adds no event parameters (GA4 still records its automatic ones, such aspage_location).After GA4 has received an event, open Admin → Data display → Events and mark it as a key event if it should count in key-event reporting.
Google Tag Manager¶
Use this path when the host site routes tags through a container.
Turn Emit Google Tag Manager events on, or pass emitGTM as
true.Install your container snippet on the host page. The widget only pushes onto
dataLayer. It does not loadgtm.js.In the container, create a Custom Event trigger for each name you want to handle:
crafterq_user_message,crafterq_agent_message, andcrafterq_open_chat. The pushed object is{ event: '<name>' }only, so there is no message-text variable to map.Create a Google Analytics: GA4 Event tag. It needs your GA4 Measurement ID, or a Google tag already in the container. Set the event name to the same
crafterq_*name, or to a name you prefer, and fire the tag on that trigger.Preview the container, then publish it. Until it is published, Preview is the only place the tag runs.
Choosing a destination¶
Google Analytics — The site already loads a Google tag (
window.gtag), and the three event names in GA4 are enough. Leave Emit Google Analytics events on and Emit Google Tag Manager events off.Tag Manager — Events should pass through the container on their way to GA4, ads, or other tags. Turn Emit Google Tag Manager events on. When the container also forwards these events to GA4, turn Emit Google Analytics events (emitGoogleAnalytics) off so chats are not counted twice.
Your own listener — You need the message text, or the destination is something other than Google (for example Segment or Mixpanel). Subscribe to the
windowevents shown above. Turn both switches off when you do not want the built-ingtagordataLayercalls. The browser events still fire.Both switches — Keep both on only when the two paths feed different destinations. See the warning below.
Important
With both switches on, each chat action can be recorded twice in GA4: once by gtag('event', …) and again by a Tag Manager tag that forwards the dataLayer event to the same property. The Console shows this as an error on Widget settings (“Both analytics emitters are on”). Prefer one path, or keep both only when you intend separate destinations.
Limits¶
There are three event names. The Google calls do not include an agent id, chat id, user id, or message text.
The Google Analytics call is
gtag('event', '<event name>')with no parameter object.The Tag Manager object is
{ event: '<event name>' }and nothing else. The push createswindow.dataLayerwhen it is missing. Entries pushed before the container loads are processed when it loads. If the container never loads, nothing is sent to Google.A Google Analytics call that runs before
window.gtagexists is skipped.The Playground does not dispatch any of the three events. Testing in the Console does not show up in the site’s analytics.
The hosted AI website dispatches visitor and agent events on that page’s own
window. It does not dispatchcrafterq_open_chat, because the chat is already open. That page does not use the customer site’sgtagordataLayer.Embedded chat places that same standalone page in an
<iframe>. Events are dispatched inside the frame. They are not delivered to the host page, and the widget does notpostMessagethem to the parent. The host page’s listeners,gtag, anddataLayerare unchanged.crafterq_open_chatdoes not fire. The analytics switches are not shown for embedded chat; a value saved on the agent still applies inside the frame, which does not reach the host page’s tags. This limit is for the iframe only. A directembed.jsmount runs in the host page and dispatches on that page’swindow, so the events can reach the hostgtaganddataLayer.The welcome message is not an event. Opening an earlier chat does not replay its messages. An agent event is one completed reply, not one event per streamed token.
Add listeners with
window.addEventListener. The events are dispatched onwindow.
Privacy and consent¶
Consent is the host site’s responsibility. The widget does not read a cookie banner, does not call gtag('consent', …), and does not wait for Google Consent Mode. Configure consent on the Google tag or in Tag Manager so analytics storage stays denied until the visitor agrees. The forwarding switches are read when the widget loads, so turning forwarding on after consent requires calling window.crafterq.init() again. That call remounts the widget, so it has to carry the full config the page relies on, including agentKey, plus css, onMount, a custom openLinksInNewTab function, and theme, and the forwarding flags, for example emitGoogleAnalytics: true. The remount closes the chat window and stops a reply that is still streaming, so call it before the visitor opens the chat when you can. The conversation comes back only if it already had a completed reply, because the widget keeps it in the browser for 24 hours. To avoid the remount, leave forwarding on and let Google Consent Mode or Tag Manager consent settings hold the tags until the visitor agrees.
The built-in Google paths send the event name only. The browser events include the raw message text in event.detail.message for crafterq_user_message and crafterq_agent_message. That text is what the visitor sent and what the agent replied, and it can contain personal data. Forward it to another tool only when your privacy notice and consent cover that chat content.
Verification¶
GA4 DebugView. Put the Google tag in debug mode (set
debug_modetotrueon the tag, or use Google Tag Assistant). In the property, open Admin → Data display → DebugView. On the host page, open the chat and send a message. The custom event names should appear as you go.Tag Manager Preview. Start Preview, then open the chat and send a message on the host page. The
crafterq_*names should show up asdataLayermessages, and the GA4 Event tag should show as fired. Publish the container when the preview matches what you want.Tag Manager data layer. With Emit Google Tag Manager events on, run this in the host page’s browser console after you use the chat:
window.dataLayer.filter(function (entry) { return entry && String(entry.event || '').startsWith('crafterq_'); });
Each matching entry looks like
{ event: 'crafterq_open_chat' }. There is no message field.Browser events. The listener under Event reference logs
event.detail.messagefor visitor and agent messages.Nothing showed up. Confirm the page uses the script widget. The Playground, the AI website, and an iframe embed do not report into the host page’s tags. Confirm
typeof window.gtag === 'function'for the Google Analytics path. Confirm the embed snippet did not override the switch you saved in the Console. For Tag Manager, confirm the container is published and the trigger’s event name matches thecrafterq_*name exactly.
4. Testing Your Deployment¶
After embedding the script tag:
Load your website in a browser.
Confirm that the CrafterQ conversational panel or chat bubble appears as configured.
Click the UI and test a short conversation to verify connectivity.
To confirm Google Analytics or Tag Manager, use the checks in Analytics Integration.
Summary¶
The Deploy Agent screen gives you flexible options to deploy your CrafterQ agent:
Share an AI website when you choose Use Q as your website
Add a chat widget or embedded chat when you choose Add Q to your website
Customize behavior through Widget settings and Advanced embed options
Measure the chat widget with Google Analytics 4 or Google Tag Manager
Once deployed, your agent is live and ready to engage users — bringing AI-driven conversation directly into your digital experiences.