> ## 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.

# Web widget

> Embed a voice agent on any website or in a mobile app - visitors can talk to it straight from the browser.

### How to embed an agent

<Note>
  On WordPress you need neither this dialog nor a snippet in your theme:
  the [Brosbots plugin for WordPress](/en/integrations/cms/wordpress) connects the
  site in one click and sets the allowed domain for you.
</Note>

Go to your agent and enable embedding on an external site.

Step 1: Open the agent and click **Widget** in the editor header - the
**Deploy Workflow** dialog opens.

Step 2: Turn on **Enable Embedding**.

Step 3: Add the domain the widget will run on under **Allowed Domains**, for example
`example.com` (the `www.` variant is matched automatically; `*.example.com` covers
subdomains). A request from a domain that is not on the list is rejected. A key with no
domain at all answers only inside the panel (the editor preview), so without an entry the
widget on your site will not start. The panel itself is always allowed, even when the list
is not empty, so the editor preview keeps working whatever domains you add.

If you gave your company website in the onboarding wizard, the key created in its
**Widget** step already lists that site's domain (e.g. `www.bistrolipowa.pl` from
`https://www.bistrolipowa.pl/menu`), so the pasted snippet works right away. Without a
website, add the domain here.

<Note>
  Keys created before this rule still answer on any site for now. When such a key is used
  on a site that is not listed, this dialog shows a banner with an **Add \<domain>**
  button carrying the detected address. Click it and save.
</Note>

### Session limits

So that a key cannot be used to burn somebody else's minutes, every key has limits:

* at most 100 sessions a day,
* at most 10 sessions from one browser a day,
* at most 10 sessions from one IP address a day and 4 within 10 minutes (the address the
  connection actually came from counts, so a script cannot get around it by changing the
  browser id),
* at most 3 conversations at once,
* one session lasts up to 5 minutes.

A normal visitor has one or two conversations and never notices the limits. Whoever hits
one sees a message in the widget's language (for example "Too many attempts in a short
time. Please try again in a few minutes.") and can try later. Widget minutes come out of
the plan's package exactly like phone calls.

### Daily minute budget

In the **Deploy Workflow** dialog (the **Widget** button in the editor) you set the **Daily minute budget**: how many minutes
of conversation the widget may use in a day. The default is 120 minutes, and it can be set
from 5 to 500. The budget cannot be turned off: the ceiling is what the daily session
limit could use anyway.

* What counts is the minutes this key's sessions actually talked today; conversations
  still running count from the moment they started.
* The day is counted in UTC, so in Poland it ends at 1:00 (winter) or 2:00 (summer).
* At 80% and 100% of the budget you get a notification in the panel (the bell) and an
  e-mail, each at most once a day. Turn them off in **Account > Notifications > Website widget**.
* Once the budget is spent, new conversations do not start until the day ends. Visitors
  see a message that conversations with the assistant are unavailable today. A
  conversation already running is not cut off. Raising the budget takes effect at once.

Below the field you can see how many minutes the widget used today.

Step 4: Configure the widget - floating or inline.

Step 5: Paste the code into your website and test the agent.

### Agent identity on the call panel

Under **Agent identity** you set what a visitor sees before the first message:

* **Display name** - defaults to the agent's name.
* **Avatar URL** - defaults to the agent's avatar, then the widget logo, then the agent's
  avatar emoji; with none of those the panel shows the agent's initials.
* **Greeting** - the text shown on the resting panel. The spoken greeting stays in the agent's configuration.

### Widget language

The widget's own text - "Ready", "Call ended", the panel greeting, the
microphone messages - is in Polish or English. The language is picked in this
order:

1. the `lang` parameter on the embed script URL (`...brosbots-widget.js?token=...&lang=pl`),
2. **the language the agent speaks** - taken from its configuration, so usually
   there is nothing to set,
3. your page's own `lang` attribute,
4. English.

A multilingual agent gets English chrome rather than having a language guessed
for it. The panel greeting can be overridden with your own text in the
**Greeting** field.

### Floating vs inline

In **floating** mode the launcher button opens the conversation in a modal.

In **inline** mode the whole conversation - avatar, transcript and controls - renders
inside your `<div id="brosbots-inline-container">`. Nothing is ever placed on top of
your page.

The panel takes the height of the container you give it and the transcript scrolls
inside. If the container has no height of its own, the panel sizes itself between
320px and 640px (at most 80% of the viewport height).

### "Powered by BrosBots" badge

The widget shows a small BrosBots link at the bottom of the panel, linking to
brosbots.com.

Whether it appears is decided by your plan, on the server, when the widget loads
its configuration:

* **Free** - always shown. The switch in the embed dialog is locked, and the
  widget refuses to start a call while the badge is hidden or removed.
* **Paid plans** - the switch is on by default and you can turn it off.

The embed dialog also reports how many sessions ran with the badge hidden, so an
account that removes it can be followed up on.


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