Add a voice AI agent to a React app

Voxera connects your React application to a managed voice pipeline. The useVoxera hook manages the browser client and exposes call state, transcripts and actions. This walkthrough adds a call button to an existing React app using a published agent configuration.

What you need

• An existing React 18 or 19 application. In Next.js, this component must be a client component.
• A browser with microphone and WebRTC support, served over HTTPS or localhost.
• A Voxera account, a published agent, and a publishable app key in the same workspace.

1. Publish an agent and create a key

Open the Voxera dashboard at app.voxera-voice.com. Create an agent, set its prompt and voice, and publish its configuration. Copy its agent ID. Create a publishable app key and set its allowed origins to the app origins you will use, including your localhost port for development. Keep the agent and key in the same workspace.

The example uses a publishable key beginning with vx_pk_. Never paste a secret key beginning with vx_sk_ into React code, a public environment variable or a browser bundle. Secret keys belong on your backend.

2. Install the React SDK

npm install @voxera/sdk-react

The React package includes the browser SDK as a dependency. The hook creates and disposes the client, subscribes to events, and merges streamed message chunks into replies.

3. Add the voice component

Save this as VoiceButton.tsx and replace both placeholder values with your publishable key and agent ID. The call starts after a user click, which also gives the browser an opportunity to request microphone access.

"use client";

import { useVoxera } from "@voxera/sdk-react";

export function VoiceButton() {
  const call = useVoxera();

  return (
    <section aria-label="Voice assistant">
      <button
        type="button"
        disabled={call.isBusy}
        onClick={() => {
          if (call.isActive) {
            void call.leave();
          } else {
            void call.start({
              appKey: "vx_pk_live_...", // Publishable key, never vx_sk_*.
              serverUrl: "https://rtc.voxera-voice.com",
              agentId: "your-agent-id",
            });
          }
        }}
      >
        {call.isBusy ? "Connecting…" : call.isActive ? "End call" : "Talk to the agent"}
      </button>
      <p role="status">{call.connectionStatus}</p>
      {call.error ? <p role="alert">{call.error}</p> : null}
      {call.autoplayBlocked ? (
        <button type="button" onClick={() => void call.resumeAudio()}>
          Tap to hear the agent
        </button>
      ) : null}
      {call.messages.map((message) => (
        <p key={message.id}><strong>{message.role}:</strong> {message.content}</p>
      ))}
    </section>
  );
}

4. Render it in your app

import { VoiceButton } from "./VoiceButton";

export default function App() {
  return <VoiceButton />;
}

In Next.js App Router, import the component into your page instead. Its use client directive keeps the hook in the browser. In either setup, start a call, allow microphone access, ask a question, and check that you hear a reply and see its text. End the call when finished.

5. Check the failure states

• Microphone denied: enable microphone permission for your app's origin and retry. An ordinary HTTP domain cannot request microphone access.
• Authorization rejected: check the key type, allowed origin including its port, workspace, and published agent ID.
• Connected but silent: use Tap to hear the agent if it appears, and check your device's output and volume.
• Session refused: check the workspace's remaining minutes and concurrent-session allowance.
• Test interruption: ask for a longer answer, then speak again while it is playing. Observe the actual audio and transcript behavior on your target browser.

Change the agent without changing the component

The published agent configuration supplies its prompt, voice and tools. Update and publish that configuration in the dashboard, then start a new session to try it. Use the documentation for backend-issued session tokens and tool calling when your integration needs them.