Vocal Bridge

Developer Documentation

Add voice to your app in minutes

Production-ready voice agents with sub-second latency, reliable tool calling, and bidirectional app communication. No infrastructure to manage.

Get Started Free Full Developer Guide

Sub-Second Latency

Real-time voice over WebRTC with optimized STT/TTS pipelines.

Client Actions

Bidirectional: agent drives your UI, app sends events back.

Reliable Tool Calling

MCP servers, HTTP APIs, or 7,000+ apps via Zapier.

Deploy Anywhere

Web, mobile, or phone from a single config.

Live Transcript

Real-time streaming out of the box. Zero setup.

Logs & Analytics

Transcripts, recordings, and usage data — plus multimodal eval of any call (Pilot).

Quick Start

Integrate in 4 steps

Go from zero to a working voice UI in under an hour.

1

Sign up and create your agent

Create a free account, configure your voice agent with a system prompt, and get a phone number and API key in minutes.

Create account
2

Set up a token endpoint

Your backend proxies a single API call to generate short-lived connection tokens. Keep your API key server-side. 

# Your backend endpoint
curl -X POST "https://vocalbridgeai.com/api/v1/token" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"participant_name": "User"}'
3

Install the SDK and connect

Pick your framework, install, and connect in a few lines. Audio, transcripts, and heartbeats are handled automatically. 

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

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

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

// Handle agent-triggered actions
vb.on('agentAction', ({ action, payload }) => {
  handleAction(action, payload);
});

await vb.connect();
// Mic is live. Agent audio plays automatically.
npm install @vocalbridgeai/react
import { VocalBridgeProvider, useVocalBridge, useTranscript }
  from '@vocalbridgeai/react';

function App() {
  return (
    <VocalBridgeProvider
      auth={{ tokenUrl: '/api/voice-token' }}
      participantName="User">
      <VoiceUI />
    </VocalBridgeProvider>
  );
}

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

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

Iterate with the CLI

Use the Vocal Bridge CLI to review call logs, update prompts, evaluate calls with a multimodal LLM, and manage your agent without leaving the terminal. 

# Install
pip install vocal-bridge

# Authenticate
vb auth login

# Review call logs and transcripts
vb logs

# Update your agent's prompt
vb prompt edit

# Evaluate a call against an objective (Pilot only)
vb eval <session_id> --objective "Schedule a meeting"

# View full integration docs
vb docs

Key Feature

Client Actions: voice meets your UI

Bidirectional communication between your voice agent and your app. The agent can drive your UI, and your app can notify the agent.

Agent → App

The agent triggers actions in your UI during conversation.

vb.on('agentAction', ({ action, payload }) => {
  if (action === 'show_product') {
    showProductCard(payload.productId);
  }
  if (action === 'navigate') {
    router.push(payload.path);
  }
});

App → Agent

Your app sends events to the agent to keep it in context.

// User clicked a buy button in your UI
await vb.sendAction('user_clicked_buy', {
  productId: '123',
  quantity: 2
});
// Agent responds: "Great choice!"

Agent → App

Handle agent-triggered actions with a hook.

import { useAgentActions } from '@vocalbridgeai/react';

function VoiceUI() {
  useAgentActions((action, payload) => {
    if (action === 'show_product') {
      showProductCard(payload.productId);
    }
    if (action === 'navigate') {
      router.push(payload.path);
    }
  });
  // ...
}

App → Agent

Send events to the agent from any component.

import { useVocalBridge } from '@vocalbridgeai/react';

function BuyButton({ productId }) {
  const { sendAction } = useVocalBridge();

  return (
    <button onClick={() =>
      sendAction('user_clicked_buy', {
        productId, quantity: 1
      })
    }>Buy Now</button>
  );
}
// Agent responds: "Great choice!"

Configure client actions from the dashboard or via vb config set --client-actions-file actions.json. Each action has a name, description, and direction. See the full developer guide for the complete reference.

Bring Your Own Agent

AI Agent Integration

Already have a chatbot, RAG system, or LLM agent? Give it a voice. Vocal Bridge handles the real-time voice layer while your existing agent handles domain logic.

  • Voice agent delegates domain questions to your agent
  • Async — voice agent chats naturally while your agent processes
  • Adaptive or verbatim response modes
  • Enable from dashboard or vb config set --ai-agent-enabled true 
import { VocalBridge } from '@vocalbridgeai/sdk';

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

// One callback — SDK handles the rest
vb.onAIAgentQuery(async (query) => {
  // Forward to your existing agent
  const answer = await yourAgent.ask(query);
  return answer; // spoken back to the user
});

await vb.connect();
import { useAIAgent } from '@vocalbridgeai/react';

function MyApp() {
  // One hook — queries are forwarded automatically
  useAIAgent({
    onQuery: async (query) => {
      const answer = await yourAgent.ask(query);
      return answer; // spoken back to the user
    },
  });

  return <VoiceUI />;
}

How it works: User speaks → voice agent determines domain question → sends query_agent via data channel → your app forwards to your agent → response is spoken back. The voice agent fills naturally while waiting.

Passive Observer Mode

Listener Mode

A Vocal Bridge agent that never speaks. It joins a session, transcribes multi-speaker audio with speaker diarization, and streams real-time coaching suggestions to your app via the data channel.

  • Live transcript with speaker labels, streamed as the conversation unfolds
  • Coaching suggestions in Markdown when your prompt's policy matches the latest turn
  • Inferred speaker map — raw IDs upgraded to names and roles as the session progresses
  • Use cases: live IR coaching, sales-call assists, support-call escalation, interview prompts
  • Create with vb agent create --style Listener or pick "Listener" in the dashboard 
import { VocalBridge } from '@vocalbridgeai/sdk';

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

vb.on('agentAction', ({ action, payload }) => {
  switch (action) {
    case 'live_transcript': {
      const { speaker_id, text, is_final } = payload;
      if (is_final) appendFinal(speaker_id, text);
      else updateInterim(text);
      break;
    }
    case 'coaching_suggestion':
      // payload.guidance is Markdown — render with any renderer.
      renderCoachingCard(payload);
      break;
    case 'speaker_map_update':
      // payload.mapping = { S0: {name, org, role, confidence}, ... }
      refreshSpeakerLabels(payload.mapping);
      break;
  }
});

await vb.connect();
import { useAgentActions } from '@vocalbridgeai/react';

function ListenerUI() {
  useAgentActions((action, payload) => {
    if (action === 'live_transcript') {
      const { speaker_id, text, is_final } = payload;
      if (is_final) appendFinal(speaker_id, text);
      else updateInterim(text);
    } else if (action === 'coaching_suggestion') {
      renderCoachingCard(payload);
    } else if (action === 'speaker_map_update') {
      refreshSpeakerLabels(payload.mapping);
    }
  });

  return <YourTranscriptAndCoachingPanels />;
}

Your custom_prompt drives both when coaching fires and what it says. See the full developer guide for the complete action schemas, prompt design patterns, and how to ground coaching in your own data via MCP.

Developer Tools

SDKs, CLI, and plugins

JavaScript SDK

npm install @vocalbridgeai/sdk

Connect, stream transcripts, send/receive client actions, and manage audio. Works in any JS environment.

React SDK

npm install @vocalbridgeai/react

React hooks and Provider. useVocalBridge(), useTranscript(), and useAgentActions() for idiomatic React.

CLI

pip install vocal-bridge

Manage agents, review call logs, download recordings, update prompts, and access the full developer docs with vb docs — all from your terminal.

Claude Code Plugin

Native slash commands inside Claude Code. Manage your agent, stream debug events, and update configs without leaving your AI assistant. 

# Claude Code
/plugin marketplace add vocalbridgeai/vocal-bridge-marketplace
/plugin install vocal-bridge@vocal-bridge

# Or via npx
npx skills add vocalbridgeai/vocal-bridge-claude-plugin

Also supports Flutter/Dart, Swift (iOS), and Kotlin (Android) via WebRTC SDKs. See the full developer guide for platform-specific instructions.

Need the complete reference?

The full developer guide covers API reference, authentication details, all SDK methods, AI Agent mode, MCP tools, post-processing, and more.

$ vb docs
Full Developer Guide

Start building with voice today

Create your free account, deploy an agent, and integrate it into your app. No credit card required.

Sign Up Free Full Developer Guide