Sohay — AI Chatbot for Knowledge Base and WooCommerce

Sohay works with OpenAI or Google (Gemini) — choose one under Sohay → AI Settings. OpenAI is the default. You can switch at any time; each provider's key and model choice are stored separately, so switching back does not mean re-entering anything. One thing to know before choosing: the Knowledge Base indexes and searches your articles through OpenAI whichever provider answers the chat. If you select Gemini and use the Knowledge Base, keep an OpenAI key saved as well. Without one, the chatbot still replies but stops consulting your articles.

Yes. Sohay is a front-end for someone else's models — without an API key the plugin has no model to call and the chat cannot answer questions. The provider bills you directly per token; Sohay does not resell access. The Spend protection controls under AI Settings let you cap daily token usage to keep costs predictable.

Providers charge per token, and the per-token rate depends on the model you pick (the cheaper models cost a fraction of a cent per chat reply). A small support site typically stays in single-digit dollars per month. The Spend protection controls under AI Settings let you cap daily token usage — once the cap is hit, the plugin stops calling the provider for the rest of the day. The Diagnostics page shows today's usage so you can spot a runaway loop or a hostile bot before it costs you real money.

The chatbot is grounded in the articles you publish — if it can't find a matching article, it tells the visitor it doesn't know instead of inventing an answer. To improve answer quality, publish articles covering the questions you actually get asked, and write a fallback "Contact us" article so the chatbot can route off-topic questions to your human support team.

Sohay → Conversations lists every chat — search them, filter by status, assign a chat to a teammate, or reply yourself. The Diagnostics page shows OpenAI errors if you're investigating a technical problem.

By default, every WordPress administrator can read every conversation. The plugin ships with five granular capabilities so you can delegate access — for example, give a support agent the ability to read and reply to chats without granting them access to AI Settings. See the developer questions below for an overview, and the capability documentation in the plugin's GitHub repository for the full matrix with worked role-configuration examples.

A tiny launcher (~8 KB) loads on every page. The full chat code only downloads when a visitor actually clicks to open the chat, so most visitors never download it. No third-party scripts, fonts, or trackers are loaded from external CDNs.

The chat renders inside an isolated container so that your theme's styling cannot break the chat, and the chat's styling cannot change your site's fonts, colours, borders, or spacing. That isolation is deliberate — it is what makes the widget look and behave the same way on every theme. The trade-off is that other plugins and scripts which scan your pages for content do not look inside that container. In practice:

• Translation plugins (TranslatePress, Weglot, and similar) will not translate the chat's own wording. This does not affect your visitors' answers — the chatbot replies in the language the visitor writes in — and Sohay's own buttons and labels are translated through WordPress's standard translation files.
• Session-replay and heatmap tools (Hotjar, Clarity, FullStory) record the widget as a blank area.
• Accessibility overlays that restyle a page from the outside will not restyle the chat.

On stores running WooCommerce 7.0 or later, a shopper can:

• Search and browse your catalog — "show me waterproof jackets under $100", "what's new?", "what's on sale?" — results come back as product cards with photo, price, and stock.
• Look at one product in detail, including its options, so they can pick a size or colour without leaving the chat.
• See live stock and prices, read from your store at the moment they ask.
• Ask about shipping, returns, refunds, and payment — answered from your WooCommerce store pages first, then from Knowledge Base articles you've tagged "policy" or "faq".
• Manage their cart — add an item, change a quantity, or remove a line, each with an Undo button.

Yes. The chat widget, Knowledge Base, and Conversations inbox work on any WordPress site — the shopping tools simply never appear. On stores running WooCommerce 7.0 or later they switch on by themselves, with no configuration. The plugin also declares HPOS and Cart-Checkout-Blocks compatibility so stores don't see an "uncertified plugin" banner.

Uncheck Show widget under Sohay → AI Settings to hide it everywhere. To hide it only on certain pages or post types, see the developer questions below.

Yes. Sohay → AI Settings has a Welcome Message field (max 280 characters). Sohay → KB Settings → Settings has a Custom System Prompt field (max 4000 characters) for the instructions the chatbot follows when it generates answers. The Custom System Prompt field recognises {site_name} and {current_date} placeholders — they are replaced with your site's title and today's date before the prompt is sent to the model.

Encrypted with AES-256-GCM in your WordPress database. The admin UI shows a masked placeholder once you've saved a key, and the values are excluded from the WordPress REST API. Each key is only ever sent to the service it belongs to.

Uninstalling deletes the plugin's own database tables (conversations, messages, sync jobs, diagnostic logs), its settings, and the capabilities it added. Your Knowledge Base articles are kept — they're regular WordPress content, so removing the plugin doesn't delete them, and they're still there if you reinstall. If you want them gone too, delete the articles under KB Articles before you uninstall.

Yes. Each site in the network keeps its own conversations, Knowledge Base, and settings — nothing is shared across the network. Network-activate to enable Sohay everywhere (each site sets itself up on first load) or activate it per-site. Uninstalling from the network removes Sohay's data from every site.

The questions below cover code-level customization. Sohay exposes 48 filters and 12 actions in total; the most-used ones appear here, and the full catalog lives in docs/HOOKS.md in the plugin's GitHub repository, alongside docs/CAPABILITIES.md for the full capability matrix.

The most commonly customized filters:

• sohaychat_should_render_widget (bool) — per-request gate on the chat widget. Combine with is_singular() / is_product() to scope the widget to specific pages.
• sohaychat_allowed_openai_models / sohaychat_allowed_google_models (string[]) — allowlist of model slugs the proxy may call for each provider. Restrict to cheaper models to cap spend.
• sohaychat_default_ai_provider (string) — which provider answers the chat when no choice is saved in the admin.
• sohaychat_provider_options (array) — provider-specific request settings, such as Gemini's safety thresholds, thinking budget, or search grounding.
• sohaychat_help_url and sohaychat_upgrade_url (string) — override the admin-header "Help" and "Upgrade" links for resellers.
• sohaychat_admin_conversation_scope — restrict which conversations a non-admin operator can see.
• sohaychat_tools — the resolved tool list for the request. Remove an entry and the chatbot is never told that tool exists, so it can neither call it nor send its data to your AI provider.

Five granular capabilities let you delegate parts of the plugin to non-admin roles:

• sohaychat_manage — AI Settings page, provider selection, API key entry, model selection. Implicitly grants all four other plugin caps.
• sohaychat_view_conversations — Sohay menu, Dashboard + Conversations submenus (read-only). Non-admin users with this cap are scoped to "assigned to me or unassigned" conversations.
• sohaychat_reply_conversations — everything sohaychat_view_conversations grants, plus operator reply, assignee changes, pin / unpin, close / reopen. Implicitly grants sohaychat_view_conversations.
• sohaychat_manage_kb — KB Settings admin page and KB sync routes.
• sohaychat_view_logs — Diagnostics admin page (read-only). Clearing the log buffer is escalated to sohaychat_manage for forensics integrity.

Three independent limiter filters. The chat-message rate limit (limit requests per rolling window seconds, per visitor): add_filter( 'sohaychat_rate_limit_options', function ( $opts ) { $opts['limit'] = 60; $opts['window'] = 60; return $opts; } ); Behind Cloudflare or another reverse proxy, enable proxy-aware client-IP detection so per-visitor limits key off the real visitor rather than the proxy: add_filter( 'sohaychat_rate_limit_options', function ( $opts ) { $opts['proxy_support'] = true; return $opts; } ); Enable proxy_support only when your site is reachable exclusively through the trusted proxy, and that proxy overwrites the CF-Connecting-IP / X-Real-IP / X-Forwarded-For headers on every request. On an origin that's also reachable directly, a visitor could forge those headers to sidestep per-visitor limits; the site-wide daily token budget still caps total spend. The public /auth/guest-token mint rate limit (separate so token-mint amplification protection can be tuned independently): add_filter( 'sohaychat_auth_rate_limit_options', function ( $opts ) { $opts['limit'] = 5; $opts['window'] = 60; return $opts; } ); The daily OpenAI token budget (caps also configurable under AI Settings → Spend protection; ceilings reset at UTC midnight; setting either value to 0 disables that particular ceiling): add_filter( 'sohaychat_usage_tracker_options', function ( $opts ) { $opts['site_cap'] = 5000000; $opts['actor_cap'] = 25000; return $opts; } ); The live readout on the Diagnostics page shows today's usage so you can spot a runaway loop before it 429s real visitors.

KB vector-search results are memoized in the sohaychat_kb object-cache group for 5 minutes by default. To shorten the window, lengthen it, or disable the cache entirely, use the sohaychat_kb_search_cache_ttl filter (return 0 to disable): add_filter( 'sohaychat_kb_search_cache_ttl', '__return_zero' ); KB sync events flush the cache automatically, so content updates don't get masked.

The plugin sets Cache-Control: no-cache, X-Accel-Buffering: no, and clears output buffers, but some CDNs still buffer Server-Sent Events. If your CDN supports it, mark the chat REST route as bypassing the cache and disable transformations on the response.

Sohay → Diagnostics shows the last 100 plugin log entries with timestamps and context. Each entry also fires the sohaychat_log_error action for integration with Sentry, Stackdriver, Query Monitor, etc.