=== TWX-Chat – AI Chatbot with Talking Avatars ===
Contributors: twxlabs
Tags: chatbot, 3d animated, talking avatar, knowledge base, site crawler
Requires at least: 5.8
Tested up to: 6.8.2
Stable tag: 1.12.2
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI-powered chatbot for WordPress. Let your website speak for itself with 3D Animated Talking Avatars. No usage limits.

== Description ==

TWX-Chat is a powerful and flexible AI chatbot plugin for WordPress, designed to enhance user engagement and provide intelligent, automated support. Powered by OpenAI, this plugin allows you to add a customizable chatbot to your website that can answer questions, provide information, and guide users.

**Key Features:**

*   **AI-Powered Chatbot:** Utilizes OpenAI's GPT models to provide natural and intelligent conversations.
*   **3D Talking Avatars:** Select from available 3D Avatars to add extra engagement for all of your visitors. No time limits!
*   **Knowledge Base Integration:** Automatically builds a searchable knowledge base from your website's pages, posts, or even a sitemap (paid plan). The chatbot uses this "context" to provide relevant and accurate answers based on your content.
*   **Site Crawler:** Includes a built-in site crawler to automatically keep your knowledge base up-to-date with the latest content from your site.
*   **Customizable:** Customize the chatbot's appearance, greeting messages, common questions, flashcards and more. Supports both embedded and floating chat styles.
*   **Streaming Support:** Provides fast, streaming responses for a smoother user experience.
*   **Shortcode Builder:** Easily create multiple chatbots with different styles and knowledge, and simply add the id to any page or post using a simple shortcode. 

Whether you want to provide 24/7 customer support, create an interactive FAQ, or simply offer a more engaging way for users to explore your site, TWX-Chat provides the tools you need.

== Installation ==

1.  Activate the plugin through the 'Plugins' menu in WordPress.
2.  Follow the setup instuctions [on our website](https://twxchat.twxlabs.au/docs/installation-setup/).

[All questions and feedback welcome!](https://twxchat.twxlabs.au/contact-us/)

== Frequently Asked Questions ==

= Do I need an OpenAI API key? =

Yes, this plugin requires an OpenAI API key to function. You can get a key by signing up on the [OpenAI website](https://openai.com/).

= Do I need any other Keys? =

Yes. If you want to use the 3D Avatar chatbots, you will need an AWS Cognito Pool Identity Key in order to allow the chatbot to speak. Instructions for this are on [our website](https://twxchat.twxlabs.au/docs/installation-setup/#twx-chat-getting-aws-cognito-id).
Also if you want to crawl your Google Drive folder (paid plan option), this will need to be entered in the General settings.

= How does the Knowledge Base work? =

The plugin's Site Crawler can read your posts, pages, images, Google Drive folder, or even a custom Sitemap (paid plans only), to create a Knowledge Base. When a user asks a question, the chatbot searches this knowledge base to find the most relevant information and uses it to form an answer. This ensures the responses are based on your site's content.

= Can I fine-tune my knowledge base? =

Yes absolutely! Use the Knowledge Base manager in the Admin settings to create new, edit existing, delete KB entries. You can even Filter and Query the Knowledge Base to see what entries (aka Sources) are relevant and would be used in the Chatbot during User queries.

= Is there time limits like with other Avatar chatbots? =

No. You can test and practise with your Avatars as long as you like, and Users can interact with them as long as you like. There are no time limts like other 3D Avatar providers. This is something we thought was very annoying with other providers and inspired us to create this unlimited feature.

= Can I view and analyze my visitor's chat conversations? =

Not with the Free version of the plugin, but definitely with any of the paid plans.

= More FAQs = 

[More FAQs and Demos here](https://twxchat.twxlabs.au/).

== External Service Usage ==

= OpenAI =
This plugin connects to the OpenAI API (https://api.openai.com) in order to provide AI-powered responses and functionality. This includes streaming and non-streaming responses to the Chatbot, and also OpenAI Assistant integration (Chat Threads, Responses, Files etc).

OpenAI API Terms of Service: https://openai.com/policies/terms-of-use  
OpenAI API Privacy Policy: https://openai.com/policies/privacy-policy

= Amazon AWS =
This plugin also connects to Amazon Polly and S3 APIs (*.amazonaws.com) in order to provide Text-To-Speech audio during Avatar Chatbot conversations.

AWS Customer Agreement (Terms of Service): https://aws.amazon.com/service-terms/
AWS Privacy Notice: https://aws.amazon.com/privacy/

== Account Requirements ==
To use API features, an account with OpenAI and optionally Amazon AWS may be required. API keys are entered by the user in the plugin settings.

== Remote Resources ==
The plugin connects to our external server (twxchat.twxlabs.au) in order to download 3D avatar assets. This occurs once per Avatar Character selection only. This helps keep the ZIP distributable to a manageable size rather than having all the Character GLTF 3D models in the package. 
It also allows us to release new Avatar Characters in future which can simply be downloaded as needed.

If you are on a paid plan, calls to the remote server are also made to verifiy your Customer Key.

== Directly Accessible Files ==
The following scripts are directly accessible by design for the followig reasons:

* stream_handler.php - is intentionally accessed directly via javascript EventSource for streaming responses from OpenAI. This file includes the proper WordPress bootstrap and nonce checks within it to prevent unauthorized access.

== Screenshots ==

1. Chatbot in action - Talking Avatar Floating
2. Chatbot in action - Talking Avatar Expanded with Conversation Panel and Flashcards
3. Chatbot in action - Embedded Chatbot with Sources and Feedback
4. Admin Settings - Chatbots list and Edit
5. Admin Settings - Site Crawler
6. Admin Settings - Knowledge Base
7. Admin Settings - Chat Log (available in paid plans)

== Changelog ==

= 1.12.2 =
* Bugfix: Duplicate Chatlog entries being inserted in some Chatbot conversations every few seconds. Fixed. Also will auto-delete old dup entries on plugin update.
* Enh: Improved RAG generation and initial responses for Chatbots with User Defined Fields. Previously hallucinating a little.
* Bugfix: Some pages causing error in log: Attempt to read property "post_content" on null...
* Bugfix: Deprecation errors in log: mb_convert_encoding(): Handling HTML entities via mbstring is deprecated; use htmlspecialchars, htmlentities, or mb_encode_numericentity/mb_decode_numericentity...

= 1.12.0 =
* Enh: Replaced old OpenAI Chat Completions API calls with new Responses API
* Enh: New Chatbot setting: 'Max Output Tokens' can now be set for better control over Chatbot output length (avoids runaway bot responses)

= 1.11.3 =
* Bugfix: Sitemap crawl deletion of previous temp files failing. Fixed
* Bugfix: Cross contamination of Chat Logs for multiple chatbots using 'remember conversation' setting. Fixed

= 1.11.2 =
* Bugfix: Site Crawl progress never completing. Fixed
* Enh: Delete all old .md files from spider results prior to crawl
* Bugfix: After creating a new floating Chatbot, it doesn't appear in the Customize tab Chatbots dropdown lists
* Enh: On mobile devices, strip down floating chatbots that have splash image to just show the image. Less real-estate used
* Bugfix: Chatbot settings: Flashcards option was showing for Non-Avatar Chatbot type

= 1.11.1 =
* Enh: Deprecate setting Customize > 'Frontpage Shortcode'. Now select Chatbot from new setting Customize > 'Frontpage Chatbot' list. Gets popualted automatically on update from deprecated value if exists.
* Enh: New setting: Customize > Global Chatbot. Allow selected Chatbot to be on all web pages/posts (unless overriden by shortcode). Chatbot must have 'Remember Conversation' on and must be 'Floating' style.
* Bugfix: Refactor Yethee\Tiktoken usage which apparently hasnt been working properly until now
* Enh: New Chatbot Setting: 'Continue Comments/Greeting' allows for a different greeting when re-joining a previous (remembered) chatbot conversation.
* Enh: Avatar chatbots, don't hide load screen greeting after load. Keep it in top left until Start button clicked.

= 1.10.4 =
* Enh: Multi-Lingual Site Crawler progress
* Enh: Improved large web page content chunking during Site Crawl

= 1.10.3 =
* Bugfix: JS Module load error.

= 1.10.2 =
* Enh: Multi-Lingual enhancements (Admin UI). Including auto generation of locale files as required.

= 1.9.27 =
* Bugfix: getMarkdown function. Remove all 4-byte UTF-8 characters (emojis, rare symbols). Causing error: Processing the value for the following field failed: orig_text. The supplied value may be too long or contains invalid data.
* Bugfix: query-chatbot REST API endpoint not validating min_similarity parameter properly.
* Enh: Multi-Lingual enhancements. New 'OpenAI Text Embedding Model' General Setting to allow for additional non-latin languages & better KB matching. ChatLog 'translate' feature if receive queries in other langs.

= 1.9.23 = 
* Bugfix: Chatlog update issue from JS. Fixed.

= 1.9.22 = 
* Enh: Users can now re-join their previous Chatbot conversations using Thread ID. Admins can allow this for any user with a valid Thread ID or just logged-in users.
* Bugfix: Admin Chatlog filtering was returning more results than filter specified.

= 1.9.19 = 
* Enh: Site Crawler now cleans up old/non-existing Knowledge Base entries to ensure Chatbots dont use them during conversations.

= 1.9.17 = 
* Bugfix: Split large content pages/posts into separate KB entries avoiding Site Crawler errors.

= 1.9.16 = 
* Bugfix: Site Crawler was crawling Password Protected pages even only selecting Public Pages/Posts in settings.

= 1.9.15 = 
* Enh: Better reporting on Site Crawler (LLM token checks prior to embedding)

= 1.9.14 = 
* Enh: All versions. Option to receive Daily/Weekly email summaries of visitor interactions. See new 'Reports' settings tab. Requires SMTP to be configured in Wordpress.
* Enh: Better error and progress reporting on Site Crawler.

= 1.9.11 = 
* Enh: Pro version. REST API for Chatbot Query added. Developers can now query a TWX-Chat chatbot from their Apps. Includes long-running conversations/threads and Chat Log entries.

= 1.9.10 = 
* Enh: Site Cralwer > Crawl onsite Media items, will now also crawl PDFs in the Media Library. PDFs are split into pages and each page is inserted into the Knowledge Base. Only PDFs with 'Description' or 'Caption' metadata are crawled.

= 1.9.9 = 
* Enh: Improve .js and .css refresh on browser after new releases
* Enh: Site Crawler. Added 'Exclude sources' setting to allow exclusion of unwanted posts/pages in KB

= 1.9.8 = 
* Bugfix: Getting error 'missing/empty param: threadId' for OpenAI Assistants using streaming. This has not been implemented yet. Fixed validation in chatbot settings.
* Enh: improved chatbot setting show/hide and handling in ajax events.

= 1.9.5 = 
* Bugfix: If enter Assistant ID in chatbot settings and then switch back to 'Knowledge Base' setting, getting missing threadId error in chatbot. Improved validation also.

= 1.9.4 = 
* Enh: Chatbot Settings. Additional validation for Avatar voices that are unsupported by AWS Cognito Pool Identity Key region
* Enh: Plugin Settings. Generate additional Copy Support Info

= 1.9.3 = 
* Enh: Chatbot Settings. Allow Avatar voice selection from dropdown list instead of old text entry and also Play sample voice

= 1.9.1 = 
* Enh: Pro Plan. WooCommerce Product integration into the Site Crawl/Knowledge Base
* Enh: Detect if Free codebase downloaded from twxlabs.au and auto check for updates

= 1.8.19 = 
* Bugfix: Create/Edit Chatbot console error. Missing array element 'model'

= 1.8.18 = 
* Enh: Allow FREE Plan users to select any 2 Avatar Characters (not just Cristine & Luke characters like before)

= 1.8.16 =
* Enh: Added LLMS.txt creation option to Site Crawler settings
* Bugfix: (minor) Fixed hyperlink escaping in Site Crawler Last Run setting

= 1.8.15 =
* Admin Test: Auto and manual plugin update options for paid plans

= 1.8.9 =
* Removed old twxBabylon js from assets/js
* Admin Enh: Updated Plugin 'View Details' logic for paid plans
* Admin Enh: Auto plugin update for paid plans
* Admin Enh: New 'Update Now!' button in 'Plugin Info' tab for manual plugin update without ZIP download
* Admin Bugfix: 'Plugin Info' tab. Invalid Customer Key allowing manual 'Check for Updates'

= 1.8.8 =
* Bugfix: Feature buttons click causing navigation error
* Readme.txt updates

= 1.8.6 =
* Readme.txt updates

= 1.8.5 =
* Version approved by Wordpress.org

= 1.7.7 =
* Version re-submitted to Wordpress.org with suggested fixes

= 1.7.0 =
* Version submitted to Wordpress.org for review

== Planned Improvements ==
* Better Internationalization
* More Avatar Characters
* MCP/Agent2Agent support
* Also there a loads more features in our paid plans. Check the [twxchat website here](https://twxchat.twxlabs.au/features)


