BraidPress for WordPress
Complete documentation for BraidPress v1.0.0. Self-hosted AI agent virtual team workspace inside WordPress Admin with zero third-party SaaS lock-in.
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| WordPress | 6.0 | 6.5 to 7.1+ |
| PHP | 7.4 | 8.1 to 8.5 (with OpenSSL enabled) |
| Database | MySQL 5.7 / MariaDB 10.3 / SQLite | MySQL 8.0+ or MariaDB 10.6+ |
| HTTPS (SSL) | Recommended | Required for Telegram Bot Webhooks |
2. Installation
- Unzip the main CodeCanyon download package on your computer and locate the installable plugin archive
braidpress.zip. - Log into your WordPress Admin dashboard and open Plugins > Add New > Upload Plugin.
- Click Choose File, select
braidpress.zip, click Install Now, and then click Activate Plugin. - On activation, BraidPress automatically creates its 9 prefixed custom tables and seeds 4 starter specialists (SEO Lead, Forms Desk, Content Editor, Site Ops) plus the Website Team group.
- Click Open Workspace on the Plugins screen or open BraidPress from the top-left WordPress Admin sidebar.
3. AI Model Providers & Custom Endpoints
Open BraidPress > Settings > AI Model to connect any language model provider. API keys are encrypted at rest with AES-256-CBC + HMAC-SHA256 derived from your WordPress AUTH_KEY and SECURE_AUTH_SALT constants.
23 Built-in Preset Providers
OpenAI, Anthropic Claude, xAI Grok, Google Gemini, OpenRouter, DeepSeek, Groq, Mistral AI, Together AI, Fireworks AI, Perplexity, Cohere, Cerebras, SambaNova, NVIDIA NIM, Moonshot Kimi, Alibaba Qwen (DashScope), Z.ai GLM, Hugging Face Router, Azure AI Foundry, Ollama (Local), LM Studio (Local), and vLLM (Self-Hosted).
Adding Unlimited Custom OpenAI or Anthropic Endpoints
- Click Add Custom Provider in the top-right corner of Settings.
- Enter a label (for example, Internal LiteLLM Proxy or Custom Claude Gateway).
- Select the wire protocol: OpenAI-compatible (
/chat/completions) or Anthropic Messages (/messages). - Enter the Base URL, Default Model ID, comma-separated model list, and API Key.
- Click Save Custom Provider, then click Test to verify live round-trip latency and Use to activate it as the workspace default (or assign it per-bot in any bot's configuration).
4. Creating Bots, Groups & Bot-to-Bot Handoffs
Click the + button in the BraidPress sidebar header to create a New Bot or New Group.
- Bot Identity: Give each bot a name, unique
@handle, role summary, avatar color, shape, and plain-English instructions. - Model Override: Leave blank to inherit the workspace default, or pick a dedicated provider and model per specialist (for example, a fast low-cost model for form triage and a flagship reasoning model for SEO audits).
- Granular WordPress Tool Access: Check only the WordPress tools that bot is allowed to invoke. Every tool call is enforced server-side in PHP by
ToolRegistrybefore execution. - Virtual Team Groups: Add multiple bots to a Group thread. Mention any teammate using
@handle(for example,@seo-bot audit Post #4 and pass copy fixes to @editor-bot). When a bot tags another teammate in its reply, BraidPress automatically chains a follow-up handoff turn in the same thread up to your configured Max Group Bot Handoffs limit.
5. Inline Human Approvals & Persistent Memory
Every bot supports three safety policies:
- Approve writes (default): Read-only WordPress tools execute immediately; any write tool (updating posts, writing SEO metadata, sending customer emails, moderating comments) pauses and renders an inline Approve / Reject card inside the thread and in the central Approvals view.
- Approve every action: Requires confirmation for all tool invocations.
- Auto-run allowed tools: Executes permitted tools immediately without pausing (useful for trusted read-only digests or internal staging sites).
Click Details in any thread header to open the Bot Inspector Drawer, where you can review tool scopes and add or delete persistent bot memories and shared workspace facts (such as brand tone rules or pricing policies).
6. Universal Customer Forms Inbox
BraidPress automatically captures incoming form submissions across all major WordPress form plugins with zero extra add-ons:
- Contact Form 7
- WPForms
- Gravity Forms
- Elementor Pro Forms
- Ninja Forms
- Fluent Forms
You can also place the built-in lightweight shortcode on any WordPress page or block:
[braidpress_contact_form title="Contact Our Team"]
Open Forms in the sidebar to filter by status (All, New, Drafted, Replied), search entries, paginate results, trigger one-click Triage with Bot, or send direct replies via wp_mail().
7. SEO Audits & Metadata Compatibility
@seo-bot automatically detects your active SEO plugin and reads/writes directly to its native post meta keys:
| SEO Plugin | Detection | Meta Fields Synced |
|---|---|---|
| Yoast SEO | Automatic | _yoast_wpseo_title, _yoast_wpseo_metadesc, _yoast_wpseo_focuskw |
| Rank Math | Automatic | rank_math_title, rank_math_description, rank_math_focus_keyword |
| All in One SEO | Automatic | _aioseo_title, _aioseo_description |
| SEOPress | Automatic | _seopress_titles_title, _seopress_titles_desc, _seopress_analysis_target_kw |
| Native Fallback | When no SEO plugin active | Stores _braidpress_seo_* keys and outputs clean <meta name="description"> and document title tags in wp_head. |
8. Controlling Your Team from Telegram
Command your main bot or any specialist directly from Telegram without opening WordPress Admin. BraidPress communicates directly with https://api.telegram.org using your site's own REST webhook endpoint (zero external relay servers).
- Message
@BotFatheron Telegram, run/newbot, and copy the bot API token. - Open BraidPress > Settings > Telegram Bot and check Enable Telegram Bot Bridge.
- Paste your Bot Token, choose your Default Main Bot or Group, and enter your authorized Telegram Chat IDs or
@usernames(strictly required so unauthorized strangers cannot message your site). - Click Save Telegram Settings, then click Verify Bot and Register Webhook.
Supported Telegram Commands
| Command | Action |
|---|---|
/start or /help | Shows connected site name and command reference. |
/bots | Lists all active bots with their @handles. |
/status | Returns live WordPress post, page, form, and pending approval counts. |
/approvals | Lists pending actions with interactive Telegram inline Approve and Reject buttons. |
/use @handle | Switches the active Telegram target bot (or tag @handle inline in any message). |
9. Routines & Event Triggers
Open Routines to automate recurring work via WP-Cron (hourly, twicedaily, daily, weekly) or real-time WordPress event hooks:
form_submitted: Runs automatically whenever any customer submits a form.post_published: Triggers SEO or editorial review when a new post goes live.comment_posted: Triages incoming blog comments.woo_order_created: Alerts or analyzes new WooCommerce orders.
Click Run Now on any routine to execute immediately and inspect duration and summaries in the paginated Recent Runs table.
10. WordPress Tools Reference
| Category | Tool Names |
|---|---|
| Content & Media | wp_list_posts, wp_get_post, wp_create_post, wp_update_post, wp_list_media, wp_update_media_alt |
| SEO | seo_audit_site, seo_get_meta, seo_update_meta, seo_check_sitemap |
| Customer Forms | forms_list_entries, forms_get_entry, forms_draft_reply, forms_send_reply |
| Comments | wp_list_comments, wp_reply_comment, wp_moderate_comment |
| Site Ops & WooCommerce | wp_site_overview, wp_list_plugins, wp_list_users, wp_get_option, woo_list_products, woo_list_orders |
| Memory & Team | memory_save, memory_search, team_list_bots |
11. Security, GDPR Privacy & Clean Uninstall
- Strict Access Control: All admin REST routes require valid WordPress REST nonces and
manage_optionscapability (filterable viabraidpress_required_capability). - Encrypted Credentials: AI provider keys and Telegram bot tokens are encrypted with AES-256-CBC + HMAC-SHA256 using hex encoding (zero
base64_encode/eval/obfuscation). - Safe Options Whitelist:
wp_get_optionstrictly blocks sensitive keys such asadmin_email, salts, or plugin secrets. - GDPR Ready: Registers a Privacy Policy guide entry under Settings > Privacy and hooks into WordPress's native Export Personal Data and Erase Personal Data tools for captured customer form entries.
- Clean Uninstall: Enable Remove all BraidPress database tables and settings when plugin is uninstalled under Settings before deleting the plugin to remove all 9 custom tables, scheduled cron events, and options cleanly.
12. Developer Hooks & Filters
| Hook | Type | Description |
|---|---|---|
braidpress_register_tools | Action | Passes the ToolRegistry instance so custom plugins or themes can register domain-specific tools. |
braidpress_required_capability | Filter | Customize the required WordPress capability for workspace access (default: manage_options). |
braidpress_form_entry_created | Action | Fires after any form entry is captured with ($entry_id, $entry_data). |
add_action( 'braidpress_register_tools', function ( $registry ) {
$registry->register( array(
'name' => 'custom_crm_lookup',
'label' => 'Lookup CRM Account',
'category' => 'Integrations',
'description' => 'Read customer tier by email address.',
'is_write' => false,
'callback' => function ( $args ) {
return array( 'tier' => 'enterprise' );
},
) );
} );
13. Troubleshooting FAQ
Test Connection says HTTP 401 or 404
Verify your API key has active billing credits and confirm the provider Base URL matches the selected protocol (OpenAI-compatible endpoints should end with /v1; Anthropic endpoints use https://api.anthropic.com/v1).
Telegram webhook does not receive messages
Telegram requires a publicly reachable HTTPS domain with a valid SSL certificate. Confirm your site URL starts with https://, verify your Chat ID is listed under Allowed Telegram Chat IDs, and click Register Webhook again.
Can I use BraidPress with local models like Ollama or LM Studio?
Yes. Select Ollama (Local), LM Studio (Local), or vLLM (Self-Hosted) in Settings and point the Base URL to your local server reachable from PHP.
14. Changelog
Version 1.0.0
- Initial release of BraidPress Virtual AI Agent Team workspace for WordPress.
- Added 4 starter specialist bots, custom bot builder, multi-bot groups, and automatic
@handlehandoffs. - Added 23 preset AI providers plus unlimited custom OpenAI-compatible and Anthropic Messages endpoints with AES-256-CBC encrypted keys.
- Added direct self-hosted Telegram Bot Bridge with slash commands and inline Approve/Reject keyboards.
- Added universal form capture (CF7, WPForms, Gravity Forms, Elementor Pro, Ninja Forms, Fluent Forms, and
[braidpress_contact_form]), SEO plugin sync (Yoast, Rank Math, AIOSEO, SEOPress + native fallback), WooCommerce read tools, WP-Cron/event routines, GDPR data exporter/eraser, pagination, search, and Light/Dark themes.