ChatProjects Documentation

ChatProjects Pro is a WordPress plugin that transforms your website into a powerful AI workspace. Unlike SaaS chat tools that require monthly subscriptions and store your data on external servers, ChatProjects lets you:

• Use your own API keys - Pay only for what you use, directly to AI providers
• Keep data on your server - All conversations stored in your WordPress database
• Chat with 5+ AI providers - Switch between GPT-5, Claude, Gemini, DeepSeek, and 100+ models via OpenRouter
• Create knowledge-based projects - Upload documents and chat with their contents using Vector Stores and the Responses API
• White-label for clients - Full branding customization for agencies PRO

Who is ChatProjects For?

Audience	Use Case
WordPress Agencies	Deploy white-labeled AI solutions for clients
Businesses	Private AI chat without third-party SaaS dependencies
Development Teams	Multi-provider AI access with project-based organization
Content Creators	Audio transcription, prompt libraries, and AI-assisted writing
Consultants	Document-based Q&A for client knowledge bases

Why ChatProjects vs. ChatGPT or Claude Directly?

Server Requirements

Requirement	Minimum	Recommended
WordPress	5.8+	6.0+
PHP	7.4+	8.1+
MySQL	5.6+	8.0+
MariaDB	10.0+	10.6+

Required PHP Extensions

• OpenSSL - For API key encryption (AES-256)
• cURL - For API communication with AI providers

Memory & Upload Settings

Setting	Minimum	For Large Files
memory_limit	128MB	256MB+
upload_max_filesize	50MB	512MB
post_max_size	50MB	512MB
max_execution_time	60	300

Browser Support

Browser	Minimum Version
Chrome	80+
Firefox	75+
Safari	13+
Edge	80+
iOS Safari	13+
Chrome for Android	80+

Installing the Plugin

Method 1: WordPress Plugin Directory (Free Version)

1. Go to Plugins > Add New in your WordPress admin
2. Search for "ChatProjects"
3. Click Install Now
4. Click Activate

Method 2: Manual Upload (Pro Version)

1. Download the Pro plugin ZIP file from your account
2. Go to Plugins > Add New > Upload Plugin
3. Choose the ZIP file and click Install Now
4. Click Activate

Method 3: FTP Upload

1. Download and extract the plugin ZIP file
2. Upload the chatprojects-pro folder to /wp-content/plugins/
3. Go to Plugins in WordPress admin
4. Click Activate next to ChatProjects Pro

Initial Configuration Checklist

1. Navigate to ChatProjects > Settings in the WordPress admin menu
2. Add at least one API key - OpenAI is required for project features
3. Configure default provider - Select your preferred AI provider
4. Set default model - Choose the model for new conversations
5. Configure file upload limit - Adjust if needed (default: 50MB)
6. Create a page - Add the [chatprojects_main] shortcode to any page
7. Test the interface - Visit your page and send a test message

Upgrading from Free to Pro

1. Deactivate the free ChatProjects plugin (do not delete)
2. Install ChatProjects Pro using Method 2 or 3 above
3. Activate ChatProjects Pro
4. Your settings, projects, and chat history are automatically preserved

You need at least one API key to use ChatProjects. OpenAI is required for project features (Vector Stores and file search).

Provider	Required For	Key Format
OpenAI	Projects, Vector Stores, File Search, GPT models	sk-...
Anthropic	Claude models (optional)	sk-ant-...
Google Gemini	Gemini models (optional)	AIza...
Chutes	DeepSeek models (optional)	cpat_... or cpk_...
OpenRouter	100+ models (optional)	sk-or-...

OpenAI API Key

Required for: Projects, Vector Stores, File Search, GPT models

1. Visit platform.openai.com
2. Sign up or log in to your account
3. Go to API Keys in the left sidebar
4. Click Create new secret key
5. Copy the key (starts with sk-)
6. Paste into ChatProjects Settings

Pricing: Pay-per-use based on tokens. See openai.com/pricing

Anthropic API Key

Required for: Claude models

1. Visit console.anthropic.com
2. Sign up or log in
3. Go to Settings > API Keys
4. Create a new key (starts with sk-ant-)
5. Copy and paste into ChatProjects Settings

Google Gemini API Key

Required for: Gemini models, Image Studio PRO

1. Visit ai.google.dev
2. Sign in with your Google account
3. Click Get API Key
4. Create a key in a new or existing project (starts with AIza)
5. Copy and paste into ChatProjects Settings

Chutes API Key

Required for: DeepSeek models

1. Visit chutes.ai
2. Sign up or log in
3. Navigate to API settings
4. Generate your API key
5. Copy and paste into ChatProjects Settings

OpenRouter API Key

Required for: 100+ models from multiple providers

1. Visit openrouter.ai
2. Sign up or log in
3. Go to Keys section
4. Create a new key (starts with sk-or-)
5. Copy and paste into ChatProjects Settings

OpenAI Models

Model	Description	Best For
GPT-5.2	Latest multimodal flagship	General purpose, complex tasks
o1-preview	Advanced reasoning	Complex problem solving, math
GPT-4.1	Fast and economical	Simple tasks, prototyping

Anthropic Claude Models

Model	Description	Best For
Claude Opus 4.5	Most capable flagship	Complex analysis, research
Claude 3.5 Sonnet	Fast and highly capable	General tasks, coding
Claude 3.5 Haiku	Fastest Claude model	Quick responses, high volume

Google Gemini Models

Model	Description	Best For
Gemini 2.5 Pro	Latest flagship model	Complex tasks, analysis
Gemini 2.0 Flash	Latest fast model	Quick tasks, streaming
Gemini 1.5 Pro	High capability	Long context, analysis
Gemini 1.5 Flash	Fast and efficient	Everyday use

Chutes Models

Model	Description	Best For
DeepSeek V3	Latest DeepSeek	General purpose, coding
DeepSeek R1	Reasoning model	Complex analysis, math
Qwen 2.5	Alibaba's flagship	Multilingual, coding
Mistral Large	Mistral AI flagship	European AI, multilingual

OpenRouter

OpenRouter provides access to 100+ models from multiple providers through a single API, including models from OpenAI, Anthropic, Google, Meta, Mistral, and more.

Chat Modes

Mode	Description	Availability
General Chat	Direct AI conversation without project context	Free & Pro
Project Chat	AI searches uploaded documents for context (RAG)	Free & Pro
Model Comparison	Side-by-side responses from two models	PRO

Starting a Conversation

1. Select Provider - Use the dropdown to choose your AI provider
2. Select Model - Choose from available models for that provider
3. Type your message - Enter your question or prompt
4. Press Enter or click Send

Messages stream in real-time as the AI generates responses.

Managing Chat History

Auto-Generated Titles

Chat titles are automatically generated from your first message. You can rename them at any time.

Renaming Chats

1. Click the chat name in the sidebar
2. Enter a new name
3. Press Enter to save

Deleting Chats

1. Hover over a chat in the sidebar
2. Click the delete icon (trash)
3. Confirm deletion

Switching Providers Mid-Conversation

You can switch AI providers or models at any point in a conversation. The new provider/model will be used for that message and subsequent ones. Your conversation context is maintained.

Dark/Light Mode

ChatProjects includes full dark mode support:

• Automatic detection - Follows your system preference by default
• Manual toggle - Click the theme toggle in the header
• Persistent preference - Your choice is saved for future sessions

Projects are organized workspaces where you can upload documents and have AI-powered conversations about their contents.

Creating a New Project

1. Navigate to the Projects tab
2. Click New Project
3. Fill in the project details:

   Field	Description	Required
   Title	Project name (e.g., "Product Documentation")	Yes
   Description	What this project contains	No
   Instructions	Custom AI behavior for this project	No

4. Click Create Project

Project Custom Instructions

Custom instructions define how the AI should behave when answering questions about your project documents.

Example: Technical Support

You are a technical support agent for our software product.
Answer questions based on the uploaded documentation.
Be concise and cite specific document sections when possible.
If you don't find the answer in the documents, say so.

Example: Research Assistant

You are a research assistant helping analyze uploaded papers.
Summarize findings, compare methodologies, and identify key conclusions.
Cite specific papers and page numbers when referencing information.

Project Sharing PRO

Mode	Description
Private	Only you (the owner) can access
Shared	Invite specific WordPress users
Public	All logged-in users can access

Free vs Pro Project Limits

Feature	Free	Pro
Number of Projects	5	Unlimited
Project Ownership	Shared (all users)	Per-user
Sharing Controls	No	Yes

RAG (Retrieval-Augmented Generation) allows the AI to search your uploaded documents and provide answers based on their contents.

How Vector Stores Work

When you upload files to a project:

1. Upload - Files are sent to OpenAI's servers
2. Processing - OpenAI extracts and chunks the text content
3. Embedding - Text is converted to vector embeddings
4. Indexing - Vectors are stored in your project's Vector Store
5. Search - When you chat, AI searches for relevant content
6. Answer - AI uses found content to generate contextual answers

Supported File Types

Documents

Type	Extensions
PDF	.pdf
Word	.doc, .docx
Text	.txt
Markdown	.md
PowerPoint	.pptx

Data Files

Type	Extensions
CSV	.csv
JSON	.json
XML	.xml
HTML	.html

Code Files

Type	Extensions
JavaScript	.js
Python	.py
PHP	.php
CSS	.css

Spreadsheets

Type	Extensions
Excel	.xls, .xlsx
ODS	.ods

File Size Limits

Setting	Default	Maximum
Per File	50 MB	512 MB

Uploading Files

1. Open your project
2. Go to the Files tab
3. Drag and drop files onto the upload area, or click to browse
4. Wait for the upload progress to complete
5. Files are automatically indexed (may take a few moments for large files)

Embed ChatProjects anywhere on your WordPress site using shortcodes.

Main Application Shortcode

[chatprojects_main]

Renders the full ChatProjects application including navigation tabs, sidebar, chat interface, and project management.

Attributes

Attribute	Values	Default	Description
default_tab	chat, projects	chat	Initial tab to display
height	Any CSS value	80vh	Container height

Examples

[chatprojects_main]
[chatprojects_main default_tab="projects"]
[chatprojects_main height="600px"]

Widget Shortcode (Floating Chat)

[chatprojects_widget]

Renders a floating chat widget that can be positioned anywhere on the page.

Widget Attributes

Attribute	Values	Default
position	bottom-right, bottom-left, top-right, top-left	bottom-right
height	Any CSS value	500px
width	Any CSS value	400px
theme	light, dark, auto	auto
collapsed	true, false	false
draggable	true, false	false

Widget Examples

[chatprojects_widget]
[chatprojects_widget position="bottom-left" height="600px" width="450px"]
[chatprojects_widget theme="dark" collapsed="true"]
[chatprojects_widget draggable="true" button_icon="robot" button_color="#10b981"]

Build and manage a library of reusable AI prompts for consistent, high-quality interactions.

What's Included

• 100+ professionally-crafted professional prompts covering common use cases
• 8 categories for organization: General, Assistant, Code Generation, Content Writing, Analysis, Creative, Business, Education

Default Prompt Categories

Category	Prompts	Examples
General	2	Quick Answer, Summarize Text
Assistant	10	Professional Assistant, Code Review Expert, Technical Writer
Code Generation	3	Function Writer, Bug Fixer, Code Optimizer
Content Writing	3	Blog Post Writer, Email Composer, Social Media Creator
Analysis	2	SWOT Analysis, Pros and Cons Evaluator
Creative	2	Story Starter, Character Creator
Business	2	Meeting Notes, Proposal Writer
Education	2	Quiz Generator, Concept Explainer

Features

• Create Custom Prompts - Add your own prompts with title, category, and content
• AI-Powered Enhancement - Click Enhance to optimize your prompt using GPT-5.2
• Template Variables - Use variables like {{word_count}}, {{topic}}, {{audience}}
• Team Sharing - Toggle sharing to make prompts available to other users
• One-Click Insert - Click any prompt to instantly insert it into your chat input

Template Variable Example

Write a {{word_count}} word blog post about {{topic}}.
Target audience: {{audience}}.
Tone: {{tone}}.

Convert audio and video recordings to text using OpenAI's Whisper API, with AI-powered tone rewriting.

Supported Formats

Format	Extension
MP3	.mp3
WAV	.wav
M4A	.m4a
FLAC	.flac
OGG	.ogg
WebM	.webm

Maximum file size: 25 MB

How to Transcribe

1. Go to the Transcribe tab
2. Click Upload Audio or drag and drop your file
3. Wait for processing (typically a few seconds)
4. View your transcription

Tone Rewriting

Transform your transcription with one-click tone options:

Tone	Description	Use Case
Professional	Business-appropriate language	Workplace communications
Casual	Friendly, conversational	Social content, emails
Formal	Academic, official language	Reports, documentation
Simple	Short sentences, easy words	Instructions, accessibility
Bullet Points	Key information in lists	Meeting notes, summaries
Summary	Condensed 2-3 paragraphs	Quick overviews

Compare responses from two AI models side-by-side to find the best fit for your needs.

Features

• Any Two Models - Compare across providers (e.g., GPT-5 vs Claude)
• Parallel Responses - Send the same prompt, get both responses simultaneously
• Response Timing - See which model responds faster
• Full History - Complete conversation preserved for both models
• Session Management - Save, browse, and delete comparison sessions

How to Compare

1. Go to the Compare tab
2. Select Model A (provider and model)
3. Select Model B (provider and model)
4. Type your prompt
5. Send to see both responses

Use Cases

• Evaluate which model writes better code
• Compare explanation quality
• Test creative writing styles
• Assess accuracy on factual questions
• Find the best value (quality vs. cost)

Give AI access to current web information for up-to-date answers.

How It Works

• Provider: DuckDuckGo (free, no API key required)
• Results: 1-20 results per search (default: 5)
• Integration: Search results are included in AI context

Auto-Trigger Keywords

The AI automatically searches the web when your message contains:

• "current", "latest", "recent", "today"
• Years (2024, 2025, etc.)
• "news", "weather", "stock price"
• "search for", "look up", "find information"

Configuration

1. Go to ChatProjects > Settings
2. Find the Web Search section
3. Enable/disable web search
4. Adjust number of results (1-20)

Install ChatProjects as a native app on any device for an app-like experience.

Supported Platforms

• iOS - Add to Home Screen from Safari
• Android - Install prompt in Chrome
• Windows - Install from Edge or Chrome
• macOS - Install from Chrome

Features

Feature	Benefit
Installable	Launch from home screen/dock
Offline Support	Cached assets work without internet
Extended Sessions	30-90 day auth cookies (vs. 2-14 days default)
Background Sync	Queued messages send when online

PWA Customization

Configure your PWA in ChatProjects > Settings > PWA:

Setting	Description
App Name	Full name shown in app launcher
Short Name	Name under home screen icon
Icon	Custom app icon (192x192 and 512x512)
Theme Color	Status bar and UI accent color
Background Color	Splash screen background

Complete customization for agencies and resellers. Remove all ChatProjects branding and replace with your own.

Customization Options

Element	What You Can Change
Plugin Name	Replace "ChatProjects" everywhere
Logo (Light Mode)	Your logo for light backgrounds
Logo (Dark Mode)	Your logo for dark backgrounds
Primary Color	Main brand color
Secondary Color	Supporting brand color
Accent Color	Highlights and interactive elements
Custom CSS	Additional style overrides

Where Branding Appears

Your custom branding is applied to:

• Admin interface headers
• Frontend chat interface
• Page titles and headings
• PWA manifest and icons
• Loading screens

CSS Variables

ChatProjects generates CSS variables you can use in custom CSS:

:root {
  --cp-primary: #your-primary-color;
  --cp-secondary: #your-secondary-color;
  --cp-accent: #your-accent-color;
  --cp-primary-rgb: r, g, b;  /* For opacity */
}

Create and edit images through natural language conversation.

Multi-Turn Editing (Gemini)

When Google Gemini API is configured, Image Studio provides a conversational editing experience:

1. Describe the image you want to create
2. View the generated result
3. Request changes: "make the sky more dramatic", "add a sunset glow", "remove the person on the left"
4. Continue refining through conversation
5. Download or save to Media Library

Aspect Ratios

Ratio	Dimensions	Use Case
1:1	Square	Social media, profiles
16:9	Wide	YouTube thumbnails, headers
9:16	Tall	Stories, mobile content
4:3	Standard	Presentations
3:4	Portrait	Portraits, posters
3:2	Photo	Photography standard

OpenAI Fallback

When Gemini is not configured, single-shot generation is available via OpenAI:

• DALL-E 3 - 1024x1024, 1792x1024, 1024x1792 (HD quality)
• GPT Image 1 - 1024x1024, 1024x1536, 1536x1024 (Fast generation)

Quality Options

Auto (recommended), Low (fastest), Medium, High, Standard, HD (highest quality)

Export your conversations in multiple formats for documentation, sharing, or backup.

Export Formats

Format	Extension	Best For
Markdown	.md	Documentation, GitHub, note apps
JSON	.json	Data processing, backups, migrations
HTML	.html	Standalone viewing, sharing, printing

Features

• Full or Partial Export - Export entire conversation or up to a specific message
• Metadata Included - Provider, model, date, message count
• Sources Preserved - Document references maintained
• Professional Styling - HTML export includes dark/light CSS themes

How to Export

1. Open the conversation you want to export
2. Click the Export button (download icon)
3. Select format (Markdown, JSON, or HTML)
4. Choose full or partial export
5. Download the file

Import web pages as searchable documents for your AI assistant. The imported content becomes part of your project's knowledge base, allowing the AI to reference and answer questions about the page content.

Overview

The URL Import feature allows you to:

• Import any public web page as a searchable document
• Optionally keep content synchronized (weekly refresh)
• Scan a website's navigation to discover and import multiple pages at once
• Manage imported URLs with manual refresh and delete options

Location: Open any project and click the URLs tab in the sidebar.

Importing a Single URL

1. Navigate to your project
2. Click the URLs tab in the left sidebar
3. Enter the full URL in the input field (e.g., https://example.com/about)
4. Optionally check Keep in sync (weekly refresh)
5. Click Import URL

Scanning for Multiple Pages

Instead of importing URLs one at a time, you can scan a website's main navigation to discover pages.

1. Enter a URL from the website you want to import (typically the homepage)
2. Click Scan for Pages
3. The system scans the page's main navigation menu
4. Review the discovered pages (up to 25 results)
5. Select which pages to import
6. Click Import Selected

Managing Imported URLs

Action	Description
Refresh	Manually re-import the page to get latest content
Toggle Sync	Enable or disable weekly automatic refresh
Delete	Remove the URL and its content from the project
Refresh All	Refresh all imported URLs at once

Limits

Limit	Value
Maximum URLs per project	50
Maximum scan results	25 pages
Sync frequency	Weekly (automatic)

Sync Status Meanings

Status	Meaning
success	Content fetched and updated successfully
unchanged	Content hasn't changed since last sync
failed	Could not fetch the URL (site may be down)
blocked	Website blocked the request

Tips for Best Results

Good URLs to import: Documentation pages, FAQ pages, blog posts, product descriptions, knowledge base articles.

URLs to avoid: Pages requiring login, dynamic dashboards, single-page applications (JavaScript-rendered content).

Add an AI-powered chatbot to any page on your WordPress site. Website visitors can chat with your AI assistant without needing to log in, while the chatbot draws answers from your project's uploaded documents.

Use Cases

• Customer support chatbot
• FAQ assistant
• Product information bot
• Documentation helper
• Lead capture tool

Quick Start

1. Create a Public Project: Go to ChatProjects Pro, create/edit a project, upload documents, set Sharing Mode to Public
2. Generate Widget Code: Go to Settings > Widget tab, select your project, copy the shortcode
3. Add to Your Site: Paste [chatprojects_widget project_id="123"] on any page

Shortcode Options

Attribute	Values	Default	Description
project_id	Number	Required	Your public project ID
position	bottom-right, bottom-left, top-right, top-left	bottom-right	Widget position
theme	light, dark, auto	auto	Color theme
width	CSS value	400px	Widget panel width
height	CSS value	500px	Widget panel height
collapsed	true, false	true	Start minimized
button_color	Hex color	Brand color	Button background
button_icon	chat, lightning, robot	chat	Button icon style
button_text	Text	empty	Optional button label
draggable	true, false	false	Allow repositioning

Example Shortcodes

Basic widget:

[chatprojects_widget project_id="123"]

Custom position and theme:

[chatprojects_widget project_id="123" position="bottom-left" theme="dark"]

Branded button with text:

[chatprojects_widget project_id="123" button_text="Chat with us" button_color="#FF5722"]

Setting Up a Public Project

1. Go to ChatProjects Pro > Projects
2. Edit the project you want to use
3. In Project Settings, find Sharing Mode
4. Select Public
5. Click Update

What "Public" means: Anonymous visitors can chat via the widget. They cannot access the main interface or see other projects. All conversations are logged for admin review.

Abuse Prevention

Configure protection in Settings > Widget > Abuse Prevention:

Setting	Default	Description
Rate Limiting	20 messages/hour	Max messages per visitor per time window
Max Message Length	2000 characters	Prevent extremely long messages
Blocked Words	empty	Comma-separated list of words to reject

Monitoring Conversations

View all widget conversations in Settings > Widget > Widget Logs. You can see visitor IPs, message counts, timestamps, and full conversation history.

Session Handling

• Each visitor gets a unique session stored in their browser
• Sessions persist across page reloads
• Visitors can continue conversations when they return
• Each project maintains separate sessions

Monitor API usage and track costs across all providers.

Metrics Tracked

Metric	Description
API Calls	Number of requests per model
Prompt Tokens	Input tokens (your messages)
Completion Tokens	Output tokens (AI responses)
Cost (USD)	Calculated cost per request
Duration (ms)	Response time

Dashboard Views

Personal Dashboard: Each user sees their own usage metrics and costs.

Platform Analytics (Admin): Administrators see aggregate metrics across all users: total usage by model, cost trends over time, top users by usage, model popularity rankings.

Date Ranges

Last 7 days, Last 30 days, Last 90 days, All time

Configurable Pricing

Set custom pricing per model to match your actual costs:

1. Go to ChatProjects > Settings > Pricing
2. Enter input token rate (per 1K tokens)
3. Enter output token rate (per 1K tokens)
4. Costs are calculated automatically

Feature	Free	Pro
AI Providers
OpenAI (GPT-5.2, GPT-5, etc.)	Yes	Yes
Anthropic (Claude 3.5)	Yes	Yes
Google (Gemini)	Yes	Yes
Chutes (DeepSeek)	Yes	Yes
OpenRouter (100+ models)	Yes	Yes
Projects
Number of Projects	5	Unlimited
Project Ownership	Shared	Per-User
Project Sharing Controls	-	Yes
Core Features
File Upload & Search (RAG)	Yes	Yes
Dark Mode	Yes	Yes
Encrypted API Keys (AES-256)	Yes	Yes
Real-time Streaming	Yes	Yes
Chat History	Yes	Yes
Pro-Exclusive Features
Prompt Library	-	Yes
Audio Transcription	-	Yes
Model Comparison	-	Yes
Web Search Integration	-	Yes
PWA Support	-	Yes
White-Label Branding	-	Yes
Image Studio	-	Yes
Chat Export	-	Yes
URL Import	-	Yes
Embeddable Chatbots	-	Yes
Usage Analytics	-	Yes
Support
WordPress.org Forum	Yes	Yes
Priority Email Support	-	Yes

API Key Encryption

All API keys are encrypted before storage using industry-standard encryption:

Feature	Implementation
Algorithm	AES-256-CBC
Key Derivation	WordPress AUTH_KEY
Library	OpenSSL
Storage	WordPress options table

Your API keys are:

• Never stored in plain text
• Decrypted only during API calls
• Never transmitted to ChatProjects servers
• Never displayed after initial entry

Data Storage

Data Type	Storage Location	Encryption
API Keys	wp_options	AES-256-CBC
Chat History	wp_chatprojects_chats	None (local)
Messages	wp_chatprojects_messages	None (local)
Projects	wp_posts (cp_project)	None (local)
Uploaded Files	OpenAI servers	Provider-managed

Data Transmission

ChatProjects connects directly to AI providers - there is no middleman server:

• Your WordPress site > AI Provider (direct connection)
• Only the provider you select receives your data
• No data passes through ChatProjects servers

WordPress Security Standards

Protection	Implementation
Nonce Verification	All AJAX requests include wp_nonce
Capability Checks	Permission validation for all actions
Input Sanitization	sanitize_text_field(), wp_kses_post(), absint()
Output Escaping	esc_html(), esc_attr(), esc_url()
SQL Protection	All queries use $wpdb->prepare()
File Validation	MIME type and size verification

ChatProjects - Backend Security Documentation

WordPress.org Verification ✓

• Meets WordPress coding standards and security guidelines
• Has passed manual code review by the WordPress plugin review team
• Undergoes regular security audits as part of directory requirements
• Adheres to WordPress best practices for plugin development

Note: The Pro version with SaaS features is a commercial extension and is not listed in the WordPress.org directory.

Data Retention & Deletion Security

Comprehensive Data Management: ChatProjects implements a robust 9-category data retention system that gives both administrators and users complete control over data lifecycle.

Covered Data Categories:

• Chat conversations (messages, metadata, OpenAI stored responses)
• Image Studio sessions and generated images
• Voice interaction sessions
• Audio transcriptions
• Model comparison sessions
• Usage analytics (tokens, costs)
• Anonymous widget chats
• Audit logs (SaaS mode)
• Billing transaction history (SaaS mode)

Retention Policies:

Admin Control (Non-SaaS & SaaS):

• Global retention policies configurable per category
• Period options: 7 days, 30 days, 90 days, 180 days, 1 year, or never
• Automated daily cleanup via WordPress cron
• Batch processing (500 records per run) to prevent server timeouts
• Orphaned file scanner to find and remove files with no database reference

User Control (SaaS Mode):

• Per-user retention preferences for their own data
• User policies can only be stricter than global admin policies (never weaker)
• Manual "Delete All" for any category with confirmation
• Rate-limited to prevent abuse (1 action per category per 5 minutes)
• Real-time data inventory showing item counts per category

OpenAI Response Cleanup: When chats are deleted (manually or via retention policy), associated OpenAI stored responses are also cleaned up:

• Before local deletion: Extract all response_id values from message metadata
• Queue for async deletion: Add to retry queue table
• API cleanup: Daily cron calls DELETE /v1/responses/{id} on OpenAI's API
• Retry logic: Failed deletions retried up to 3 times
• Admin visibility: Failed queue items surfaced in admin panel with manual retry option

Edge Case Protection:

Scenario	How It's Protected
Active subscriber billing data	Automatically excluded from auto-purge via database JOIN check
Shared chat deletion	Share records deleted first; recipients lose access (owner controls retention)
OpenAI API failures	Local data deleted immediately; external cleanup queued with retry logic
Large datasets	Batch processing prevents server timeouts and memory issues
Concurrent cron runs	Transient lock prevents overlapping cleanup operations
Orphaned files	Scanner cross-references filesystem against database records

File Storage Security

Upload Process:

• User uploads file via browser → temporary PHP file created (/tmp/phpXXXXXX)
• File validated (type, MIME, size, permissions)
• Spreadsheets automatically converted to UTF-8 .txt for vector store compatibility
• File streamed to OpenAI via multipart/form-data POST
• Temporary files immediately deleted with @unlink() after successful upload
• Only metadata stored in WordPress (filename, file_id, size, upload date)

Benefits:

• Reduced attack surface: No files to exploit on your server
• Storage savings: Large documents don't consume WordPress hosting space
• GDPR compliance: File deletion removes from OpenAI; no local copies to manage
• Automatic cleanup: No configuration or cron jobs needed for file management

File Access Control - Three-layer security system:

• Project-level permissions: Admins can access all projects, project owner has full access, shared users verified against share records, team members verified via team membership
• AJAX nonce validation: CSRF protection on all upload/delete endpoints, user must be logged in, nonce must match current session
• File validation: Extension check (whitelist of allowed types), MIME type check (binary content validation via finfo_file()), size limit (50MB max, configurable), filename sanitization (path traversal and dangerous character removal)

Allowed File Types:

• Documents: pdf, doc, docx, txt, md
• Spreadsheets: xls, xlsx, ods, csv (auto-converted to .txt)
• Data: json, xml, html, css
• Code: js, py, php, java, cpp

General Plugin & WordPress Security

1. Authentication & Authorization

Login Security:

• Email verification required before first login
• Password requirements: Minimum 8 characters
• Secure password handling: WordPress wp_check_password() for hashing verification
• Account status checks: Suspended/banned accounts blocked at login

Account Lockout System:

• 5 failed login attempts → 15-minute IP-based lockout
• Transient-based tracking with 1-hour sliding window
• Automatic daily cleanup of old lockout records
• Audit log entry created for each lockout event

Session Management:

• Re-authentication required for sensitive admin actions after 30 minutes
• Session validation on all authenticated AJAX requests
• Last auth timestamp tracked per user

2. Rate Limiting

Plan-Based API Limits:

Plan	Per Minute	Per Hour	Per Day	Concurrent
Free	10	100	500	2
Lite	30	500	2,000	5
Starter	60	1,000	5,000	10
Pro	120	3,000	15,000	20
Power	200	6,000	30,000	30
Enterprise	500	15,000	100,000	50

Implementation:

• Persistent database table (chatprojects_rate_limits) with atomic increments
• INSERT ... ON DUPLICATE KEY UPDATE for race condition prevention
• Rate limit headers in AJAX responses (X-RateLimit-Limit-*, X-RateLimit-Remaining-*)
• Team accounts get 1.5x multiplier on limits

Authentication Flow Rate Limits:

Action	Limit	Window
Registration	5 per IP	1 hour
Resend verification	3 per IP	1 hour
Forgot password	5 per IP	1 hour
Reset password	5 per IP	1 hour

3. Data Encryption

API Key Encryption:

• Cipher: AES-256-CBC (industry standard)
• Key derivation: PBKDF2 with 100,000 iterations
• IV: Random pseudo-bytes per encryption operation
• Format: Base64-encoded [IV + encrypted_data]

Key Sources (priority order):

• CHATPROJECTS_ENCRYPTION_KEY constant (if defined in wp-config.php)
• WordPress AUTH_KEY constant (preferred default)
• Fallback to SECURE_AUTH_KEY or ABSPATH + DB_NAME
• Weak key detection alerts if fallback is used

Storage:

• User API keys: Encrypted in chatprojects_user_api_keys table
• Platform API keys: Encrypted in wp_options table
• Backwards compatibility: Auto-detects and migrates unencrypted keys

4. Input Validation & Sanitization

Contextual Sanitization:

// Email addresses
sanitize_email($input);

// Text fields
sanitize_text_field($input);

// URLs
esc_url_raw($input);

// HTML content
wp_kses_post($input);

// Textareas
sanitize_textarea_field($input);

// Arrays
array_map('sanitize_text_field', $input);

File Upload Validation:

• Extension whitelist check
• MIME type verification via finfo_file()
• File size enforcement
• Filename sanitization (removes path info, dangerous characters)
• Upload verification via is_uploaded_file()

5. CSRF Protection

WordPress Nonce Verification: All AJAX handlers verify nonces before processing:

check_ajax_referer('chatpr_register_nonce', 'nonce');
check_ajax_referer('chatpr_login_nonce', 'nonce');
check_ajax_referer('chatpr_api_keys_nonce', 'nonce');
// ... applied to 40+ AJAX endpoints

Additional CSRF Token Layer:

• Custom CSRF token generation (32-character random)
• Tokens stored as transients with 1-hour expiry
• Separate validation layer for admin actions
• Destructive admin actions require confirm_nonce (separate from action nonce)

Protected destructive actions: Delete user/team, impersonate user, suspend account, send announcements, purge data

6. Security Headers

Sent on all frontend requests:

X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Strict-Transport-Security: max-age=31536000; includeSubDomains

7. Audit Logging

All admin actions logged with: Admin user ID, action type, target (user/team/subscription), metadata (details of what changed), IP address, timestamp.

Logged Action Categories:

• User management (credits, plans, suspensions, deletions)
• Team management (creation, members, permissions)
• Subscription changes (cancellations, reactivations)
• Security events (lockouts, announcements, blocked requests)

Features:

• 365-day retention (configurable)
• CSV export for external analysis
• Filter by admin, action, target, date range
• Pagination for large datasets

8. SQL Injection Prevention

All database queries use prepared statements:

// Standard pattern throughout the plugin
$wpdb->get_var($wpdb->prepare(
    "SELECT hit_count FROM {$table} WHERE limit_key = %s AND expires_at > NOW()",
    $key
));

// Placeholders:
// %d for integers
// %s for strings
// %f for floats

No raw SQL or string concatenation in database queries throughout the entire codebase.

9. XSS Prevention

Output escaping on all user-generated content:

// Text content
echo esc_html($variable);

// HTML attributes
echo esc_attr($variable);

// URLs
echo esc_url($variable);

// HTML content (with allowed tags)
echo wp_kses_post($variable);

Applied in: All template files, email templates, admin views, AJAX response data, JavaScript localized data.

10. Suspicious Activity Detection

Automated monitoring for:

• Rapid requests: Flags users making >50 requests in short time
• IP changes: Tracks and alerts on IP address changes per user
• API errors: Flags users with >20 API errors per hour
• Custom action hook: do_action('chatprojects_suspicious_activity', $user_id, $type, $data)

Actions taken: User marked for review, admin notification, automatic rate limiting, audit log entry.

11. Client IP Detection

Proxy-aware IP detection supporting: Cloudflare (HTTP_CF_CONNECTING_IP), standard proxies (HTTP_X_FORWARDED_FOR), Nginx (HTTP_X_REAL_IP), direct connection (REMOTE_ADDR). Handles comma-separated IPs, validates format, fallback to 0.0.0.0 if invalid.

12. Email Security

Email Verification Flow:

• Token generation: 32 random bytes
• Token expiry: 24 hours
• Timing attack protection: Uses hash_equals() for token comparison
• Verification URL: Includes action, token, user ID parameters
• Branded HTML templates with inline styles for email client compatibility

Email Failure Logging: All email failures logged to PHP error log, includes error message and full email data, WordPress wp_mail_failed hook integration.

Security Architecture Summary

Layer	Feature	Implementation
Infrastructure	WordPress.org approved (free version)	Meets all directory security requirements
Data Retention	Automated cleanup	9 categories, configurable periods, batch processing
File Storage	No local storage	Files uploaded to OpenAI only, metadata-only locally
Authentication	Multi-factor protection	Email verification, lockouts, session management
Rate Limiting	Multi-tier throttling	Per-plan API limits, auth flow limits, concurrent tracking
Encryption	AES-256-CBC	API keys, sensitive data, PBKDF2 key derivation
CSRF Protection	Dual-layer	WordPress nonces + custom tokens
Input Validation	Contextual sanitization	File type, MIME, size, content sanitization
SQL Injection	Prepared statements	100% parameterized queries, no raw SQL
XSS Prevention	Output escaping	Context-aware escaping on all user content
Audit Logging	Complete trail	All admin actions, IP tracking, 365-day retention
Monitoring	Suspicious activity	Request tracking, IP changes, error detection
Security Headers	Industry standard	Nosniff, SAMEORIGIN, XSS-Protection, HSTS

Compliance & Best Practices

GDPR Compliance:

• ✅ Data deletion on request (manual + automated)
• ✅ Export user data functionality
• ✅ Clear data transparency information
• ✅ External service cleanup (OpenAI responses)
• ✅ Audit trail of all data operations
• ✅ User control over retention policies

WordPress Security Best Practices:

• ✅ Nonce verification on all forms
• ✅ Capability checks for admin functions
• ✅ Escaped output for all user data
• ✅ Sanitized input on all endpoints
• ✅ Prepared statements for all database queries
• ✅ Secure password storage (WordPress hashing)
• ✅ File upload restrictions
• ✅ Rate limiting on public endpoints

OWASP Top 10 Protection:

• ✅ A01 Broken Access Control: Role-based permissions, capability checks
• ✅ A02 Cryptographic Failures: AES-256-CBC encryption, secure key derivation
• ✅ A03 Injection: Prepared statements, input sanitization
• ✅ A04 Insecure Design: Security-first architecture, defense in depth
• ✅ A05 Security Misconfiguration: Secure defaults, security headers
• ✅ A07 Identification/Authentication: Lockouts, session management, MFA-ready
• ✅ A08 Software/Data Integrity: Nonce verification, audit logging
• ✅ A09 Security Logging Failures: Comprehensive audit log, email failure tracking
• ✅ A10 Server-Side Request Forgery: Input validation, URL sanitization

Key Security Files

File	Purpose	Key Features
includes/class-security.php	Core security utilities	Encryption, file validation, input sanitization
includes/saas/class-security-hardening.php	SaaS security layer	Lockouts, headers, suspicious activity detection
includes/saas/class-rate-limiter.php	API rate limiting	Plan-based limits, concurrent tracking
includes/class-data-retention.php	Data lifecycle management	Retention policies, automated cleanup
includes/class-data-retention-queue.php	External cleanup queue	OpenAI API deletion with retry logic
includes/saas/class-audit-log.php	Action logging	All admin operations, IP tracking
includes/saas/class-registration.php	Authentication flow	Email verification, rate limiting
includes/class-access.php	Permission management	Project access, team membership checks

Frequently Asked Questions

Common Issues

ChatProjects connects to external AI services. Your data is transmitted according to each provider's privacy policy.

Provider	Used For	Privacy Policy
OpenAI	Chat, Vector Stores, File Search, Images, Transcription	openai.com/privacy
Anthropic	Chat with Claude models	anthropic.com/privacy
Google Gemini	Chat with Gemini models, Image Studio	policies.google.com/privacy
Chutes	Chat with DeepSeek models	chutes.ai/privacy
OpenRouter	Chat with 100+ models	openrouter.ai/privacy
DuckDuckGo	Web Search PRO	duckduckgo.com/privacy

Documentation

Resource	Location
This Guide	chatprojects.com/docs
In-Plugin Help	Tooltips throughout the interface

Support Channels

Version	Channel	Response Time
Free	WordPress.org Forum	Community-based
Pro	Priority Email: support@chatprojects.com	24-48 hours

Additional Links

Resource	URL
Official Website	chatprojects.com
Pro Features	chatprojects.com/pro
Free Download	chatprojects.com/free
Contact	chatprojects.com/contact

Version 1.0.0

Initial Release - December 2025

Core Features

• Multi-provider AI chat (OpenAI, Anthropic, Gemini, Chutes, OpenRouter)
• Project management with OpenAI Vector Stores
• File upload and AI-powered document search (RAG)
• Modern chat interface with real-time streaming
• Dark/Light theme support
• AES-256 API key encryption
• Local message storage
• Shortcode embedding

Pro Features

• Prompt Library with 100+ professional prompts
• Audio transcription with tone rewriting
• Side-by-side model comparison
• DuckDuckGo web search integration
• Progressive Web App (PWA) support
• White-label branding customization
• Image Studio (Gemini multi-turn + OpenAI)
• Chat export (Markdown, JSON, HTML)
• Usage analytics and cost tracking

Supported File Types

PDF, DOC, DOCX, TXT, MD, PPTX, CSV, JSON, XML, HTML, CSS, JS, PY, PHP, Java, C++, XLS, XLSX, ODS