# Voice button

> Add a floating or inline button that starts a voice call with your agent.

Source: https://voxio.in/docs/voice-button · voxioagent 2.0.0 · Index: https://voxio.in/docs/llms.txt

The voice button is a web component, `<voxio-voice-button>`. It opens the microphone, connects to your flow and shows the state of the call.

## Add the button

Mount the button with your flow key:

HTML:

```html
<script src="https://cdn.jsdelivr.net/npm/voxioagent@2.0.0/dist/voxio.js"
        data-flow-key="YOUR_FLOW_KEY" data-label="Talk to us" defer></script>
```

JavaScript:

```js
import { mountVoiceButton } from "voxioagent/widget";

const button = mountVoiceButton({ flowKey: "YOUR_FLOW_KEY", label: "Talk to us" });
```

React:

```jsx
import { VoxioVoiceButton } from "voxioagent/react";

<VoxioVoiceButton flowKey="YOUR_FLOW_KEY" label="Talk to us" />
```

Replace `YOUR_FLOW_KEY` with your flow key, from the flow's **Overview** in the dashboard.

## Options

The button takes every [session option](https://voxio.in/docs/sessions.md#options) (such as `flowKey`, `environment` and `customs`), every [look and placement option](https://voxio.in/docs/customising.md), and these:

- `label` (string | false): The text next to the icon. `false` shows the icon alone.
- `tooltip` (string): Shown on hover.
- `shape` ("circle" | "rounded" | "square" | "pill"): The button’s shape.
- `size` (number | string): The button’s size. Numbers are pixels.
- `mobileSize` (number | string): The size on screens narrower than 640px.
- `hideLabelOnMobile` (boolean): Shows the icon alone on narrow screens.
- `motion` ({ pulse?, glow? }): An idle pulse and a glow while the agent speaks. Both switch off under `prefers-reduced-motion`.
- `showMute` (boolean): Shows a mute button beside it during a call.
- `looks` (Looks): What the button shows in each state. See [Change the look per state](#change-the-look-per-state).

## Change the look per state

The button has a look for each state: `idle`, `connecting`, `listening`, `speaking`, `muted`, `error` and `ended`. A look is an image or GIF URL, an inline SVG, a built-in animation or your own renderer.

Set a look for the states you want to change:

```js
mountVoiceButton({
  flowKey: "YOUR_FLOW_KEY",
  looks: {
    idle: "https://example.com/idle.png",
    connecting: { builtIn: "orb" },
    speaking: { builtIn: "wave" },     // built in: "orb", "wave", "mic"
    error: { svg: "<svg …>…</svg>" },
  },
});
```

States you leave out keep the default look.

## Control the button

The element returned by `mountVoiceButton` has these methods:

| Method | What it does |
| --- | --- |
| `start()` | Opens the microphone and connects. If you set consent, it asks first. |
| `stop()` | Ends the call. |
| `toggle()` | Starts or stops the call. |
| `mute(muted?)` | Mutes or unmutes the microphone. |
| `open()` and `close()` | Shows or hides the widget. Closing doesn’t end a call. |
| `attach(element)` | Makes another element start and stop the call when clicked. Returns a function that detaches it. |
| `destroy()` | Ends the call, releases the microphone and removes the widget. |

## Use your own launcher

To start calls from a button that's already on your page, hide the widget and attach it:

```js
const button = mountVoiceButton({ flowKey: "YOUR_FLOW_KEY", hidden: true });
button.attach(document.querySelector("#help-cta"));
```

Clicking `#help-cta` now starts and ends the call.

## Next steps

- [Customising widgets](https://voxio.in/docs/customising.md): match the button to your brand.
- [Web actions](https://voxio.in/docs/web-actions.md): let the agent fill in forms on your page while it talks.