PHPackages                             eventiva/craft-chatagent - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. eventiva/craft-chatagent

ActiveCraft-plugin

eventiva/craft-chatagent
========================

Plugin name: Chatagent

1.0.0(2w ago)01[1 issues](https://github.com/eventiva-solutions/CraftCMS-Chatagent/issues)proprietaryPHPPHP &gt;=8.2CI passing

Since Mar 5Pushed 1w agoCompare

[ Source](https://github.com/eventiva-solutions/CraftCMS-Chatagent)[ Packagist](https://packagist.org/packages/eventiva/craft-chatagent)[ RSS](/packages/eventiva-craft-chatagent/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

ChatAgent - AI Chatbot Plugin for Craft CMS
===========================================

[](#chatagent---ai-chatbot-plugin-for-craft-cms)

**ChatAgent** is a powerful AI chatbot plugin for Craft CMS that lets you train a smart assistant on your own content and deploy it directly on your website - without any third-party chat platform. Feed it your Craft entries, uploaded files, URLs, or custom Q&amp;A pairs, and your visitors get instant, accurate answers based on your actual content.

---

Requirements
------------

[](#requirements)

- Craft CMS 5.9.0 or later
- PHP 8.2 or later
- OpenAI API Key

---

Installation
------------

[](#installation)

#### From the Plugin Store

[](#from-the-plugin-store)

Go to the Plugin Store in your project's Control Panel and search for **"ChatAgent"**. Then press **Install**.

---

Features at a Glance
--------------------

[](#features-at-a-glance)

- **4 Training Sources** - Craft Entries, File Upload, URL / Sitemap, Q&amp;A Pairs
- **Dashboard** with conversation stats, charts, and training metrics
- **Chat Logs** with full session history, search, and filtering
- **Confidence Score** per bot response, color-coded for quick review
- **Thumb Up / Down Ratings** - user feedback directly in the chat widget
- **Q&amp;A Import from Logs** - turn any chat response into training data
- **Auto-Train on Entry Save** - index content automatically as you publish
- **Queue Manager Support** - background processing, no UI blocking
- **Custom System Prompt** - full control over AI persona and behavior
- **Light / Dark Mode** toggle in the chat widget
- **Full Customization** - colors, logo, company name, greeting, preset questions
- **Log Color Grading** - confidence levels highlighted at a glance

---

Training Your Chatbot
---------------------

[](#training-your-chatbot)

The chatbot's knowledge comes entirely from content you provide. You can train it from four different sources, all accessible under **Chatbot → Training** in the Control Panel.

### Craft Entries

[](#craft-entries)

Train the chatbot on your existing Craft CMS content in just a few clicks.

- Select which **sections** the chatbot should learn from
- Click **"Train now"** to index all entries from the selected sections
- Each entry is split into chunks and stored as vector embeddings
- A table shows every indexed entry with its chunk count and last training date
- Individual entries can be re-trained or removed from the index
- Click into an entry to **inspect its chunks** and see exactly what the AI knows

### File Upload

[](#file-upload)

Upload plain-text documents directly to the training index.

- Supports `.txt` and `.md` files (max 5 MB each)
- Drag-and-drop or click to browse
- Files are indexed immediately after upload
- Manage uploaded files in a table: re-index or delete individual files

### URL / Sitemap Training

[](#url--sitemap-training)

Point the chatbot at any public webpage or import an entire sitemap at once.

- Paste a **sitemap XML URL** to automatically discover and import all pages
- Or enter **individual URLs** manually (one per line)
- Click **"Crawl all &amp; index"** to process all queued URLs
- Each URL shows a status badge: `pending`, `indexed`, or `error`
- Click into a URL to inspect its extracted chunks
- Re-crawl or delete individual URLs at any time

### Q&amp;A Training

[](#qa-training)

Define exact question-and-answer pairs to give the chatbot precise, reliable responses to common questions.

- Add pairs manually via a simple form (question + answer)
- Or **import directly from Chat Logs** - turn any real bot response into a training pair with one click
- Toggle pairs active / inactive without deleting them
- Pairs show their source: `Manual` or `Log`
- Saved pairs are immediately indexed and available to the chatbot

---

Dashboard
---------

[](#dashboard)

The Dashboard gives you a live overview of how your chatbot is being used and what it knows.

### Conversation Statistics

[](#conversation-statistics)

- **Total Conversations** - number of chat sessions
- **Total Messages** - all messages sent and received
- **Average Response Time** - bot latency in seconds
- **Average Conversations per Day**
- **Positively Rated / Negatively Rated** messages (when ratings are enabled)

Filter all stats by date range using the date picker or quick presets (Last 7 days, Last 30 days, Last 90 days). Stats refresh instantly without a page reload.

### Activity Chart

[](#activity-chart)

An interactive line chart shows conversation and message volume over time - helpful for spotting peaks or drops in chatbot usage.

### Suggestion Statistics

[](#suggestion-statistics)

See which preset questions your visitors click most, with usage counts per suggestion.

### Training Data Summary

[](#training-data-summary)

- Indexed entry count, chunk count, sections, and last training date
- Indexed file count, chunk count, and last indexing date

---

Chat Logs
---------

[](#chat-logs)

Every conversation is stored and fully accessible under **Chatbot → Chat Logs**.

### Session List

[](#session-list)

Browse all chat sessions in a filterable, paginated table.

**Filter by:**

- Search by session ID
- Rating (All, Positive, Negative)
- Confidence level (High ≥ 80%, Medium 60–79%, Low &lt; 60%, No context)

**Each row shows:**

- Session ID, page URL, message count
- Rating summary (thumbs up / down ratio)
- Color-coded confidence badge
- IP address and timestamp

### Session Detail View

[](#session-detail-view)

Click any session to see the full conversation.

- Every message shows its role (User or Bot), timestamp, and response time
- Bot messages display a **confidence score badge** (color-coded)
- If the user rated a message, a **thumbs up (green)** or **thumbs down (red)** icon is shown
- Messages used as Q&amp;A training sources are marked with a **"✓ Q&amp;A Training"** badge
- A **"Use as Q&amp;A"** button is available on every bot message - one click creates a new training pair

### Color Grading

[](#color-grading)

Confidence scores are color-coded throughout the log views for instant visual scanning:

ScoreColorMeaning≥ 80%GreenHigh confidence - strong context match60–79%YellowMedium confidence&lt; 60%RedLow confidence - weak or partial context-WhiteNo context used---

Confidence Score
----------------

[](#confidence-score)

Every bot response is automatically assigned a confidence score between 0 and 1, based on how closely the retrieved context matches the user's question.

- Displayed as a **color-coded percentage** badge on each message
- Visible in the session list and the full session detail view
- Configurable **minimum similarity threshold** (Settings → AI Configuration)
- Low-confidence responses can be reviewed and improved by adding targeted Q&amp;A pairs

---

Thumb Up / Down User Ratings
----------------------------

[](#thumb-up--down-user-ratings)

Visitors can rate individual bot responses directly in the chat widget.

- Thumbs up / down buttons appear below each bot response (when enabled in Settings → Logging)
- Ratings are stored per message and visible in Chat Logs
- Aggregated rating counts appear in the Dashboard
- Filter Chat Logs by rating to quickly find poorly received answers

---

Auto-Train on Entry Save
------------------------

[](#auto-train-on-entry-save)

When this feature is enabled (Settings → Training), any entry saved in the Craft Control Panel is automatically indexed in the background - no manual training needed.

- Works for all sections selected for training
- Creates a background queue job on every entry save
- Keeps your chatbot's knowledge current as you update content
- Can be toggled off at any time without losing existing index data

---

Queue Manager Support
---------------------

[](#queue-manager-support)

Long training operations (large sitemaps, many entries) run as background jobs via Craft's built-in Queue system.

- Training and crawl jobs are queued automatically
- The UI shows how many jobs were queued and links to **Utilities → Queue**
- No blocking of the Control Panel during processing
- You can continue working while training runs in the background

---

Settings &amp; Customization
----------------------------

[](#settings--customization)

All settings are under **Chatbot → Settings**, organized in tabs.

### General

[](#general)

SettingDescriptionEnable ChatbotShow or hide the widget on the frontendCompany NameDisplayed in the chat headerLogo TextUp to 3 characters, shown as a badge if no logo image is setLogo ImageSquare image (min 80×80 px) used as the chat avatarPrimary ColorColor for buttons and user message bubblesLogo Background ColorBackground color behind the logo in the chat headerDefault ThemeStart in Light or Dark mode### AI Configuration

[](#ai-configuration)

SettingDescriptionOpenAI API KeyRequired for all AI functionsChat Model`gpt-4o-mini` (recommended), `gpt-4o`, or `gpt-3.5-turbo`Embedding Model`text-embedding-3-small` (recommended), `-large`, or `ada-002`Initial MessageThe bot's first greeting when the chat opensSystem PromptFull instructions / persona for the AI - define tone, language, scope, restrictionsMax Context ChunksHow many matching text chunks are passed as context (1–20, default 5)Min Similarity ScoreMinimum relevance threshold for context retrieval (0.00–1.00, default 0.65)> **Note:** Switching the embedding model requires full retraining of all content.

### Training

[](#training)

- Select which Craft sections are included in training
- Enable or disable **Auto-Train on Entry Save**

### Suggestions

[](#suggestions)

- Toggle preset question buttons on or off
- Enter up to 4 preset questions (one per line)
- Questions appear as clickable buttons below the initial greeting

### Logging

[](#logging)

- Enable or disable **Message Ratings** (thumbs up / down)
- Enable or disable **Conversation Logging**
- Set a **Log Retention** period in days (0 = keep forever)

---

Chat Widget
-----------

[](#chat-widget)

The chat widget appears as a floating button on your website (bottom right by default). Visitors click it to open the chat window.

**Widget features:**

- Company name and logo in the header
- Dark / Light mode toggle (moon icon)
- Refresh button to start a new conversation
- Preset suggestion buttons (if enabled)
- Send message with button or Enter key
- Loading animation while the bot processes
- Thumbs up / down buttons per response (if enabled)

The widget's colors, logo, greeting, and default theme are all controlled from the Settings page in the Control Panel.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance97

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c619a06012909dfbf41dee86c41050abebfda0aa4d1b6c35a341aabda458c762?d=identicon)[vxdy](/maintainers/vxdy)

---

Top Contributors

[![marcobajtl](https://avatars.githubusercontent.com/u/89908956?v=4)](https://github.com/marcobajtl "marcobajtl (6 commits)")[![renex05](https://avatars.githubusercontent.com/u/106073656?v=4)](https://github.com/renex05 "renex05 (6 commits)")[![vxdy](https://avatars.githubusercontent.com/u/60035996?v=4)](https://github.com/vxdy "vxdy (2 commits)")

### Embed Badge

![Health badge](/badges/eventiva-craft-chatagent/health.svg)

```
[![Health](https://phpackages.com/badges/eventiva-craft-chatagent/health.svg)](https://phpackages.com/packages/eventiva-craft-chatagent)
```

###  Alternatives

[nystudio107/craft-seomatic

SEOmatic facilitates modern SEO best practices &amp; implementation for Craft CMS 5. It is a turnkey SEO system that is comprehensive, powerful, and flexible.

1741.4M36](/packages/nystudio107-craft-seomatic)[craftcms/aws-s3

Amazon S3 integration for Craft CMS

631.5M21](/packages/craftcms-aws-s3)[nystudio107/craft-retour

Retour allows you to intelligently redirect legacy URLs, so that you don't lose SEO value when rebuilding &amp; restructuring a website

40964.5k13](/packages/nystudio107-craft-retour)[craftcms/ckeditor

Edit rich text content in Craft CMS using CKEditor.

48344.0k32](/packages/craftcms-ckeditor)[nystudio107/craft-plugin-vite

Plugin Vite is the conduit between Craft CMS plugins and Vite, with manifest.json &amp; HMR support

13924.6k36](/packages/nystudio107-craft-plugin-vite)[engram-design/supertable

Super-charge your content builders and create nested Matrix fields.

3141.3k](/packages/engram-design-supertable)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
