React

voxioagent/react works with React 18 and later.

#Use the components

Each widget is a component. Its props are the widget's options, plus className, style, id and three event props:

1import { VoxioVoiceButton } from "voxioagent/react";
2
3<VoxioVoiceButton
4  flowKey="YOUR_FLOW_KEY"
5  label="Talk to us"
6  onStateChange={(state, muted) => {}}
7  onError={(error) => console.warn(error.code)}
8  onEnded={({ reason, seconds, sessionId }) => {}}
9  elementRef={(el) => el?.attach(document.querySelector("#cta"))}
10/>

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

elementRef gives you the underlying element, for methods such as attach() and open(). The other components are VoxioAvatar and VoxioChat.

#Build your own interface

The useVoxioSession hook gives you a session tied to the component's lifetime. This component shows the state, a level meter and the controls:

1import { useVoxioSession } from "voxioagent/react";
2
3export function Call() {
4  const v = useVoxioSession({ flowKey: "YOUR_FLOW_KEY" });
5
6  return (
7    <div>
8      <p>{v.state}</p>
9      <meter value={v.level.agent} />
10      {v.error && <p>{v.error.code}</p>}
11      <button onClick={v.start} disabled={!v.session}>Start</button>
12      <button onClick={() => v.mute(!v.muted)}>{v.muted ? "Unmute" : "Mute"}</button>
13      <button onClick={v.stop}>End</button>
14    </div>
15  );
16}

After you click Start, the state moves to connecting, then listening, and the meter moves when the agent speaks. The hook returns:

#Render on the client

Sessions use browser APIs. With Next.js, Remix or TanStack Start, render these components on the client only, for example with React.lazy or a client-only boundary.

#Next steps

• Headless sessions: see every session option and event.
• Errors: handle each error code.