AI Chat Plugin for WordPress

A production-ready WordPress plugin that adds a fully customizable chatbot widget to any site, powered by your own external backend API.

Features

Requirements

• WordPress 6.0 or later
• PHP 8.0 or later

Installation

1. Download or clone this repository.
2. Upload the ai-chat-plugin folder to /wp-content/plugins/.
3. Activate via Plugins → Installed Plugins.
4. Go to AI Chat in the WordPress admin sidebar.
5. Set your Backend Base URL and save.

Backend API Contract

The plugin expects the following endpoints on your backend:

Chat — POST {BACKEND_URL}/chat

Request body:

{
  "sessionId": "uuid-v4-string",
  "message":   "User message text",
  "channel":   "chat"
}

For later messages in the same session, send the historyAccessToken returned by the previous response in the X-Chat-History-Token request header. The first message has no history token. The widget handles this in both proxy and direct mode. It keeps the token in the browser's session storage; if that token is no longer available, it starts a new backend session instead of reusing an inaccessible session ID.

Response body:

{
  "sessionId": "uuid-v4-string",
  "text":      "Assistant reply",
  "channel":   "chat",
  "historyAccessToken": "opaque-token"
}

The backend may wrap this response in an array. The plugin accepts either form.

Health check — GET {BACKEND_URL}/chat/health

Typical response:

{
  "status":    "UP",
  "timestamp": "2026-05-12T00:00:00.000Z",
  "services":  { "api": "UP", "redis": "UP" }
}

Admin Settings

Navigate to AI Chat → Settings and configure each tab:

Connection Modes

Proxy (recommended, default)

Browser → POST /wp-json/ai-chat/v1/chat → WordPress → POST {backend}/chat → Backend

• Backend URL is never sent to the browser.
• The widget fetches a WordPress nonce (ai_chat_proxy) before each message so cached pages do not send an expired nonce. This public nonce is request hygiene, not visitor authorization or the primary abuse control.
• Rate-limited per visitor IP using WordPress transients.

Direct

Browser → POST {BACKEND_URL}/chat

• Requires CORS to be enabled on the backend, including the X-Chat-History-Token request header for follow-up messages.
• Backend URL is exposed to the browser — only use if the backend is intentionally public.

Shortcode

Place the chatbot trigger anywhere in page content:

[ai_chat_widget]

This renders a trigger button that opens the floating chat panel when clicked.

Plugin Structure

ai-chat-plugin/
├── ai-chat-plugin.php           # Entry point — constants, requires, activation hooks
├── includes/
│   ├── class-plugin.php         # Singleton bootstrap
│   ├── class-admin-settings.php # Tabbed admin settings page
│   ├── class-assets.php         # Script/style enqueuer + JS config builder
│   ├── class-frontend.php       # wp_footer widget + shortcode
│   ├── class-rest-controller.php# Proxy REST endpoint + rate limiting
│   ├── class-api-client.php     # wp_remote_post HTTP client
│   ├── class-session-manager.php# UUID generation & validation
│   └── class-sanitizer.php      # Input sanitization + defaults
├── assets/
│   ├── css/
│   │   ├── chat-widget.css      # Widget styles (CSS variables, responsive, RTL)
│   │   └── admin.css            # Admin page styles
│   └── js/
│       ├── chat-widget.js       # Vanilla JS widget (session, API, UI, a11y)
│       └── admin.js             # Color pickers + test-connection AJAX
├── templates/
│   └── chat-widget.php          # wp_footer mount point
├── languages/                   # i18n .pot files go here
├── uninstall.php                # Deletes all plugin data on removal
├── readme.txt                   # WordPress.org readme
└── README.md                    # This file

Developer Hooks

Filters

Example

// Add a custom header to every backend request.
add_filter( 'ai_chat_api_request_args', function ( array $args ): array {
    $args['headers']['X-My-Header'] = 'value';
    return $args;
} );

// Append context to every message before forwarding.
add_filter( 'ai_chat_proxy_payload', function ( array $payload ): array {
    $payload['siteId'] = get_current_blog_id();
    return $payload;
} );

Security

• All admin inputs are sanitized via AI_Chat_Sanitizer::sanitize_settings().
• All HTML output uses esc_html(), esc_attr(), esc_url(), and wp_kses().
• SVG input is parsed with DOMDocument and rebuilt from an allowlist of safe elements/attributes — scripts and event handlers are stripped.
• The proxy REST endpoint checks a short-lived public nonce (ai_chat_proxy) and applies a per-peer-IP rate limit. The nonce does not authorize access.
• The backend URL is never sent to the browser in proxy mode.
• The JS widget escapes all text before inserting it into the DOM (textContent / custom escHtml()).

Changelog

1.0.0

• Initial release.

License

GPL-2.0-or-later — see LICENSE.