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

# Put your agent on your website

> Add a chat and voice bubble to your site with one script tag. Visitors talk or write to the published version of your Builder agent.

The **web widget** is a bubble in the corner of your website. Visitors click it and can **write** to your agent or **talk** to it from the browser, with the same agent that answers your calls and your WhatsApp.

<Info>
  This guide is for agents made in the **Builder**. The widget always uses the **published** version of the agent, never the draft you are editing.
</Info>

## What you need

1. A **published** agent. To offer voice, the agent needs its voice and transcription configured, the same as for phone calls.
2. A **payment method** saved and **credits** in your account.
3. Access to your website's code, or to the place where your site builder lets you paste a script.

## Set up the widget

<Steps>
  <Step title="Open the agent in the Builder">
    From **Agents**, open the agent and go to the **Channels** tab. Click **Configure** on the **Web widget** card.
  </Step>

  <Step title="Choose where it can be shown">
    Under **Allowed Domains**, write your site's domain without `https://`, one per line: `yourdomain.com`. Use `*.yourdomain.com` to allow all of its subdomains; it does not include `yourdomain.com` itself, so write both if you want both. `localhost:3000` works for testing on your computer.
  </Step>

  <Step title="Choose what visitors can do">
    Turn **Type** (text chat) and **Talk** (a call from the browser) on or off, then turn on **Show the widget** and click **Save changes**.
  </Step>

  <Step title="Paste the code">
    Copy the code under **Code for your website** and paste it before `</body>` on every page where you want the bubble.
  </Step>
</Steps>

The code looks like this:

```html theme={null}
<script src="https://app.ryvo.so/widget.js" data-ryvo-widget="ryvo_pk_..." async></script>
```

Two optional attributes:

| Attribute | Values | What it does |
| - | - | - |
| `data-idioma` | `es`, `en` | The language of the widget. By default it follows the visitor's browser. |
| `data-posicion` | `izquierda` | Puts the bubble on the left. By default it goes on the right. |

## How it is protected

The code carries a **publishable key** (`ryvo_pk_...`). It is public on purpose: anyone who opens your site can see it, the same way they see the rest of your code. What stops someone from using your agent from another site:

* **Allowed domains.** The widget only opens inside the domains you wrote. The visitor's browser enforces this, so another site that copies your code gets an empty frame.
* **A human check.** Each conversation and each call starts with an invisible check that tells a person from a bot.
* **Rate limits** per visitor, per agent and per account.
* **Your account's own limits.** Balance, simultaneous calls of your plan and the rest of the checks of any conversation still apply.

If your key ends up somewhere it should not, click **Rotate key** and paste the new code. The old code stops opening new conversations right away. To stop everything at once, turn off **Show the widget**.

## What it costs

Each widget conversation is billed **like a web conversation**: text per message and voice per minute, at your plan's rate. Conversations show up in your history with the **Widget** channel, next to the rest of your agent's conversations.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bubble shows up but the panel is blank">
    The domain of the page is not in **Allowed Domains**. Check that you wrote it exactly as it appears in the address bar, without `https://` and without a path. `www.yourdomain.com` and `yourdomain.com` are different domains.
  </Accordion>

  <Accordion title="The widget says the assistant is not available">
    The agent is unpublished or paused, the widget is off, or your account ran out of credits. Check the **Web widget** card in the **Channels** tab and your balance.
  </Accordion>

  <Accordion title="Voice does not start">
    The visitor has to allow the microphone. If the **Talk** mode does not appear, the agent does not have voice and transcription configured in its published version.
  </Accordion>
</AccordionGroup>