--- title: WP Support Agent Documentation date: 2026-08-29 modified: 2026-08-30 author: url: "https://techcreative.dev/wp-support-agent/documentation/" categories: - name: Uncategorized url: "https://techcreative.dev/uncategorized/" post_type: page word_count: 2439 estimated_tokens: 3171 --- # WP Support Agent Documentation Documentation # WP Support Agent Documentation Reference for the free plugin and the Pro add-on: installation, every setting, the knowledge base, placements, the REST routes, developer hooks, the database schema and the changelog. Written against **free 0.5.0** and **Pro 0.5.0**. [Download Free](/download/5344.md) [Get Pro — $49](/checkout/?add-to-cart=5317.md) [Product Overview](/wp-support-agent.md) 6.2+ WordPress required 7.4+ PHP required 13 Provider presets 3 Database tables Getting Started ## Installation and Requirements ### Requirements - WordPress 6.2 or newer - PHP 7.4 or newer - MySQL 5.6+ or MariaDB 10.0+ (FULLTEXT index support) - An API key from one of the 13 supported AI services - Outbound HTTPS from your server to that AI service ### Installing **1.** Upload the zip under *Plugins → Add New → Upload Plugin*, or extract it into `wp-content/plugins/`. **2.** Activate *WP Support Agent*. Activation creates the three database tables and schedules the daily conversation purge. **3.** The setup wizard opens automatically. If it does not, go to *Support Agent → Setup*. **4.** For Pro, install *WP Support Agent Pro* as a second plugin and enter your licence key under *Support Agent → Licence*. Pro requires the free plugin and stays inert without it. Where Things Live ## Admin Screens ### Free - Setup — the four step wizard - Settings — provider, content, privacy, limits - Appearance — designer with live preview - Knowledge — the indexed entries - Conversations — transcripts, ratings, CSV export ### Pro adds - Analytics — deflection, satisfaction, unanswered - Licence — activation, status, contact details All screens sit under the top-level *Support Agent* menu. Every screen requires `manage_options`. ![WP Support Agent conversations log showing transcripts, per-reply ratings and CSV export](https://techcreative.dev/wp-content/uploads/2026/08/wp-support-agent-documentation-conversations-log.webp) First Run ## The Setup Wizard, Step by Step 01 ### Business Business name, a short description, and the support email the agent falls back to. These are written into the system prompt. 02 ### Content Every public post type with a published count. What you tick becomes `source_post_types` and is queued for indexing. 03 ### AI provider Pick a preset, follow the linked instructions, paste the key. The wizard calls the provider to verify it before letting you continue. 04 ### Appearance Agent name, avatar, accent colour and position. A contrast check flags colours that will be hard to read. **Key verification is recorded server-side.** The result of the connection test is stored as `key_status`, `key_checked` and `key_error`, so the Settings screen shows “Key verified 3 minutes ago” or the exact failure reason. Saving a new key clears that status. Reference ## Settings Reference Every setting lives in a single autoloaded option, `wpsa_settings`, so the front end needs one query. API keys are never in this array — they are encrypted separately by `WPSA_Credentials`. Defaults are shown in brackets. ![WP Support Agent documentation: the settings screen behind every option in the reference](https://techcreative.dev/wp-content/uploads/2026/08/wp-support-agent-documentation-settings-reference.webp) Business profile and agent persona **business_name** — Used in the system prompt and the panel header. **business_description** — One or two lines on what you do. **support_email** — Where the agent sends people it cannot help. **agent_name** — Display name in the chat panel. [Support Agent] **agent_role** — Optional role line, e.g. “Course support”. **agent_avatar** — Built-in icon or an uploaded attachment. [svg:headset] **primary_context** — Free text that overrides all indexed content. Put prices, hours and refund terms here. **strict_grounding** — Refuse anything the retrieved passages do not support. [true] AI provider **provider** — One of the 13 preset slugs, or a custom endpoint slug. **model** — Model id, populated live from the provider. **custom_base_url** — Base URL for the two custom endpoint presets. **temperature** — Sampling temperature. [0.2] **max_tokens** — Ceiling on reply length. [1024] **key_status / key_checked / key_error** — Written by the connection test; read-only in practice. Content sources **source_post_types** — Post types the agent may read. [post, page] **content_source** — auto, agentpress or builtin. [auto] — auto prefers AgentPress MD Markdown where it exists and falls back to the built-in extractor. **context_chunks** — How many passages to retrieve per question. [6] **context_budget** — Character ceiling on retrieved context. [6000] Widget behaviour and placement **enabled** — Master switch. [true] **placement** — floating, top_bar, header, footer or shortcode. [floating] — the three in-page modes require Pro. **position** — Corner for the floating launcher. [bottom-right] **placement_selector** — CSS selector the panel relocates into for the header and footer modes. **offset_x / offset_y** — Floating launcher offsets in px. [24 / 24] **welcome_message** — First message shown inside the panel. **greeting_message / show_greeting** — Optional bubble beside the launcher. **placeholder** — Input placeholder text. **suggestions** — Starter questions shown as chips. **show_badge** — Attribution badge. Honoured only on the WordPress.org build; a valid licence always removes it. Appearance **theme_preset** — clean, soft, bold, dark or glass. [clean] **color_primary / color_surface / color_text** — Accent, panel and text colours. [#2563eb / #ffffff / #0f172a] **color_scheme** — light, dark or auto. [auto] **radius / panel_width / panel_height / launcher_size** — Geometry in px. [16 / 400 / 560 / 56] **launcher_icon** — avatar follows agent_avatar, or pick an icon. [avatar] **font / font_size** — theme inherits your site font. [theme / 15] **bubble_style / header_style / shadow** — rounded, solid, medium. [rounded / solid / medium] **launcher_label** — Text label beside the launcher. **avatar_in_messages** — Show the avatar on every reply. [false] **custom_css** — Applied only with a valid licence. Privacy, abuse and cost controls **require_consent / consent_message / privacy_url** — Optional consent gate before the first message. [false] **rate_limit / rate_window** — Messages per visitor per window, in seconds. [20 per 600] **session_max_messages** — Hard stop on one conversation. [60] **daily_message_cap** — Site-wide ceiling per day. [1000] **max_message_length** — Characters accepted per message. [2000] **retention_days** — Conversations are deleted after this many days by a daily cron event. [30] Handoff and business hours (Pro) **escalation_enabled** — Show the handoff form in the panel. [false] **business_hours** — Per-day open and close times. Consecutive identical days are collapsed for display, so a normal week reads “Monday to Friday, 09:00-17:00”. **contact_phone / contact_address / contact_hours_note** — Rendered above the handoff form and injected into the system prompt under an availability heading. Editable on the Pro Licence screen. How Answers Are Found ## The Knowledge Base Finishing the wizard queues a background scan of every published post in the post types you selected. Each post is reduced to readable prose, split into passages, and written to the chunks table with a MySQL `FULLTEXT` index across title and body. Retrieval is keyword based, not vector based. There are no embeddings, so there is no embedding bill, no re-indexing when you change model, and no external service beyond the one answering the question. Entries are stored as a private post type, `wpsa_kb`, grouped by the `wpsa_kb_group` taxonomy. You can edit any entry by hand, mark it as priority so it outranks other passages, or disable it without deleting it. Page builder content Elementor, Bricks, Divi and WPBakery store layout JSON rather than prose in `post_content`, so a naive scanner indexes almost nothing. Where **AgentPress MD** is installed, the plugin reads the Markdown it has already generated from post meta — no HTTP call and no class coupling, so it keeps working even if AgentPress is deactivated. Without it, a built-in extractor handles most layouts. ![WP Support Agent knowledge base with 1,045 searchable passages and per post type content coverage](https://techcreative.dev/wp-content/uploads/2026/08/wp-support-agent-documentation-knowledge-base.webp) Putting It On The Page ## Placements and the Shortcode ### Floating A launcher button in a corner; the panel overlays the page. Available in the free plugin. ### Shortcode Place `[wp_support_agent]` anywhere in your content and the panel renders inline. The shortcode takes no attributes — it uses your saved settings. Free. ### Sticky bar, header, footer A labelled bar in normal flow that expands and collapses in place rather than opening a popup. Requires Pro. Only one instance renders per page load, whichever placement fires first. The widget prints at `wp_footer` priority 5 and the script initialises on DOM ready, so it does not matter which runs first. ![WP Support Agent appearance presets, panel shape, size and avatar options documented](https://techcreative.dev/wp-content/uploads/2026/08/wp-support-agent-documentation-appearance-presets.webp) Pro Add-on ## What Pro Adds ### Analytics - Deflection rate — replies that answered vs declined - Satisfaction — from per-reply thumb ratings - Conversations, messages and token totals - Per-day trend over the selected window - Unanswered questions, ranked - Top pages that trigger a chat ### Handoff to a person - Form inside the chat panel - Full transcript emailed to your support address - Header-injection guards on every field - Same-origin check on the endpoint - Fires wpsap_escalated for your own integrations ### Presentation and hours - Attribution badge removed - Sticky bar, header and footer placements - Custom CSS field - Business hours with an open or closed badge - Contact card with a tap-to-call link - Automatic updates via the licence server Business hours inform the agent rather than blocking the chat: outside your hours it still answers, but it tells the visitor when a person will be back. Pro ## Licence and Updates A Pro licence covers **one site** for **365 days**. Activating writes the `wpsa_license` option, which the free plugin already uses as its feature flag, so everything unlocks immediately with no further handshake. The plugin keeps working when the year is up. What stops is update delivery and priority support, until you renew. Repeated failures are handled carefully: three consecutive *invalid* answers from the licence server lock the licence, but network failures do not count against you — an unreachable server never deactivates a paying customer. Endpoints Licence operations run against `techcreative.dev/wp-json/apmd-licensing/v1/` **/activate** — bind the key to this site **/deactivate** — release the site **/check** — periodic revalidation **/product-metadata** — current version for the updater **/download** — signed package download For Developers ## REST Routes, Hooks and Schema REST API routes All routes sit under the `wp-support-agent/v1` namespace. **Public** — unauthenticated by design, because a visitor is not a logged-in user. Every one is protected by a signed session cookie, a same-origin check, a per-visitor rate limit and the site-wide daily cap. **POST /chat** — send a message; streams by default, pass stream=false for a single JSON reply **GET /history** — messages in the current session **POST /reset** — start a new session **POST /rate** — thumb rating on one reply **POST /escalate** — hand off to a person (Pro) **Admin** — all require `manage_options` and a valid REST nonce. **POST /admin/models** — list models from the configured provider **POST /admin/test** — verify the API key against the live service **POST /admin/scan** — run or resume a knowledge base scan **POST /admin/agentpress** — trigger AgentPress MD generation **POST /admin/save** — persist settings Filters **wpsa_is_pro** — the master feature gate; Pro narrows it further so an expired licence stops unlocking features immediately **wpsa_system_prompt** — the assembled system prompt before it is sent **wpsa_retrieve_context** — the passages retrieved for a question **wpsa_providers** — the provider registry **wpsa_presets** — appearance presets **wpsa_avatars** — the built-in avatar set **wpsa_sources** — registered content sources **wpsa_make_transport** — swap the HTTP transport **wpsa_should_render** — whether the widget renders on this request **wpsa_can_stream** — allow or block streaming **wpsa_allowed_origins** — extra origins accepted by the same-origin check **wpsa_client_ip** — how the visitor IP is derived before hashing **wpsa_purge_cache** — override the page cache purge **wpsap_license_api_url** — point Pro at a different licence server Actions **wpsa_loaded** — the free plugin has booted; Pro hooks this, so an add-on is inert without it **wpsap_loaded** — the Pro add-on has booted **wpsa_purged_caches** — fired after page caches are cleared **wpsap_escalated** — fired after a successful handoff, for CRM or helpdesk integrations Database schema Three tables, all prefixed like the rest of your install. Schema version `1.2.0`, tracked in the `wpsa_db_version` option. **wpsa_sessions** — one row per conversation: session key, hashed visitor, user id, page URL, locale, message count, rating, resolved flag, timestamps **wpsa_messages** — one row per message: role, content, raw payload, model, input and output token counts, per-reply rating **wpsa_chunks** — the knowledge base: entry and source ids, sequence, title, URL, body, priority and enabled flags, plus the FULLTEXT index over title and body **Visitor IP addresses are never stored.** `visitor_hash` is a salted hash used only for rate limiting, which is what lets the plugin throttle abuse without keeping personal data. Scheduled events and options **wpsa_purge_conversations** — daily; deletes conversations older than retention_days **wpsa_scan_batch** — indexes the knowledge base in batches **Options written:** `wpsa_settings`, `wpsa_version`, `wpsa_db_version`, `wpsa_license`, `wpsa_scan_queue`, `wpsa_scan_state`, `wpsa_error_log`. API keys are stored separately and encrypted by `WPSA_Credentials`, using a key derived from your site’s security salts. Uninstall behaviour Deleting the plugin through the WordPress admin runs `uninstall.php`, which is deliberately thorough: it drops all three tables, purges the encrypted credentials, deletes every option listed above, removes all `wpsa_kb` entries and their `wpsa_kb_group` terms, and clears the scheduled events. Deactivating does none of this — it only unschedules the cron events. If you want to keep your knowledge base and conversation history, deactivate rather than delete. Compatibility ## Supported AI Providers Thirteen presets, reached through just two transports: the OpenAI `/chat/completions` shape and the Anthropic `/v1/messages` shape. That is why flat-fee plans such as Z.ai and Moonshot work — they expose Anthropic-compatible endpoints. ### OpenAI transport - Google Gemini — free tier - Groq — free tier - OpenAI - Mistral AI - DeepSeek - Cerebras - OpenRouter - Local model (Ollama / LM Studio) - Any OpenAI-compatible endpoint ### Anthropic transport - Anthropic Claude - Z.ai GLM Coding Plan — flat monthly - Moonshot Kimi — flat monthly - Any Anthropic-compatible endpoint Consumer chat subscriptions to ChatGPT or Claude are not API access and cannot be used here. History ## Changelog 0.5.0 — current Appearance is now a single screen with a live preview, no longer duplicated as a settings tab. Every settings screen shares one set of controls. Sticky bar, header and footer placements expand in place instead of opening a popup. The settings screen now shows when the API key was last checked, and why a check failed. **Fixed:** the widget could bind its listeners twice if a caching or optimisation plugin loaded the script twice, so one click sent two messages. **Fixed:** the conversation export read every message into memory at once. **Hardened:** cross-site requests to the chat endpoints are refused consistently. 0.3.0 Appearance designer: presets, bubble and header styles, depth, fonts, launcher label. Placement modes, avatar auto-cropping, per-reply ratings. Conversations log with search, filtering, bulk actions and CSV export. 0.2.0 Knowledge base built from your content, editable by hand and grouped by post type. Reads Markdown from AgentPress MD where present, so page-builder content is understood. Answers cite the pages they came from. 0.1.0 Initial release. Help ## Something Not Covered Here? Pro licences include priority email support. If you are evaluating, or something in this reference does not match what you are seeing, get in touch and we will sort it out. [Ask a Question](/get-started.md) [Get Pro — $49](/checkout/?add-to-cart=5317.md) New here? Start with the [WP Support Agent overview](/wp-support-agent.md), or see how it [compares with other chatbot plugins](/best-wordpress-chatbot-plugin.md).