Complete User Guide
Everything you need to know to create, configure, and optimize your AI assistant with SmartChatAssistant.
Version 1.0 · Last updated: March 2026
1. Platform Overview
SmartChatAssistant is a SaaS platform that lets you create custom AI virtual assistants, trained on your business data, to integrate on any website via a simple JavaScript snippet.
↓
Management Dashboard
Supported AI Providers
| Provider | Models | Notes |
|---|---|---|
| OpenAI | GPT-4o, GPT-4o-mini | Requires API key |
| Google Gemini | Gemini Pro, Gemini Flash | Requires API key |
| Anthropic (Claude) | Claude Haiku 5.5 (default), Sonnet 5.5, Opus 5.5 | Requires API key |
| OpenRouter | Free models only (e.g. Gemma 4 31B, Nemotron), list refreshed daily | Free, with automatic fallback |
Available Plans
| Feature | Free | Pro (€29/mo) | Ultra (€99/mo) |
|---|---|---|---|
| Assistants | 1 | 5 | Unlimited |
| AI messages/month | 100 | 4,000 (~800 conversations) | 15,000 (~3,000 conversations) |
| Messages/day per assistant | 50 | 2,000 | 20,000 |
| AI Actions & Webhooks | — | ✓ | ✓ |
| Lead Capture | — | ✓ | ✓ |
| Human Handoff | — | ✓ | ✓ |
| Automatic web page refresh (KB) | Manual only | Every 7 days | Every day |
| Team members | 1 | 5 | 20 |
| Custom CSS | ✓ | ✓ | ✓ |
2. Public Area (Landing Page)
The landing page is the platform's showcase, accessible to anyone without login.
Section Details
Hero section
Feature cards
Plans & pricing
Footer
Landing Page Sections
"The AI assistant that doesn't just answer. It sells", sample chat with product cards, CTA "Build your Assistant for Free"
WooCommerce, WordPress, Shopify, Wix, OpenAI, Gemini
Section on the WooCommerce catalog: free plugin, recommendations of real products only, cards in chat, tracked clicks
80% cost reduction, 24/7, <2s response
All the main features
4 steps: Upload → Configure → Integrate → Analyze
Free / Pro / Ultra in AI messages, annual toggle, note on standard vs premium models
Invite a friend → 200 free AI messages
Privacy, Terms, Cookies and the public Security & GDPR page
3. Registration & Login
Registration
- Click "Start Free" or "Sign Up"
- Fill in: Name, Email, Password
- Confirm registration
- Verify your email address (yellow banner in dashboard)
Login
- Email + Password — classic form with brute-force protection
- Google OAuth — one-click login
Login with filled credentials:
Security: CSRF protection, rate limiting, httponly+samesite cookies, session with auto-expiry (1h inactivity).
4. Main Dashboard
Metric Cards
Assistants
N
Plan
Pro
AI messages
4,000
Usage
30%
Sidebar Navigation
Global
Dashboard, Assistants
Assistant
Settings, KB, FAQ, Actions, Leads, Widget, Welcome Rules, Webhooks, Conversations, Playground, Analytics, Handoff
Account
Admin, Account, Team, Billing, Logout
5. Assistant Management
Creating a new assistant
- Go to Assistants → New Assistant
- Fill in: Name, AI Provider, AI Model
- Optional: use the Prompt Wizard to generate the system prompt
- Click Create
AI Wizard for prompt generation:
Configuring an assistant
From the Settings page you can edit:
- General: Name, API Key (copy with one click)
- System Prompt: Personality, tone, expertise, limits + token indicator
- AI Model: Provider, Model, Max Context Tokens, Max History, BYOK, Fallback. With BYOK (your own API key) every reply always counts as 1 AI message, whatever the model or length.
Context Usage Bar: [System Prompt] + [FAQ] + [KB] + [History] + [Response] = Total tokens. Green <70%, Amber 70-90%, Red >90%.
Embed code
data-api-key="YOUR_API_KEY"
defer></script>
In-page chat (iframe): to have the chat always open inside a page of your site (e.g. "Support") instead of the bubble, use the In pagina (iframe) tab and paste the code where you want the chat. You choose width and height; it can be used together with the bubble.
style="width:100%;max-width:720px;height:600px;border:none;"
title="Chat" allow="microphone; clipboard-write" referrerpolicy="no-referrer-when-downgrade"></iframe>
6. Knowledge Base
The Knowledge Base is the assistant's "brain": the information it uses to answer questions.
4 Import Methods
Title + text content. Ideal for product descriptions, regulations.
PDF, TXT, DOCX, CSV (max 10 MB). Text extracted automatically.
Enter a URL, the system downloads and analyzes the content.
Starting URL, depth 1-3, max 1-20 pages. Import the entire site.
Example: Auto Crawl mode
Automatic refresh: pages imported from a URL or via crawl are re-crawled automatically (Pro every 7 days, Ultra every day; Free manual only). Only pages whose content changed are replaced; a snippet you edited by hand is excluded from the automatic update.
Tip: If the context is near the limit, disable less important snippets instead of deleting them.
7. Structured FAQ
Question/answer pairs with top priority in the assistant's context.
Creating a FAQ
- Main question — E.g. "What are your opening hours?"
- Variants — Alternative phrasings ("When do you open?", "Are you open on Saturday?")
- Answer — The exact answer the AI should provide
- Order — 1-100 (lower = higher priority)
FAQ creation form:
Best practice: Add at least 2-3 variants for each FAQ to improve recognition.
8. AI Actions
Allow the assistant to take action, not just answer. Pro+ Plan
The AI requests name, email, phone and saves automatically.
Shows a clickable button with a destination URL.
Sends a notification email to a specific address.
Calls an external endpoint with parameters and uses the response.
Action creation form:
Managing existing actions
Every action in the list has three controls: ON/OFF to enable or suspend it, the pencil to edit it and the bin to delete it. The pencil reopens the form already filled in, so you can fix the name, the instruction and the configuration (recipient, button URL, endpoint) without recreating the action from scratch. The type, however, cannot be changed.
Email Notification — multiple recipients and transcript. The recipient field accepts up to 5 comma-separated addresses, and each one gets its own copy. The email carries the notification reason plus the conversation transcript, which makes it a good end-of-session summary.
Several actions in one reply. The assistant can trigger more than one action at a time (for example lead collection and an email notification when closing) and all of them run. In the Playground actions are simulated: the email is not actually sent, so use the real widget for an end-to-end test.
9. Lead Management
Collects all contacts captured during conversations. Pro+ Plan
Each lead: name, email, phone, status, date. You can change status, add notes, export to CSV.
Lead form fields
On the Leads page, the “Lead form fields” panel decides what the visitor is asked for:
- Standard fields — Name, Email, Phone, Company, Message: each one can be switched on individually and has its own “Required” option.
- Custom fields — up to 5, comma-separated (e.g.
Car make, Registration year). The label you type is the one shown in the widget, and it is also the name the value appears under in the lead detail, in the email and in the CSV export. They are always optional for the visitor.
Changes apply from the next widget load: reload the page hosting it to see them.
Where leads are delivered. Every lead sends an email with the collected data and the chat transcript. By default it goes to your account address; to receive it elsewhere open AI Actions → Lead Collection → pencil and set one or more recipients (max 5, comma-separated).
10. Widget Settings
Colors (6 independent)
Appearance
Messages
Behavior
GDPR & Security
Custom CSS
Your CSS is applied inside the widget after the base styles, so it overrides them without needing !important. It stays confined to the widget: it cannot affect the host site.
Available selectors: #sca-container (with the .sca-bottom-right and .sca-bottom-left variants), #sca-toggle for the button, #sca-window for the chat window.
/* button and window 100px above the bottom */
#sca-container.sca-bottom-right,
#sca-container.sca-bottom-left { bottom: 100px; }Maximum 10,000 characters. @import, javascript: and the <script> / </style> tags are not allowed: saving is rejected with a message naming the sequence to remove. Changes show up when the page hosting the widget is reloaded.
11. Welcome Rules
Different welcome messages based on the page the visitor is browsing.
| URL contains | Message | Suggestions |
|---|---|---|
| /pricing | Have questions about our plans? | Compare plans, How much? |
| /product/ | Want to know more about this product? | Features, Availability |
| /contact | Can I help you find the right contact? | Tech support, Sales |
Rule creation form:
12. Template Library
Ready-to-use templates for different industry verticals: optimized prompts, FAQs, and welcome rules.
Available Sectors
Template system prompt
FAQs included in the template
How to use a template
- Go to sidebar → Template Library
- Browse sectors and click the one you're interested in
- Review: System Prompt, FAQ, and Welcome Rules
- Select with checkboxes what to import
- Click Apply Template
Best practice: Use the template as a starting point, then customize every element with your actual business data.
13. Webhooks
Send real-time notifications to external systems. Pro+ Plan
No-code automations
Salesforce, HubSpot
Channel notifications
Conversation logs
14. Conversations
Complete chat history: Session ID, dates, message count, referrer URL.
Conversation detail:
Best practice: Periodically review conversations to identify recurring questions → create new FAQs or enrich the KB.
15. Playground
Isolated test environment to try your assistant before going live.
Example Playground conversation:
Best practice: After every change to KB, FAQ, or prompt, always test in the Playground before going live.
16. Analytics
Detailed performance metrics. Period: 7, 30, or 90 days. Advanced charts: Pro+
Unique sessions
Total exchanged
Average latency (ms)
% thumbs up
Most active hour
6 Interactive Charts
- Conversations per day (Line chart)
- Average response time (Line chart)
- Satisfaction over time (Trend)
- Activity by hour (Bar chart 24h)
- Tokens consumed (Stacked bar)
- Lead conversion funnel (Horizontal bar)
17. Human Handoff
When the AI can't help, the visitor can request a human operator. Pro+ Plan
Visitor Side
"Talk to operator" button → handoff request → waiting message
Operator Side
Badge with pending requests → read AI conversation → reply → resolve
18. Multi-user Team
| Role | Permissions |
|---|---|
| Admin | Full access, team management, billing |
| Editor | Create/edit assistants, KB, FAQ, actions |
| Viewer | View only |
Free: 1 member · Pro: 5 · Ultra: 20
19. Account & Notifications
Profile
Edit name, email, password
Email Notifications
New lead, low AI messages, pending handoff, weekly report
20. Billing & AI Messages
| Package | Price |
|---|---|
| 1,000 AI messages | €9.99 |
| 5,000 AI messages | €39.99 |
| 15,000 AI messages | €99.99 |
How they work: 1 credit = 1 AI message = one AI reply generated on a standard model (gpt-4.1-nano, gpt-4o-mini, gpt-4.1-mini, gemini-2.5-flash-lite, gemini-3.1-flash-lite, gemini-2.5-flash, gemini-3-flash-preview, claude-haiku-5-5, OpenRouter free models). Premium models (GPT-4o, GPT-4.1, Gemini Pro models, gemini-3.5-flash, Claude Sonnet 5.5 and Opus 5.5, any paid OpenRouter model or custom model ID) count 5 AI messages per reply.
Long replies: when context + output exceed 8,000 tokens, one extra step is counted per 8,000 tokens (e.g. 12,000 tokens = 2 AI messages on a standard model, 10 on a premium model).
BYOK: if the assistant uses your own API key, every reply counts as 1 AI message, with no model or length multipliers.
Referral: Invite friends → 200 free AI messages for both. Unlimited invites.
21. Export / Import Assistants
Export button in assistant list
Assistant import form
Export
Download complete JSON package: configuration, KB, FAQ, Actions, Widget Settings, Welcome Rules.
Import
Upload an exported JSON → new assistant with full configuration.
22. Website Integration
data-api-key="YOUR_API_KEY"
defer></script>
How It Works
- The script loads configuration from the API
- Displays the bubble in the configured corner
- On click, opens the chat window
- If required, shows the GDPR banner
- Messages sent → API → AI responds
- Session persists for the configured duration
Multi-language: The widget detects the browser language and automatically replies in the same language (15+ languages).
23. Security & GDPR
Security
- Sensitive data encryption
- CSRF Protection
- Rate Limiting
- Content Security Policy
- Forced HTTPS
- Hashed IPs (SHA-256)
- Two-factor authentication (2FA)
- Lead data encrypted with AES-256
- Servers in Italy (EU)
GDPR Compliance
- Prior consent
- Privacy notice in widget
- Right to erasure
- Right to data export
- Conversation anonymisation: 30 days (Free), 90 (Pro), 365 (Ultra)
- No OpenAI/Gemini/Anthropic model training on your content
- DPA on request (Pro and Ultra)
Public Security & GDPR page: share it with your customers. It explains roles (you are the controller, SmartChatAssistant the Art. 28 processor), data flow, sub-processors, model training (exception: OpenRouter free models may log prompts) and how to request the DPA: email privacy@smartchatassistant.com from your account address, with company name, VAT number and privacy contact.
24. Admin Panel
Accessible only to users with the platform administrator role.
- User List — all registered users
- Assistants per User — view assistants for a specific user
25. Best Practices
System Prompt
Clearly define the role
Specify the tone (formal, informal, technical)
List the topics it can discuss
Define boundaries ("Don't make up information")
Indicate how to handle off-topic questions
Add instructions for lead collection
Knowledge Base
Keep snippets up to date
Use descriptive titles
Disable (don't delete) temporary snippets
Monitor the context bar — don't exceed 80%
FAQ
At least 3 variants per question
Concise and precise answers
Low order values (10-20) for critical FAQs
Widget
Colors consistent with your brand
Engaging welcome message
2-4 suggested messages
Enable GDPR consent
Test on mobile
Monitoring
Check weekly "Unanswered Questions"
Monitor satisfaction — below 70% review prompt and KB
Analyze the lead funnel
Check response time — if >5s, switch to a faster model
26. Checklist — From Zero to Live
Phase 1 — Setup
Phase 2 — Create Assistant
Phase 3 — Training
Phase 4 — Widget
Phase 5 — Go Live
27. Troubleshooting
The widget doesn't appear on my site
- Verify the snippet is in the page's
<head> - Check the API key is correct
- Verify allowed domains (or leave empty to accept all)
- Open browser console (F12) and look for JavaScript errors
- Verify the assistant is active
The assistant doesn't respond
- Verify you have enough AI messages
- Check the AI provider configuration
- If using BYOK, verify the API key is valid
- Check logs for connection errors
Responses are inaccurate
- Review the system prompt — is it specific enough?
- Add FAQs for problematic questions
- Verify the KB is correct and up to date
- Check the context bar — if at 100%, possible truncation
GDPR consent doesn't appear
- Verify "Privacy notice in the chat" is not set to None
- With the Notice, once the visitor closes it with the X it is not shown again in that browser
- Check the consent message is not empty
Leads are not being captured
- Verify the "Lead Collection" action is active
- Check the system prompt for data collection instructions
- Verify you have a plan that supports leads (Pro or Ultra)
28. WooCommerce Catalog
From the Pro plan (up to 2,000 products; Ultra 20,000). The assistant recommends products from your WooCommerce shop based on what the visitor needs and shows them as clickable cards (image, name, price, attributes) linking to the product page on your site. No sector-specific setup: what tells a pharmacy from a clothing store is your data and the instructions you write.
How it works
- Install the SCA Connector for WooCommerce plugin on your WordPress site: it builds the catalog feed and rebuilds it in the background at the interval you choose.
- SmartChatAssistant reads the feed (hourly by default, full once a day). Your site never sends anything.
- Every read produces a catalog schema (categories, attributes with their frequent values, price range) that goes into the prompt, so the AI understands your sector on its own.
- During the chat the assistant searches the catalog (text, category, price, availability, attributes), several times per turn if needed, proposes one to a few products, asks a clarifying question when the need is vague and never proposes sold-out products.
Setup
- Plugin (WooCommerce → SCA Connector): feed URL and token to copy, regeneration interval (15 min – 24 h or custom), rebuild on product save, extra meta fields to export, preview, last regeneration status, "Regenerate now", last read by SmartChatAssistant.
- Dashboard (assistant → Catalog): URL and token, "Test connection", read interval, search mode, max products per reply, advice instructions (what to ask and what to avoid in your sector), attributes shown on cards (max 3), UTM parameters, on/off switch, "Sync now" and status.
- Widget: card carousel under the reply, click opens a new tab, JavaScript event
sca:product_clickfor Google Tag Manager.
Tip: in the Playground with debug on, the "Catalogo WooCommerce" section lists the searches the model ran and the products it picked: use it to tune your advice instructions.
29. Connecting Claude (MCP connector)
From the Pro plan. Connect Claude.ai, Claude Cowork and Claude Code to your account: Claude reads assistants, knowledge base, FAQs, conversations, leads and analytics, tests the assistant's replies and, with write access, edits prompts, FAQs, knowledge and widget texts and replies to handoffs. Everything goes through the same checks as the dashboard and is logged in Account → Claude / MCP.
Claude.ai and Claude Cowork
- On claude.ai open Settings → Connectors (Cowork: Connectors) and choose Add custom connector.
- Name:
SmartChatAssistant. URL:https://app.smartchatassistant.com/mcp. Leave client ID and secret empty. - Click Connect: SmartChatAssistant's authorization page opens (log in first if needed).
- Pick the access level (read-only or read and write) and which assistants to share, then Authorize.
- In a chat with Claude enable the connector and ask, for example: "List my assistants", "Summarise last week's conversations of assistant X", "Draft 10 FAQs from the unanswered questions".
Claude Code
- In Account → Claude / MCP create a personal token (name, access level, assistants) and copy it right away: it is shown only once.
- In the terminal run:
claude mcp add --transport http smartchatassistant https://app.smartchatassistant.com/mcp --header "Authorization: Bearer YOUR_TOKEN"Without a token: claude mcp add --transport http smartchatassistant https://app.smartchatassistant.com/mcp, then /mcp inside Claude Code to sign in through the same authorization page used by Claude.ai.
What Claude can do
Read-only
See configuration, knowledge, FAQs, actions, widget, conversations, unanswered questions, leads, handoffs, analytics, catalog. Ask the assistant questions as a visitor would (spends AI messages like the widget) and inspect the exact prompt the model receives.
Read and write
Also: create new assistants (within the plan limit), change name, prompt and model, add/edit/delete knowledge and FAQs, import a web page, update widget texts, change lead status and notes, reply to and close handoffs. Deletions always require an explicit confirmation.
Security
- Claude only sees your assistants (and only those chosen when authorizing).
- Every connection can be revoked with one click in Account → Claude / MCP, which also lists the latest calls.
- Provider API keys and action secrets are never exposed.
- Limit of 60 calls per minute per connection (more on higher plans).
© 2026 SmartChatAssistant — by Gabriele Ferrari
Need help? support@smartchatassistant.com