Sarvam Agent Widget SDK

A JavaScript SDK for integrating with Sarvam Agent Widget APIs and WebSocket connections. This SDK provides a simple and powerful way to build voice-enabled applications with real-time audio processing.

Features

• 🎤 Audio Processing: Real-time audio capture and processing
• 🔗 WebSocket Integration: Seamless real-time communication
• 📡 API Client: Easy-to-use API client for widget configuration
• 🎵 Audio Playback: Built-in audio response playback
• 🔄 Auto-reconnection: Automatic WebSocket reconnection
• 📝 TypeScript Support: Full TypeScript support with type definitions
• 🛡️ Error Handling: Comprehensive error handling and logging

Installation

npm install @sarvam/agent-widget-sdk

Quick Start

import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

// Initialize the SDK
const sdk = new SarvamWidgetSDK({
	apiUrl: 'https://agent-widget-sarvam.vercel.app',
	enableLogging: true
});

// Initialize audio and setup
await sdk.initialize();

// Start a voice session
await sdk.startVoiceSession(
	{
		orgId: 'your-org-id',
		appId: 'your-app-id',
		token: 'your-token'
	},
	{
		onOpen: () => console.log('Connected'),
		onMessage: (event) => console.log('Message received:', event.data),
		onClose: () => console.log('Disconnected'),
		onError: (error) => console.error('Error:', error),
		onAudioResponse: (audioData) => {
			// Handle audio response
			sdk.playAudioResponse(audioData.data);
		}
	}
);

// Start interaction
sdk.startInteraction('Current page content...');

API Reference

SarvamWidgetSDK

Main SDK class that provides access to all functionality.

Constructor

new SarvamWidgetSDK(config?: SDKConfig)

Parameters:

• config (optional): Configuration object
  • apiUrl: API base URL (default: 'https://agent-widget-sarvam.vercel.app')
  • enableLogging: Enable console logging (default: true)
  • autoReconnect: Auto-reconnect WebSocket (default: true)
  • reconnectInterval: Reconnection interval in ms (default: 3000)
  • maxReconnectAttempts: Maximum reconnection attempts (default: 5)

Methods

initialize(): Promise<void>

Initializes the SDK with audio processor and sets up audio context.

await sdk.initialize();

startVoiceSession(config, handlers): Promise<void>

Starts a voice session with WebSocket connection.

await sdk.startVoiceSession(
	{
		orgId: 'org-123',
		appId: 'app-456',
		token: 'your-token',
		appVersion: 1 // optional
	},
	{
		onOpen: () => console.log('Connected'),
		onMessage: (event) => console.log('Message:', event.data),
		onClose: () => console.log('Disconnected'),
		onError: (error) => console.error('Error:', error),
		onAudioResponse: (audioData) => {
			// Handle audio response
		},
		onTextResponse: (text) => {
			// Handle text response
		}
	}
);

startInteraction(webContent?: string): void

Starts audio recording and interaction.

sdk.startInteraction('Current page content or context');

stopInteraction(): void

Stops audio recording and interaction.

sdk.stopInteraction();

sendContentUpdate(content: string): void

Sends content update to the agent.

sdk.sendContentUpdate('Updated page content');

playAudioResponse(audioData: string, onStart?: () => void, onEnd?: () => void): Promise<void>

Plays audio response.

await sdk.playAudioResponse(
	base64AudioData,
	() => console.log('Playback started'),
	() => console.log('Playback ended')
);

endVoiceSession(): Promise<void>

Ends the voice session and cleans up resources.

await sdk.endVoiceSession();

cleanup(): Promise<void>

Cleans up all SDK resources.

await sdk.cleanup();

Widget Configuration API

getWidgetConfig(appId: string): Promise<WidgetConfig>

Retrieves widget configuration.

const config = await sdk.getWidgetConfig('app-123');
console.log(config);

createWidgetConfig(config): Promise<WidgetConfig>

Creates a new widget configuration.

const config = await sdk.createWidgetConfig({
	appId: 'app-123',
	orgId: 'org-456',
	orgName: 'My Organization',
	buttonConfig: {
		text: 'Talk to us',
		bgColor: '#0066cc',
		textColor: '#ffffff',
		endText: 'End Call'
	},
	widgetConfig: {
		title: 'Support Chat',
		logoUrl: 'https://example.com/logo.png'
	}
});

updateWidgetConfig(appId: string, updates): Promise<WidgetConfig>

Updates widget configuration.

const config = await sdk.updateWidgetConfig('app-123', {
	buttonConfig: {
		text: 'New button text',
		bgColor: '#ff0000'
	}
});

Audio Device Management

getAudioDevices(): Promise<MediaDeviceInfo[]>

Gets available audio input devices.

const devices = await sdk.getAudioDevices();
console.log(devices);

setAudioInputDevice(deviceId: string): Promise<void>

Sets the audio input device.

await sdk.setAudioInputDevice('device-id');

Status Methods

isInitialized(): boolean

Checks if SDK is initialized.

if (sdk.isInitialized()) {
	console.log('SDK is ready');
}

isConnected(): boolean

Checks if WebSocket is connected.

if (sdk.isConnected()) {
	console.log('WebSocket is connected');
}

isRecording(): boolean

Checks if audio is being recorded.

if (sdk.isRecording()) {
	console.log('Recording audio');
}

Proxy API

proxyRequest(url: string, options): Promise<Response>

Makes requests through the proxy to bypass CORS.

const response = await sdk.proxyRequest('https://api.example.com/data', {
	method: 'POST',
	headers: {
		Authorization: 'Bearer token'
	},
	body: { data: 'example' }
});

Error Handling

The SDK provides comprehensive error handling with specific error codes:

import { SDKError } from '@sarvam/agent-widget-sdk';

try {
	await sdk.initialize();
} catch (error) {
	if (error instanceof SDKError) {
		console.error('SDK Error:', error.code, error.message);
		console.error('Details:', error.details);
	}
}

Error Codes

• SDK_INITIALIZATION_FAILED: Failed to initialize SDK
• SDK_NOT_INITIALIZED: SDK not initialized
• WEBSOCKET_CONNECTION_FAILED: WebSocket connection failed
• WEBSOCKET_NOT_CONNECTED: WebSocket not connected
• AUDIO_SETUP_FAILED: Audio setup failed
• AUDIO_PLAYBACK_FAILED: Audio playback failed
• WIDGET_CONFIG_FETCH_FAILED: Widget config fetch failed
• PROXY_REQUEST_FAILED: Proxy request failed

Examples

Basic Voice Chat

import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

const sdk = new SarvamWidgetSDK();

async function startVoiceChat() {
	try {
		// Initialize SDK
		await sdk.initialize();

		// Start voice session
		await sdk.startVoiceSession(
			{
				orgId: 'your-org-id',
				appId: 'your-app-id',
				token: 'your-token'
			},
			{
				onOpen: () => console.log('Voice chat connected'),
				onAudioResponse: async (audioData) => {
					await sdk.playAudioResponse(audioData.data);
				},
				onClose: () => console.log('Voice chat disconnected')
			}
		);

		// Start interaction
		sdk.startInteraction('Hello, I need help with...');
	} catch (error) {
		console.error('Failed to start voice chat:', error);
	}
}

startVoiceChat();

Widget Configuration Management

import SarvamWidgetSDK from '@sarvam/agent-widget-sdk';

const sdk = new SarvamWidgetSDK();

async function manageWidgetConfig() {
	try {
		// Get existing config
		const config = await sdk.getWidgetConfig('app-123');
		console.log('Current config:', config);

		// Update config
		const updatedConfig = await sdk.updateWidgetConfig('app-123', {
			buttonConfig: {
				text: 'Chat with AI',
				bgColor: '#4CAF50'
			}
		});

		console.log('Updated config:', updatedConfig);
	} catch (error) {
		console.error('Failed to manage config:', error);
	}
}

manageWidgetConfig();

TypeScript Support

The SDK is written in TypeScript and provides complete type definitions:

import SarvamWidgetSDK, {
	SDKConfig,
	VoiceSessionConfig,
	WebSocketHandlers,
	WidgetConfig
} from '@sarvam/agent-widget-sdk';

const config: SDKConfig = {
	apiUrl: 'https://agent-widget-sarvam.vercel.app',
	enableLogging: true
};

const sdk = new SarvamWidgetSDK(config);

const sessionConfig: VoiceSessionConfig = {
	orgId: 'org-123',
	appId: 'app-456',
	token: 'your-token'
};

const handlers: WebSocketHandlers = {
	onOpen: () => console.log('Connected'),
	onMessage: (event) => console.log('Message:', event.data),
	onClose: () => console.log('Disconnected'),
	onError: (error) => console.error('Error:', error)
};

Browser Support

The SDK supports all modern browsers with WebRTC and Web Audio API support:

• Chrome 66+
• Firefox 60+
• Safari 13+
• Edge 79+

License

MIT License - see LICENSE file for details.

Support

For questions and support, please contact the Sarvam AI team or create an issue in the repository.