> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress

> The plugin that puts your agent on a WordPress site with no theme editing and no code to paste.

The **Brosbots Voice Agent** plugin does what the [web
widget](/en/features/web-widget) does, without pasting anything into a theme.
One click, sign in to Brosbots, pick an agent, and you are back on your site with
the widget live.

The agent, its prompt, voice and knowledge base stay in the Brosbots panel. The
plugin duplicates none of it: it only decides where the widget shows and what the
agent knows about the visitor.

## Installation

<Steps>
  <Step title="Download the plugin">
    In the Brosbots panel: **Integrations** → the **WordPress** tile →
    **Download the plugin (.zip)**.
  </Step>

  <Step title="Install it">
    In WordPress: **Plugins → Add New → Upload Plugin**, pick the file you
    downloaded and activate it.
  </Step>

  <Step title="Open the settings">
    **Settings → Brosbots**.
  </Step>

  <Step title="Connect the site">
    Click **Connect to Brosbots**. You are sent to the panel to pick the agent
    that should answer here. No account yet? You can create one in the same step.
  </Step>

  <Step title="Authorize">
    **Authorize** brings you back to the site with the connection saved. The
    widget is live.
  </Step>
</Steps>

Nothing is installed before you authorize it, and the token only ever travels
back to an address on the same domain the connection started from.

## Requirements

* WordPress 6.0 or newer, PHP 7.4 or newer.
* The site must be served over **https**. A browser grants no microphone access
  otherwise, so an insecure site is refused during the connection.
* A Brosbots account with at least one agent.

## Where the widget shows

Under **Settings → Brosbots** you pick one mode:

| Mode | What it does |
| - | - |
| Every page | The widget across the whole site |
| Only selected pages | The widget on the chosen pages only |
| Every page except selected | The inverse of the above |

On top of that:

* **Cart and checkout** (WooCommerce) are excluded by default. A floating widget
  over a payment form costs more orders than it wins.
* **wp-admin** never loads the widget.
* The `[brosbots]` shortcode renders the agent inside a page and ignores the
  rules above. It needs the agent's embed mode set to **inline** in the Brosbots
  panel.

## What the agent knows about the visitor

This is the difference between the plugin and a plain embed snippet: the agent
opens the conversation already knowing what the visitor is looking at, instead of
asking.

| Group | What reaches the agent |
| - | - |
| Page | Title and address of the page being read, site name |
| Visitor | Name and e-mail, **only when signed in** |
| WooCommerce | The product on screen with price and availability, cart item count and total |

Each group is its own checkbox. An anonymous visitor sends nothing about
themselves.

<Note>
  Nothing reaches the agent until the visitor starts a conversation. Loading the
  page only requests the widget's configuration.
</Note>

## Extending the plugin

The plugin exposes four filters:

| Filter | Use |
| - | - |
| `brosbots_context_variables` | Add your own context, an order or booking number for instance |
| `brosbots_should_render` | Last word on whether the widget loads on this request |
| `brosbots_app_url` | Point the site at a self-hosted Brosbots |
| `brosbots_api_url` | The same, for the API host |

```php theme={null}
add_filter( 'brosbots_context_variables', function ( $context ) {
    $context['order_number'] = get_query_var( 'order' );
    return $context;
} );
```

Context variables are used in the agent's prompt like any other, see [Template
variables](/en/voice-agent/template-variables).

## Switching agent and disconnecting

* **Switch agent**: the same button as the first connection. Pick another agent
  and the site gets the new embed.
* **Disconnect this site**: the plugin forgets the token and the widget stops
  loading. The agent, its recordings and transcripts are untouched in Brosbots.
* **Uninstalling** the plugin removes its settings from the WordPress database.
  The token itself is revoked in the agent's embed settings.

## Security

An embed token is public by nature: it sits in the page source of every page the
widget loads on. What protects it is the domain allow-list, which the plugin sets
during the connection. A token lifted from your site does not work on anyone
else's.

The return from the panel is only accepted when it matches a one-time code the
plugin generated before leaving, and the token is verified against the API on top
of that. A hand-crafted return address cannot park someone else's agent on your
site.

## Troubleshooting

**The widget does not appear.** Check that **Show the agent on the site** is
ticked, that the page matches the display rules, and that the site is served over
https.

**"That connection did not start here".** The one-time code expired (it lasts ten
minutes) or the return happened in a different browser. Click **Connect to
Brosbots** again.

**"Brosbots did not recognise that token".** The embed was revoked in the panel
in the meantime. Connect the site again.

**The agent cannot see the cart.** WooCommerce context is its own checkbox and
needs WooCommerce active.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.