Vocal Bridge SDK

Official JavaScript/TypeScript SDK for Vocal Bridge voice agents. Connect your users to AI voice agents with a few lines of code.

Packages

Package	Description	npm
@vocalbridgeai/sdk	Core SDK (vanilla JS/TS)
@vocalbridgeai/react	React hooks & provider

Quick Start

Vanilla JavaScript

npm install @vocalbridgeai/sdk

import { VocalBridge } from '@vocalbridgeai/sdk';

const vb = new VocalBridge({
  auth: { tokenUrl: '/api/voice-token' },
});

vb.on('transcript', ({ role, text }) => {
  console.log(`[${role}] ${text}`);
});

await vb.connect();

React

npm install @vocalbridgeai/sdk @vocalbridgeai/react

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

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

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

  return (
    <div>
      <button onClick={state === 'disconnected' ? connect : disconnect}>
        {state === 'disconnected' ? 'Start' : 'End'}
      </button>
      {transcript.map((e, i) => <p key={i}>{e.role}: {e.text}</p>)}
    </div>
  );
}

Authentication

Three auth strategies supported:

// 1. API Key (prototyping only - exposes key to browser)
{ auth: { apiKey: 'vb_xxx' } }

// 2. Token URL (production - your backend proxies the request)
{ auth: { tokenUrl: '/api/voice-token' } }

// 3. Custom provider (maximum flexibility)
{ auth: { tokenProvider: async () => ({ url, token, room_name, ... }) } }

Backend token endpoint (recommended for production):

// Node.js/Express
app.post('/api/voice-token', async (req, res) => {
  const response = await fetch('https://vocalbridgeai.com/api/v1/token', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.VOCAL_BRIDGE_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ participant_name: req.user?.name || 'User' }),
  });
  res.json(await response.json());
});

Client Actions

Send and receive custom actions between your app and the voice agent:

// Receive actions from agent
vb.on('agentAction', ({ action, payload }) => {
  if (action === 'show_product') displayProduct(payload);
});

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

React:

const { sendAction, onAction } = useAgentActions();

useEffect(() => {
  return onAction('show_product', (payload) => setProduct(payload));
}, [onAction]);

AI Agent Integration

Connect your existing AI agent to the Vocal Bridge voice agent:

// Automatic mode - SDK handles the response flow
vb.onAIAgentQuery(async (query) => {
  return await myAgent.ask(query); // Return value auto-sent back
});

React:

useAIAgent({
  onQuery: async (query) => await myAgent.ask(query),
});

API Reference

See individual package READMEs:

• @vocalbridgeai/sdk API
• @vocalbridgeai/react API

Examples

• Vanilla JS - Basic HTML + JS integration
• React Basic - React app with transcript and actions

Development

npm install
npm run build
npm test

License

Apache-2.0