=== BitBloom Chatbot for Chatkit ===
Contributors: ishchai
Tags: openai, chatkit, chat, embed, ai
Requires at least: 6.2
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.2.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Embeds the ChatKit widget from OpenAI Agent Builder into WordPress pages. Independent integration by BitBloom; not affiliated with OpenAI.

== Description ==

**BitBloom Chatbot for Chatkit** lets you embed a published Agent Builder workflow into WordPress using OpenAI’s ChatKit UI.
Features a floating launcher, optional shortcode, theme controls (light/dark, accent color, radius, density, font), and server-side session creation with REST nonces (no API key in the browser).
- Optional avatar support: display a custom image in the chat header and/or the floating launcher button.


**Highlights**
- Floating ChatKit launcher or inline embed via shortcode.
- One-time setup: paste your *Workflow ID* and *Domain Public Key*.
- Theme controls: color scheme, accent, radius, density, font.
- Secure: session created on the server; REST calls nonce-protected.
- Rate limiting: configurable per-IP hourly limit for session requests (default 20/hour).
- Privacy-friendly: user ID is a salted hash (no IP stored or sent by the plugin).

**What you need from OpenAI**
1. A **published** Agent Builder workflow (copy its Workflow ID).
2. Your **Domain allowlist** and **Domain Public Key** (Security → Domain allowlist).
3. Active billing/credits in your OpenAI account.

The plugin also supports an optional **avatar image**, allowing you to personalize the chat experience by displaying a custom image inside the chat header and/or on the floating launcher button.

== Installation ==
For a full video walkthrough of the installation and setup process:
https://youtu.be/Kd0WxODDdYc

1. Download the ZIP and upload it via **Plugins → Add New → Upload Plugin**, 
   or install it directly from the WordPress Plugin Directory.

2. Activate **BitBloom Chatbot for Chatkit**.

3. Add your OpenAI API key to wp-config.php:

   define('OPENAI_API_KEY', 'sk-proj-xxxxxxxxxxxxxxxx');

   This key must NOT be placed in the plugin settings screen for security reasons.

4. Go to **BitBloom Chatbot for Chatkit** in the WordPress admin menu and configure:

   - **Workflow ID**  
     (Found in OpenAI → Agent Builder → Publish → Get Code)

   - **Domain Public Key**  
     (Found in OpenAI → Agent Builder → Security → Domain allowlist)

5. (Optional) Customize theme settings:
   - Color scheme (light/dark)
   - Accent color
   - Corner radius
   - Density
   - Font

6. (Optional) Configure avatar settings:
  - Upload a custom avatar image
  - Show the avatar inside the chat header
  - Show the avatar on the floating launcher button
  - Use an image-only launcher (no text label)

7. (Optional) Enable **Auto-inject** to display the floating chat launcher on all pages.

8. (Optional) To embed the chat inline inside a single page or post, use the shortcode:
   
   [bitbloom_chatbot_for_chatkit]

9. (Optional) Adjust **Rate limit** (per IP / hour). Default is 20/hour.


== Usage ==

**Floating Launcher (auto)**
- Once configured, the floating button appears on the front-end. Clicking it opens ChatKit bound to your published workflow.
If enabled, a custom avatar image can appear inside the chat header and/or on the launcher button.

**Shortcode (inline chat)**
Add to any post/page:
[bitbloom_chatbot_for_chatkit]

**Security**
- The plugin uses `wp_rest` nonces for the session endpoint and never exposes your OpenAI API key in the browser.

== Frequently Asked Questions ==

= The chat opens but doesn’t reply. What should I check? =
The most common causes are:
- The workflow is not **published** in OpenAI’s Agent Builder.
- The site domain is missing from the **Domain allowlist**.
- Incorrect or missing **Domain Public Key**.
- No available **OpenAI credits** in your account.

= Where do I put my OpenAI API key? =
Add it to your wp-config.php file:
define('OPENAI_API_KEY', 'sk-proj-xxxxxxxx');
Do not place the API key in the browser or inside the plugin settings.

= Does the plugin store chat history or user messages? =
No. The plugin does not store any conversation data on your server.  
All communication is handled directly through the session created when the chat loads.

= Does the plugin send my API key to the browser? =
No. The API key remains server-side.  
All browser requests use a WordPress REST route protected by a nonce.

= Can I embed the chat inside a page instead of using the floating launcher? =
Yes. Use the shortcode:
[bitbloom_chatbot_for_chatkit]

= Can I customize the look of the chat? =
Yes. You can change the color scheme (light/dark), accent color, radius, density, and font.

= Can I add a custom avatar to the chat? =
Yes. You can upload an image in the plugin settings and choose whether it appears in the chat header, the floating launcher button, or both.

= Is there a usage/rate limit in the plugin? =
Yes. By default, the plugin limits session requests to 20 per hour per IP.
You can change this in the plugin settings (Rate limit per IP / hour) to any value between 1 and 99999.

= The chat window shows an error when loading. What causes this? =
Usually one of the following:
- Missing or invalid **Workflow ID**
- Incorrect **Domain Public Key**
- The WordPress site is blocking REST requests
- A security plugin is blocking nonces or AJAX

= Does the plugin support caching plugins? =
Yes. The launcher and UI are safe to cache, but the REST endpoints should remain uncached.  
If you use aggressive caching (e.g., LiteSpeed, Cloudflare APO), exclude:
- /wp-json/bitbloom-chatbot-for-chatkit/*

= Can I use multiple workflows on the same site? =
Yes. The shortcode supports multiple instances when placed on different pages.

= Does the plugin work on multisite? =
Yes, but each subsite must configure its own Workflow ID and Domain Public Key.

= Is this plugin GDPR-compliant? =
The plugin does not store personal data, but the site owner is responsible for ensuring:
- A proper privacy notice
- Compliance with data handling when using OpenAI services

== Screenshots ==
1. **Admin settings screen** – Configure Workflow ID, Domain Public Key, and chat theme.
2. **Agent embedded on a live site** – The ChatKit widget opened on a WordPress page.

== Privacy ==
- The plugin computes an anonymized **user identifier** using a salt + user agent hash and **does not send IP**.
- The plugin does **not** collect analytics or telemetry.
- Data exchanged with OpenAI is limited to what’s required to run your configured workflow (message text, workflow ID, domain public key, and the anonymized user hash).
- On uninstall, the option `bitbloom-chatbot-for-chatkit_options` is deleted.

== Changelog ==
= 1.2.2 =
* Added optional avatar support:
  - Display avatar in the chat header
  - Display avatar in the floating launcher
  - Supports image-only launcher (no label)
* Improved launcher button rendering logic and defaults.
= 1.2.1 =
* Added an admin setting to configure the per-IP hourly rate limit for session requests (default: 20/hour).
= 1.2.0 =
* Initial public release under the name “BitBloom ChatKit Embed”.

== Upgrade Notice ==
= 1.2.2 =
Improves the launcher button logic (supports image-only launcher and smarter defaults).
= 1.2.1 =
Adds a configurable rate limit setting (default 20/hour).
= 1.2.0 =
First stable release.

== External services ==

This plugin loads the ChatKit web component from OpenAI’s CDN and creates short-lived client sessions with OpenAI in order to render the chat UI.

• Service: OpenAI ChatKit (web component & sessions API)
• What for: Render the chat widget and let the agent run your workflow.
• Endpoints:
  - CDN script: https://cdn.platform.openai.com/deployments/chatkit/chatkit.js
  - Sessions API: https://api.openai.com/v1/chatkit/sessions
• What is sent and when:
  - On page load, the browser downloads the ChatKit web component from the CDN.
  - When the user opens the chat, WordPress calls the Sessions API server-to-server to mint a short-lived client_secret. The request includes:
    * Your configured workflow ID
    * A non-identifying, hashed “user” string derived from the site salt and the user agent (no PII)
• Privacy & Terms:
  - OpenAI Terms: https://openai.com/policies/terms-of-use
  - OpenAI Privacy Policy: https://openai.com/policies/privacy-policy