Documentation
Everything you need to install, configure and troubleshoot IrisAI.
Where things live
IrisAI adds one menu item with five tabs, plus a separate Search Eval page.
Settings
Subtabs for General, Knowledge Index, Chat Page, Widget, Appearance, Advanced and Usage.
Account
Plan, credits, usage history and billing.
Knowledge Base
What’s indexed, document stats and indexing controls.
Chat History
What visitors have actually asked.
Chat Tester
Try questions from the admin, with a debug panel.
Search Eval
Run saved questions against retrieval and inspect the scores.
Getting started
Requirements
- WordPress 5.0 or later
- PHP 8.0 or later
- Outbound HTTPS from your server to your AI provider
Step 1 · Install
Install and activate the plugin, then open IrisAI from the admin menu. The setup wizard runs the first time and has two steps: connect, then index.
Step 2 · Connect
Option 1 · Start Free
One click. Your account, API key and trial credits are created automatically — no signup form, nothing to copy.
Option 2 · Existing IrisAI key
In the collapsed advanced panel. Enter your Proxy Base URL and IrisAI API key by hand.
Option 3 · Bring your own key
Use an OpenAI, Claude or Gemini key of your own. Your provider bills you directly.
Don’t confuse Options 2 and 3
Option 2 expects an IrisAI key. A provider key entered there will not work.
Step 3 · Index your content
Choose which post types to index. Posts and pages are preselected, and each type shows how many items it holds. Indexing runs in the background, so you can leave the page. You can re-run or extend it later from Knowledge Base.
Step 4 · Place the assistant
| Placement | How | Notes |
|---|---|---|
| Floating widget | On by default | Configure under Settings → Widget |
| Full-page chat | [irisai_chat] | Use a full-width template |
| Manual widget | [irisai_widget] | Optional position="bottom-left" |
Configuration
Choosing a model
In Proxy mode, Settings → General offers current models from OpenAI, Anthropic and Google in one dropdown. In BYO the field is free text. For answering questions from your own content, economy models perform close to flagships — the facts come from your content, not the model.
Response length
Under Settings → General. Output tokens are the expensive half of a request, so this is your highest-leverage cost setting. 800–1,000 is generous for a site assistant.
System prompt
The default already forbids stating prices, dates, names, phone numbers, emails or addresses absent from your content, tells the assistant to decline when nothing matches, and to reply in the visitor’s language. Add your rules on top rather than replacing it.
Auto re-index
Under Settings → Knowledge Index. Editing a post refreshes that post’s passages, splitting by length rather than by heading — so run a full re-index after restructuring or bulk publishing.
Embeddings in BYO mode
Semantic search needs an embedding model. An OpenAI or Google key provides one; a chat-only key such as Anthropic’s does not, and IrisAI falls back to keyword matching. Add an OpenAI or Google embedding key under Settings → Knowledge Index if you run Claude for chat.
Embedding models produce different vector sizes and are not interchangeable. Changing yours means clearing the vector data and running a full re-index.
Troubleshooting
Start with Search Eval — most “wrong answer” reports are retrieval problems, not model problems.
Search Eval takes a list of questions and shows, for each, the top matching passage, its similarity score, the keyword boost, the final score and whether the assistant would answer or decline. No answer is generated, so you skip the expensive half of a request — each question costs one embedding to match, cached for an hour while you iterate.
The assistant says it doesn’t have those details
Usually correct behaviour: nothing indexed matched well enough. Check in Search Eval whether the right passage is found at all.
- Is the page’s post type actually indexed?
- Does the fact exist as text, rather than in an image or a footer? Footers and template parts are not post content and are never indexed.
- Has the page been restructured since the last full re-index?
Chat isn’t working at all
- Check the Account tab for remaining credits (Proxy mode).
- Confirm your domain is registered against your account.
- Use Chat Tester with the debug panel on — it shows the request, timing and any error.
- Enable
WP_DEBUGfor detailed logs.
“Embedding dimensions do not match”
Your index was built with a different embedding model than the one now in use. Clear the vector data from Knowledge Base and run a full re-index.
The widget isn’t appearing
- Check it’s enabled under Settings → Widget, and that visibility rules include the page.
- Clear any page or CDN cache.
- Check the browser console for JavaScript conflicts.
Removing IrisAI cleanly
Deactivating leaves your data in place. For a clean removal, enable Remove data on uninstall under Settings → Advanced first, then deactivate and delete the plugin. That removes settings, indexed passages, cached results and the plugin’s tables.
Without that option enabled, deleting the plugin leaves the tables behind, so reinstalling later keeps your existing index.
Ready to set it up on your own site?