> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vogent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK

> Integrate Vogent into your web applications with the Vogent Web Client SDK

## Overview

The Vogent Web Client is a TypeScript/JavaScript library that allows you to integrate Vogent voice capabilities directly into your web applications. It provides real-time call management, audio streaming, and transcript monitoring.

<Card title="GitHub Repository" icon="github" href="https://github.com/vogent/vogent-web-client">
  View the source code and contribute on GitHub
</Card>

## Installation

Install the Vogent Web Client using your preferred package manager:

<CodeGroup>
  ```bash Bun theme={null}
  bun add @vogent/vogent-web-client
  ```

  ```bash NPM theme={null}
  npm install @vogent/vogent-web-client
  ```

  ```bash Yarn theme={null}
  yarn add @vogent/vogent-web-client
  ```
</CodeGroup>

## Prerequisites

Before using the Web SDK, you'll need:

* **sessionId**: Unique session identifier
* **dialId**: Unique dial/call identifier
* **token**: Authentication token (dial token)

<Warning>
  **Important**: Use a public API key when creating browser-based calls. Never expose your secret API key in client-side code.
</Warning>

## Quick Start

Here's a complete example of how to initiate a call and monitor transcripts:

```typescript theme={null}
import { VogentCall } from '@vogent/vogent-web-client';

// Step 1: Create a dial via the Vogent API
const response = await fetch('https://api.vogent.ai/api/dials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pub_vogent_...',  // Use your public API key
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callAgentId: 'your_call_agent_id',
    browserCall: true  // Important: Enable browser call mode
  })
});

const { dialToken, sessionId, dialId } = await response.json();

// Step 2: Initialize the VogentCall instance
const call = new VogentCall({
  sessionId,
  dialId,
  token: dialToken
});

// Step 3: Start the call session
await call.start();

// Step 4: Connect audio
const audioConnection = await call.connectAudio();

// Step 5: Monitor transcripts in real-time
const unsubscribe = call.monitorTranscript((transcript) => {
  transcript.forEach(({ text, speaker }) => {
    console.log(`${speaker}: ${text}`);
  });
});

// Step 6: Listen for status changes
call.on('status', (status) => {
  console.log('Call status:', status);
});

// Cleanup when done
unsubscribe();
await call.hangup();
```

## API Reference

### VogentCall Constructor

Initialize a new call instance:

```typescript theme={null}
const call = new VogentCall({
  sessionId: string,
  dialId: string,
  token: string
});
```

**Parameters:**

* `sessionId` (string): Unique identifier for the session
* `dialId` (string): Unique identifier for the dial/call
* `token` (string): Authentication token (dial token)

### Methods

#### `start()`

Initiates the call session.

```typescript theme={null}
await call.start();
```

**Returns:** `Promise<void>`

***

#### `connectAudio()`

Establishes the audio connection for the call.

```typescript theme={null}
const audioConnection = await call.connectAudio();
```

**Returns:** `Promise<AudioConnection>`

***

#### `monitorTranscript(callback)`

Monitors the call transcript in real-time.

```typescript theme={null}
const unsubscribe = call.monitorTranscript((transcript) => {
  transcript.forEach(({ text, speaker }) => {
    console.log(`${speaker}: ${text}`);
  });
});
```

**Parameters:**

* `callback` (function): Function called with transcript updates

**Returns:** `function` - Unsubscribe function to stop monitoring

**Transcript Object:**

* `text` (string): The transcribed text
* `speaker` (string): Speaker identifier (e.g., "user", "agent")

***

#### `setPaused(paused)`

Pauses or resumes AI interaction during the call.

```typescript theme={null}
await call.setPaused(true);  // Pause AI
await call.setPaused(false); // Resume AI
```

**Parameters:**

* `paused` (boolean): `true` to pause, `false` to resume

**Returns:** `Promise<void>`

***

#### `hangup()`

Ends the call.

```typescript theme={null}
await call.hangup();
```

**Returns:** `Promise<void>`

***

### Events

#### `status`

Listen for call status changes:

```typescript theme={null}
call.on('status', (status) => {
  console.log('Call status:', status);
});
```

**Status values:**

* `connecting`: Call is being established
* `connected`: Call is active
* `ended`: Call has ended
* `error`: An error occurred

## TypeScript Support

The Vogent Web Client is written in TypeScript and includes full type definitions for an enhanced development experience.

```typescript theme={null}
import type { VogentCall, TranscriptItem } from '@vogent/vogent-web-client';
```

## Error Handling

Always wrap your calls in try-catch blocks to handle errors gracefully:

```typescript theme={null}
try {
  await call.start();
  await call.connectAudio();
} catch (error) {
  console.error('Call error:', error);
  // Handle error appropriately
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Public API Keys">
    Always use public API keys (prefixed with `pub_`) in client-side code. Never expose secret API keys in your web application.
  </Accordion>

  <Accordion title="Clean Up Resources">
    Always unsubscribe from transcript monitoring and properly hang up calls when done:

    ```typescript theme={null}
    const unsubscribe = call.monitorTranscript(...);
    // ... later
    unsubscribe();
    await call.hangup();
    ```
  </Accordion>
</AccordionGroup>