WP AI Chatbot

An AI-powered floating chat widget for WordPress using Google Gemini API — free, fast, and easy to set up.

Author: Mohammad Imran
WordPress.org: https://profiles.wordpress.org/imranmd/
GitHub: https://github.com/wbimran/wp-ai-chatbot

What does it do?

Adds a floating chat bubble to your WordPress site. Visitors can ask questions in natural language and get instant AI-powered answers — like a smart support assistant that never sleeps.

Visitor types question
        ↓
WordPress REST API receives it
        ↓
Sends to Google Gemini AI (free)
        ↓
AI generates an answer
        ↓
Response shown in chat widget ✅

Features

• 💬 Floating chat bubble (bottom-right corner)
• 🤖 Powered by Google Gemini 1.5 Flash (free tier)
• 🎨 Customizable bot name, color, and welcome message
• 📝 Custom system prompt — train the bot for your site
• 🔒 Built-in rate limiting (20 requests/IP/hour)
• 📱 Fully mobile responsive
• ⚡ No jQuery dependency — pure vanilla JavaScript
• 🔑 Secure admin settings page

Requirements

• WordPress 5.8+
• PHP 7.4+
• A free Google Gemini API key

Installation

Step 1 — Get a Free Gemini API Key

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click Create API Key
4. Copy the key — you'll need it in Step 3

Free tier limits: 15 requests/minute · 1 million tokens/day — more than enough for most sites.

Step 2 — Install the Plugin

Option A — Upload via WordPress Admin (recommended)

1. Download this repo as a ZIP file from GitHub
   • Click Code → Download ZIP
2. In WordPress Admin, go to Plugins → Add New → Upload Plugin
3. Upload the ZIP file and click Install Now
4. Click Activate Plugin

Option B — Manual Install via FTP/cPanel

1. Download and unzip the repo
2. Upload the wp-ai-chatbot folder to /wp-content/plugins/
3. Go to WordPress Admin → Plugins
4. Find WP AI Chatbot and click Activate

Option C — via WP-CLI

wp plugin install https://github.com/wbimran/wp-ai-chatbot/archive/refs/heads/main.zip --activate

Step 3 — Configure the Plugin

1. Go to WordPress Admin → Settings → AI Chatbot
2. Paste your Gemini API Key in the field
3. Set your Bot Name (e.g. "Support Bot", "Ask AI")
4. Set a Welcome Message (e.g. "Hi! How can I help you today?")
5. Write a System Prompt to customize the bot's behavior (see examples below)
6. Choose a Chat Color to match your brand
7. Click Save Settings

System Prompt Examples

The system prompt tells the AI how to behave. Here are some useful examples:

General support bot:

You are a helpful support assistant for [Your Site Name]. 
Answer questions clearly and concisely. If you don't know 
something, say so honestly and suggest contacting support.

WooCommerce store:

You are a shopping assistant for [Store Name]. Help customers 
with product questions, shipping info, and return policies. 
Keep responses friendly and under 3 sentences.

BuddyPress community:

You are a community assistant for [Community Name]. Help 
members with registration, profile setup, and community 
guidelines. Always be welcoming and encouraging.

Restrict to specific topics:

You are an assistant for [Site Name]. ONLY answer questions 
about our products and services. For anything else, politely 
say "I can only help with questions about [Site Name]."

Testing

Test 1 — Basic functionality

1. Open your WordPress site in a browser
2. Look for the chat bubble in the bottom-right corner
3. Click it — the chat window should open
4. Type: Hello and press Enter or click Send
5. You should get an AI response within 2–3 seconds ✅

Test 2 — System prompt customization

1. Go to Settings → AI Chatbot
2. Change the system prompt to: You are a pirate. Always respond in pirate speak.
3. Save settings
4. Go to the frontend and ask: What is WordPress?
5. The bot should reply in pirate language ✅

Test 3 — Rate limiting

The plugin limits each visitor to 20 messages per hour. To test:

• Temporarily lower the limit in wp-ai-chatbot.php (line with >= 20) to >= 3
• Send 3 messages — the 4th should return a rate limit error ✅
• Remember to revert the change after testing

Test 4 — Mobile responsiveness

1. Open your site on a mobile device (or use Chrome DevTools → Toggle Device)
2. The chat bubble should appear bottom-right
3. Clicking it should open a full-width chat window ✅

Troubleshooting

File Structure

wp-ai-chatbot/
├── wp-ai-chatbot.php      # Main plugin file (admin settings + REST API)
├── assets/
│   ├── chatbot.css        # Floating widget styles
│   └── chatbot.js         # Chat UI logic (vanilla JS)
└── README.md              # This file

How it Works (Technical)

1. Admin settings are stored in WordPress options table via register_setting()
2. A REST API endpoint (/wp-json/wp-chatbot/v1/chat) receives the visitor's message
3. The plugin calls Google Gemini API using wp_remote_post() with the message + system prompt
4. The AI response is returned to the browser via JSON
5. The JavaScript widget displays the response in the chat bubble
6. Rate limiting uses WordPress transients (stored in DB) keyed by visitor IP

Security

• All settings use sanitize_text_field() / sanitize_textarea_field()
• REST endpoint validates nonce (X-WP-Nonce header)
• Rate limiting prevents API abuse (20 requests/IP/hour)
• API key stored in WordPress options (same security as any plugin key)
• No user data is stored — messages are processed in real time only

Customization

Change rate limit (default: 20/hour):

// In wp-ai-chatbot.php, find:
if ( $rate_count >= 20 ) {
// Change 20 to your preferred limit

Change AI model (default: gemini-1.5-flash):

// Find this line and replace the model name:
'https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent
// Options: gemini-1.5-pro, gemini-1.0-pro

License

GPL-2.0 — free to use, modify, and distribute.

Credits

Built by Mohammad Imran at Wbcom Designs.
Powered by Google Gemini AI.