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

# Widget integration

> Add the Orato voice and chat widget to any website with one script tag, or initialize it programmatically in a single-page app.

The Orato widget adds a floating button to your website. Visitors can start a voice call with your assistant or send a text message.

## Prerequisites

> [!TIP]
>
> An assistant with the **Web Widget** role. Style it on the [Branding](https://docs.tryorato.com/assistants/branding.md) tab.

> [!TIP]
>
> A **public API key** (`pk_live_...`) with your website domain whitelisted. See [API keys](https://docs.tryorato.com/developer/api-keys.md).

> [!TIP]
>
> Your **Assistant ID**.

## Add the script

Paste this snippet into the `<head>` or `<body>` of your HTML:

```html theme={null}
<!-- Orato Voice Widget -->
<script
  src="https://app.tryorato.com/widget.js"
  data-key="pk_live_YOUR_PUBLIC_KEY"
  data-assistant="YOUR_ASSISTANT_ID"
  defer
></script>
```

Replace `pk_live_YOUR_PUBLIC_KEY` and `YOUR_ASSISTANT_ID` with your values.

| Attribute | Description |
| - | - |
| `src` | The Orato widget script |
| `data-key` | Your public API key |
| `data-assistant` | The ID of the Web Widget assistant to load |
| `defer` | Loads the script without blocking your page |

## Initialize programmatically

In React, Next.js, Vue, or another single-page app, you can initialize the widget with the global `Orato` object once the script has loaded:

```javascript theme={null}
// Initialize manually
if (window.Orato) {
  window.Orato.init({
    apiKey: 'pk_live_YOUR_PUBLIC_KEY',
    assistantId: 'YOUR_ASSISTANT_ID'
  });
}
```

## Platform tips

> **WordPress**
>
> Add the script with a header/footer code plugin, or in your theme's `footer.php` before `</body>`.

> **Webflow, Framer, Wix, Squarespace**
>
> Paste the snippet into the site-wide custom code setting (head or footer) and publish.

> **Shopify**
>
> Edit your theme code and add the snippet to `theme.liquid` before `</body>`.

> **Next.js**
>
> Use the `next/script` component with `strategy="afterInteractive"` and the same `src` and `data-*` attributes, or call `window.Orato.init` in a client component.

## Verify the installation

Reload your site. The launcher button appears in the corner you chose on the Branding tab (bottom right by default). Click it and start a call or chat.

## Troubleshooting

> **The widget doesn't appear**
>
> * Check the browser console for errors.
> * Make sure your domain is whitelisted on the public key in **Developer → API Keys**. Add `www.` and non-`www` versions if you use both.
> * Confirm `data-key` starts with `pk_live_`. Never use a secret key in the browser.

> **The wrong assistant answers**
>
> Check that `data-assistant` matches the ID of your Web Widget assistant.

> **The microphone doesn't work**
>
> The visitor must allow microphone access, and your site must be served over HTTPS.

> [!TIP]
>
> The same instructions are available in the app under **Developer → Developer Docs**.


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