@vocalbridgeai/sdk

Core JavaScript/TypeScript SDK for Vocal Bridge voice agents.

Installation

npm install @vocalbridgeai/sdk

Quick Start

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

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

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

// Listen for agent actions
vb.on('agentAction', ({ action, payload }) => {
  console.log('Action:', action, payload);
});

// Connect
await vb.connect();

// Send an action
vb.sendAction('user_clicked_buy', { productId: '123' });

// Mute/unmute
await vb.toggleMicrophone();

// Disconnect
await vb.disconnect();

API

new VocalBridge(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | auth | AuthConfig | required | Authentication strategy | | participantName | string | "User" | Display name | | sessionId | string | auto | Custom session ID | | autoAckHeartbeat | boolean | true | Auto-acknowledge agent heartbeats | | autoPlayAudio | boolean | true | Auto-attach agent audio elements | | maxReconnectAttempts | number | 3 | Max reconnect retries | | reconnectDelay | number | 2000 | Delay between retries (ms) | | debug | boolean | false | Console logging |

Auth Strategies

// API key (prototyping)
{ apiKey: 'vb_xxx', agentId?: 'uuid' }

// Token URL (production)
{ tokenUrl: '/api/voice-token', headers?: {}, body?: {} }

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

Methods

| Method | Description | |--------|-------------| | connect() | Connect to the voice agent | | disconnect() | Disconnect and clean up | | setMicrophoneEnabled(enabled) | Mute/unmute mic | | toggleMicrophone() | Toggle mic state | | sendAction(action, payload?) | Send custom action to agent | | sendAIAgentResponse(turnId, response) | Respond to AI agent query | | onAIAgentQuery(handler) | Register auto-response handler |

Properties

| Property | Type | Description | |----------|------|-------------| | state | ConnectionState | Current connection state | | isMicrophoneEnabled | boolean | Mic enabled state | | transcript | TranscriptEntry[] | Accumulated transcript | | agentMode | string? | Agent mode from token | | roomName | string? | Current room name | | room | Room? | Underlying Room instance (advanced) |

Events

| Event | Data | Description | |-------|------|-------------| | connectionStateChanged | ConnectionState | State transition | | transcript | { role, text, timestamp } | New transcript entry | | agentAction | { action, payload } | Custom agent action | | heartbeat | { timestamp, agent_identity } | Agent heartbeat | | aiAgentQuery | { query, turnId } | AI agent query | | microphoneChanged | boolean | Mic state change | | error | VocalBridgeError | Error occurred |

ConnectionState

disconnected -> connecting -> waiting_for_agent -> connected
                                                     |
                                             reconnecting

AI Agent Integration

// Automatic: return value is sent as response
vb.onAIAgentQuery(async (query) => {
  return await myAgent.ask(query);
});

// Manual: full control over the flow
vb.on('aiAgentQuery', async ({ query, turnId }) => {
  const answer = await myAgent.ask(query);
  vb.sendAIAgentResponse(turnId, answer);
});

License

Apache-2.0