Sohay — AI Chatbot for Knowledge Base and WooCommerce

ხდკ

Which AI provider should I pick, and can I switch later?

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.

Do I need an account with an AI provider?

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.

How much will it cost me?

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.

Will the chatbot make things up?

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.

Where can I see what visitors are asking?

Sohay → Conversations lists every chat — search them, filter by status, assign a chat to a teammate, or reply yourself. Turn on human handoff and you also get views for visitors waiting to talk to a person and for conversations your team has handled. The Diagnostics page shows OpenAI errors if you’re investigating a technical problem.

Can a real person take over a chat from the assistant?

Yes. Turn on Human handoff under Sohay → Settings, and your team can step into any conversation. While someone is handling a chat the assistant stops replying, and the visitor sees that person’s name and picture on the answers rather than the AI marker. Hand it back and the assistant picks up again, with the whole exchange still in front of it.

Visitors can ask for a person with a button above the message box, the assistant can fetch one when it gets stuck, and you can simply jump in — replying to a conversation takes it over.

The setting is off until you switch it on, because handing someone to a person who is not there is worse than not offering it. Set the hours your team actually covers; outside them the widget stops offering, and anyone who asks anyway gets a message you write.

How do I know when somebody is waiting to talk to us?

Four ways, so you don’t have to sit watching the inbox. A Waiting for a Person view in Sohay → Conversations lists them oldest first. The browser tab shows a count, so a background tab still tells you. An email goes out when a request comes in — to addresses you choose, or whoever the conversation is assigned to. And the conversation itself carries a banner with a Take over button.

If nobody picks it up within the time you set (10 minutes by default), the assistant takes the conversation back and tells the visitor honestly that nobody was available, rather than leaving them waiting.

Does human handoff slow my site down?

Only while it’s switched on, and only for visitors with the chat window actually open — those windows quietly check for new replies. Nothing checks while the chat is closed, while the browser tab is in the background, or after ten quiet minutes.

If your host is tight on resources, that background checking is the thing to weigh. A developer can slow it down without touching the plugin’s code. The full arithmetic is in the handoff documentation in the plugin’s GitHub repository.

Will my visitors’ chats be visible to other admins?

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.

Does this slow down my site?

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.

Why don’t my translation or session-recording plugins see the chat widget?

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.

Screen readers and keyboard navigation are unaffected — assistive technology reads the accessibility tree, which the isolation does not hide.

The container is open rather than sealed, so a script that explicitly supports this kind of isolation can still reach the chat’s content. Most third-party scripts do not.

What can shoppers do in the chat on a WooCommerce store?

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.

The chatbot cannot take payment or place an order. When the shopper is ready it hands them to your normal WooCommerce checkout.

Does the plugin work without WooCommerce?

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.

Can I hide the widget on specific pages?

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.

Can I customize the welcome message and system prompt?

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.

Where can visitors read my Knowledge Base?

At /knowledge-base/ on your site. The page lists your KB categories as cards with an article count on each, a search box, and the articles filed under each category. Clicking a card opens that category; searching stays inside the Knowledge Base rather than dropping visitors into your site-wide search results.

These pages are public and indexable on purpose — support articles answer the questions people type into search engines, and the chatbot cites the same URLs when it uses an article to answer.

Can I change the Knowledge Base URL?

Yes. Sohay → KB Settings → Settings has a URL Base field. Set it to docs, help, support — whatever suits your site — and the index and every article move together, from /knowledge-base/getting-started/ to /docs/getting-started/.

Two things worth knowing before you change it. Links to the old addresses stop working, including any a search engine has already indexed, so if the Knowledge Base has been public for a while consider adding redirects. And a base that’s already taken — by one of your pages, by another plugin, or by WordPress itself (category, author, tag, and so on) — is refused with an explanation rather than accepted; pick another, or move the page that’s using it first.

Category pages have their own Category URL Base field just below, defaulting to kb-category. It has to stay separate from the base above — a value equal to it, or sitting inside it, is refused, because the two would compete for the same URLs.

You don’t need to re-save your permalinks afterwards. Sohay rebuilds the URL rules itself.

Can I change how the Knowledge Base pages look?

They’re deliberately plain, and they inherit your theme’s fonts, colours, and link styling so they don’t look bolted on. If you want to go further, your theme can replace any of it: copy archive-kb.php, taxonomy-kb-category.php, search-kb.php, or any file from parts/ out of the plugin’s templates/ folder into a sohaychat/ folder in your theme, and Sohay will use yours instead. Block themes that define their own Knowledge Base template keep it untouched. docs/KB-ARCHIVE.md in the GitHub repository documents each template and what it receives.

Where are my API keys stored?

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.

What happens to my data if I uninstall Sohay?

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.

Does Sohay work on WordPress Multisite?

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.

For developers

The questions below cover code-level customization. Sohay exposes 57 filters and 15 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 and docs/KB-ARCHIVE.md for the Knowledge Base templates.

How do I customize the plugin with code?

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.

Example — keep the WooCommerce catalog answers but never let the cart leave the site:

add_filter( 'sohaychat_tools', function ( $tools ) {
    unset( $tools['sohaychat-wc/get-cart'], $tools['sohaychat-wc/update-cart'] );
    return $tools;
} );

The keys are the tool names: sohaychat-wc/search-catalog, sohaychat-wc/lookup-catalog, sohaychat-wc/get-product, sohaychat-wc/search-shop-policies-and-faqs, sohaychat-wc/get-cart, sohaychat-wc/update-cart, and sohaychat-kb/get-information for the Knowledge Base lookup. Returning an empty array disables tool use entirely — the chatbot still replies, just with no way to look anything up.

Example — hide the widget everywhere except the WooCommerce shop and product pages:

add_filter( 'sohaychat_should_render_widget', function ( $enabled ) {
    if ( ! $enabled ) { return false; }
    return function_exists( 'is_shop' ) && ( is_shop() || is_product() );
} );

The constants on Bengal_Studio\Sohaychat\Sohaychat_Hooks are the recommended form for new code; the legacy literal form continues to work across releases.

How do I delegate access to non-admin roles?

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.

WordPress’s built-in manage_options capability implicitly grants all five, so administrators keep working unchanged. Use Members, User Role Editor, or WP-CLI (wp cap add <role> sohaychat_view_conversations) to delegate caps to non-admin roles. See docs/CAPABILITIES.md in the GitHub repository for the full matrix, every REST route’s required cap, three worked role-configuration examples, and the conversation-scope filter contract.

How do I adjust rate limits or the daily OpenAI token budget in code?

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.

Can I disable the KB search cache?

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.

Why does the streaming response cut off behind my CDN?

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.

Where can I see streaming/proxy errors?

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.