D Diagent docs
/

WordPress & WooCommerce

Install & connect

This page walks through installing the Pitchbar WordPress plugin on a fresh WP site, connecting it to your Pitchbar workspace, and verifying that the widget actually loads on the front end.

Total time: about 3 minutes on a vanilla WordPress + WooCommerce install. The plugin is fully self-contained — no composer install, no build step, no external CDN dependency.

Prerequisites

  • A Pitchbar workspace (sign up at your workspace URL, or ask your platform admin to create one).
  • WordPress 6.4 or newer running on PHP 7.4 or newer.
  • Workspace admin or owner role in Pitchbar (the API tokens page is admin-gated; viewer/editor are blocked).
  • The pitchbar-{version}.zip archive — see "Where do I get the zip?" below.

Where do I get the zip?

Three paths, pick whichever matches your setup:

  1. From your Pitchbar workspace — a super_admin opens /admin/integrations/wordpress, clicks Build latest, then Download. The archive lives at storage/app/private/wp-plugin-builds/pitchbar-{version}.zip server-side.
  2. From the CLI on the Pitchbar host: php artisan pitchbar:build-wp-plugin writes the zip and prints its path.
  3. From an existing tenant install — if your platform owner already distributed the archive to you, that's the zip; no need to rebuild.

Step 1. Upload & activate

  1. In WordPress admin, open Plugins → Add New → Upload Plugin.
  2. Pick pitchbar-{version}.zip and click Install Now.
  3. Click Activate Plugin.
  4. A blue admin notice appears at the top of every admin page: "Pitchbar is installed but not configured yet. Open Settings → Pitchbar to connect."

The plugin registers itself with no front-end behaviour until step 3 — until you save a workspace URL + token, the widget never renders.

Step 2. Create a workspace API token in Pitchbar

  1. Sign into your Pitchbar workspace.
  2. Open Settings → API tokens.
  3. Click Create token. Name it after the WordPress site (e.g. shop.example.com).
  4. Grant the wp:integration ability.
  5. Pitchbar displays the plaintext token exactly once. Format: pbar_ + 48 alphanumeric characters. Copy it now — only the SHA-256 hash is persisted, so if you lose the plaintext you have to revoke and reissue.

The same screen also generates a shopper_signing_secret on token create, which the plugin picks up automatically on its first handshake (you never have to paste it). See the REST API reference for what the secret is used for.

Step 3. Connect WordPress to Pitchbar

  1. In WordPress admin, open Settings → Pitchbar.
  2. Paste your Pitchbar workspace base URL (e.g. https://app.pitchbar.example) into Pitchbar base URL. Trailing slashes are trimmed automatically.
  3. Paste the API token you just created into API token.
  4. Click Test connection. The button disables, the status line shows "Testing connection…", and within a couple of seconds you either get a green confirmation or a red error.
  5. On success: the empty agent dropdown swaps for a populated list of every agent in your workspace, and the workspace name is shown underneath ("Connected to workspace: Acme Storefront"). The plugin also captured the shopper signing secret silently and stashed it in wp_options.
  6. Pick which agent should run on this site. Each agent gets its own dropdown entry with its site type appended (e.g. Storefront bot (ecommerce)).
  7. Confirm the Enabled toggle is checked under "Widget display".
  8. Tick the Post types you want the widget to load on. Defaults: post + page. Custom post types and (when WooCommerce is active) product appear as additional checkboxes.
  9. Click Save Changes.

Step 4. Verify the front-end embed

  1. Open a public page on your WordPress site (homepage, blog post, product page — anything matching the post types you enabled).
  2. The Pitchbar bar appears in the footer area. By default it animates in from the bottom edge.
  3. Click the bar to open the chat panel. Type a question — the agent streams a response.

If the widget never appears, check Troubleshooting — the most common cause is a theme that omits wp_footer(), or a caching plugin that's serving a stale HTML snapshot.

What's saved server-side

Two pieces live in WordPress' wp_options table under the key pitchbar_settings (plaintext, as WordPress options aren't encrypted at rest):

  • API token — full plaintext value. Trust level: same as a wp-config.php secret. Revoke from your Pitchbar workspace anytime to instantly invalidate it.
  • shopper_signing_secret — the per-token plaintext secret Pitchbar uses to HMAC-sign callbacks to your WP site (order lookup, coupon apply, lead push). Captured automatically on the first Test connection.
  • Selected agent, workspace ID, workspace name, enabled post types, enabled flag — small config blob.

Uninstalling the plugin via the WordPress dashboard deletes both options. Deactivating only leaves them in place so re-activating doesn't lose the connection.

What happens on (re-)activation

If the plugin is already configured at activation time (a deactivate → activate cycle on an existing install), a one-off full sync is scheduled 30 seconds out via wp_schedule_single_event on the pitchbar_run_full_sync_event hook. When WooCommerce is active, a second event for products is scheduled 60 seconds out (so posts finish first). This means uploading a new plugin version doesn't strand stale content; the next wp-cron tick refreshes the agent's knowledge base.

Deactivating the plugin clears both scheduled hooks via wp_clear_scheduled_hook so nothing fires after the plugin is off.

Where the plugin shows up in WP admin

  • Settings → Pitchbar — the single configuration screen for everything (connection, agent picker, post-type toggles, sync buttons).
  • Plugins admin notice — the soft blue banner while the plugin is unconfigured, or while a chunked sync is finishing in the background.
  • Users admin — pushed leads land as WP users (subscriber role on non-Woo, WC customer on Woo) with pitchbar_lead_id + pitchbar_conversation_id in user meta.

Permissions

The Settings page and all AJAX actions require the manage_options capability — the same one WordPress uses for "General Settings". Editors, authors, and contributors cannot reach it. Multisite super_admins also pass the check.

REST endpoints (/wp-json/pitchbar/v1/*) are public on purpose (permission_callback => __return_true) and instead authenticate by HMAC signature on every request. See REST API reference.

Uninstalling cleanly

  1. Open Plugins in the WP admin.
  2. Click Deactivate next to Pitchbar. Scheduled sync events are cleared.
  3. Click Delete. WordPress invokes uninstall.php which removes the pitchbar_settings option and the pitchbar_activation_flag flag.
  4. Revoke the WordPress API token in /settings/api-tokens on Pitchbar so the plaintext that lived in wp_options is dead immediately.

Knowledge that the plugin already pushed to Pitchbar stays in the knowledge base — uninstalling the plugin doesn't delete the agent's Sources or Documents. Remove those from the Pitchbar admin if you want a full teardown.