@vocalbridgeai/react

React hooks and provider for Vocal Bridge voice agents.

Installation

npm install @vocalbridgeai/sdk @vocalbridgeai/react

Quick Start

import { VocalBridgeProvider, useVocalBridge, useTranscript } from '@vocalbridgeai/react';
import { ConnectionState } from '@vocalbridgeai/sdk';

function App() {
  return (
    <VocalBridgeProvider options={{ auth: { tokenUrl: '/api/voice-token' } }}>
      <VoiceChat />
    </VocalBridgeProvider>
  );
}

function VoiceChat() {
  const { state, connect, disconnect, isMicrophoneEnabled, toggleMicrophone } = useVocalBridge();
  const { transcript } = useTranscript();

  return (
    <div>
      <p>Status: {state}</p>

      {state === ConnectionState.Disconnected ? (
        <button onClick={connect}>Start</button>
      ) : (
        <>
          <button onClick={disconnect}>End</button>
          <button onClick={toggleMicrophone}>
            {isMicrophoneEnabled ? 'Mute' : 'Unmute'}
          </button>
        </>
      )}

      {transcript.map((entry, i) => (
        <p key={i}>
          <strong>{entry.role}:</strong> {entry.text}
        </p>
      ))}
    </div>
  );
}

API

<VocalBridgeProvider>

Wraps your app and creates the VocalBridge instance.

<VocalBridgeProvider options={{ auth: { tokenUrl: '/api/voice-token' } }}>
  {children}
</VocalBridgeProvider>

useVocalBridge()

Primary hook for connection lifecycle.

const {
  state,              // ConnectionState
  connect,            // () => Promise<void>
  disconnect,         // () => Promise<void>
  isMicrophoneEnabled, // boolean
  toggleMicrophone,    // () => Promise<void>
  setMicrophoneEnabled, // (enabled: boolean) => Promise<void>
  sendAction,          // (action, payload?) => Promise<void>
  agentMode,           // string | undefined
  error,               // VocalBridgeError | null
  client,              // VocalBridge instance
} = useVocalBridge();

useTranscript()

Live conversation transcript.

const { transcript, clear } = useTranscript();
// transcript: Array<{ role: 'user' | 'agent', text: string, timestamp: number }>

useAgentActions()

Bidirectional custom actions.

const { lastAction, sendAction, onAction } = useAgentActions();

// Per-action handler with auto-cleanup
useEffect(() => {
  return onAction('show_product', (payload) => {
    setProduct(payload);
  });
}, [onAction]);

// Send action to agent
sendAction('user_clicked_buy', { productId: '123' });

useAIAgent()

AI Agent integration with automatic or manual response flow.

Automatic (callback):

useAIAgent({
  onQuery: async (query) => {
    return await myAgent.ask(query); // auto-responds
  },
});

Manual:

const { pendingQuery, respond } = useAIAgent();

useEffect(() => {
  if (pendingQuery) {
    myAgent.ask(pendingQuery.query).then(answer => {
      respond(pendingQuery.turnId, answer);
    });
  }
}, [pendingQuery]);

License

Apache-2.0