H Habla docs
/

WordPress & WooCommerce

Install & connect

This page walks through installing the Habla WordPress plugin on a fresh WP site, connecting it to your Habla 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.

The WordPress plugin is optional. You can deploy the chat widget on any site — including WordPress — with the manual HTML embed snippet from an agent's Settings page (see Embed the widget). That path loads the widget only; it does not replace WordPress content sync, WooCommerce order lookup, coupon apply, lead mirroring, or the other features documented in the WordPress integration section.

Prerequisites

  • A Habla 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 Habla (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?

Workspace owners and admins should start on Integrations in your Habla workspace. When your platform operator has configured the plugin download URL, the WordPress card shows a Download plugin button for the current release (for example pitchbar-2.0.6.zip).

If the download button is missing, the plugin is not currently published to your workspace — contact your workspace administrator. Editors and viewers cannot download or configure the plugin.

Platform operators who self-host Habla can also produce the archive without ssh:

  1. Platform super_admin build — a super_admin opens /admin/integrations/wordpress, clicks Build latest, then Download. The archive is written to storage/app/private/wp-plugin-builds/pitchbar-{version}.zip server-side. This endpoint is not available to workspace owners, admins, editors, or viewers.
  2. From the CLI on the Habla host: php artisan pitchbar:build-wp-plugin writes the zip and prints its path (operator / self-host use).

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: "Habla is installed but not configured yet. Open Settings → Habla 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 Habla

  1. Sign into your Habla 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. Habla 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 Habla

  1. In WordPress admin, open Settings → Habla.
  2. Paste your Habla workspace base URL (e.g. https://app.pitchbar.example) into Habla 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 Habla 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 Habla workspace anytime to instantly invalidate it.
  • shopper_signing_secret — the per-token plaintext secret Habla 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 → Habla — 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

On WordPress

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.

On Habla

  • API tokens (/settings/api-tokens) — workspace owner or admin only. Editors and viewers cannot create or revoke integration tokens. Create tokens with the wp:integration ability.
  • Integrations page (/app/integrations) — workspace owner or admin only. Shows connected WordPress sites and, when configured, an optional tenant-facing plugin download link.
  • Plugin zip build/download (/admin/integrations/wordpress) — platform super_admin only. Workspace members cannot generate or download a zip from this surface.

Uninstalling cleanly

  1. Open Plugins in the WP admin.
  2. Click Deactivate next to Habla. 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 Habla so the plaintext that lived in wp_options is dead immediately.

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