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

# Web SDK reference

> Every option and method of the Hamsa Web SDK (@hamsa-ai/voice-agents-sdk 0.7.0): the constructor, start() options, call methods, page tools and TypeScript types.

For version 0.7.0 of `@hamsa-ai/voice-agents-sdk`.

## Constructor

```javascript theme={null}
const agent = new HamsaVoiceAgent({ publicKey: "pk_...", region: "eu" });
```

| Option | What it does | Default |
| - | - | - |
| `publicKey` | Your public key (`pk_…`). Leave it out when every call starts with a [call token](https://docs.tryhamsa.com/developers/sdks/web-sdk/start-calls.md#with-a-call-token-from-your-server). | none |
| `region` | Where your Hamsa account runs: `eu` or `uae`. | `eu` |
| `API_URL` | The Hamsa API address. Overrides `region`. | `eu`: `https://api.tryhamsa.com`, `uae`: `https://api.uae.tryhamsa.com` |
| `LIVEKIT_URL` | The call server's address. Overrides `region`. | `eu`: `wss://rtc.eu.tryhamsa.com`, `uae`: `wss://rtc.uae.tryhamsa.com` |
| `debug` | Log what the SDK does to the browser console. | `false` |

Code from before public keys passes an API key first: `new HamsaVoiceAgent(API_KEY, options)`. It still works. See [Migrate](https://docs.tryhamsa.com/developers/sdks/web-sdk/migrate.md).

## start() options

```javascript theme={null}
await agent.start({ agentId: "YOUR_AGENT_ID", params: { customer_name: "Sara" } });
```

| Option | What it does |
| - | - |
| `agentId` | Required. The agent to call. |
| `callToken` | A call token from your server, or a function that returns one (or a promise of one). See [Start calls](https://docs.tryhamsa.com/developers/sdks/web-sdk/start-calls.md#with-a-call-token-from-your-server). |
| `params` | Values for the agent's [variables](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md), as `{ name: value }`. |
| `callerKey` | A stable ID for the person (1 to 200 characters), to keep them on one side of an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md). |
| `isChatOnly` | `true` for a [chat](https://docs.tryhamsa.com/developers/sdks/web-sdk/chat.md): no microphone, no audio. Default `false`. |
| `tools` | Functions the agent can call in your page. See [Page tools](#page-tools). |
| `voiceEnablement` | `true` to turn on your page tools for this call. Leave it out when you pass no `tools`. Default `false`. |
| `versionRef` | Not from a page: refused with a public key or an older API key, and ignored next to a call token. To run a version, your server puts it in the [call token](https://docs.tryhamsa.com/developers/sdks/web-sdk/start-calls.md#with-a-call-token-from-your-server). |
| `environmentId` | The same as `versionRef`. |
| `onAudioData` | Get the agent's voice as it plays. See [Audio](https://docs.tryhamsa.com/developers/sdks/web-sdk/audio.md#capture-call-audio). |
| `captureAudio` | Capture the call's audio with your own settings. See [Audio](https://docs.tryhamsa.com/developers/sdks/web-sdk/audio.md#capture-options). |

`start()` returns a promise that resolves once the call has started. If the call can't start, `error` fires, or the promise rejects when nothing listens for `error`.

`userId`, `preferHeadphonesForIosDevices`, `connectionDelay` and `disableWakeLock` are still accepted, so older code keeps working, but they have no effect.

## Methods

### The call

| Method | What it does |
| - | - |
| `start(options)` | Starts a call. Returns a promise. |
| `end()` | Ends the call. |
| `pause()` | Turns off the microphone and stops playing the agent. The call stays connected. |
| `resume()` | Undoes `pause()`. |
| `sendMessage(text)` | Sends the visitor's message in a [chat](https://docs.tryhamsa.com/developers/sdks/web-sdk/chat.md). Returns a promise. |
| `sendDTMF(digit)` | Sends a keypad digit: `"0"` to `"9"`, `"*"` or `"#"`. |
| `getJobId()` | The current call's ID, or `null`. |
| `getJobDetails()` | Reads the call from the API. Only with an older API key in the page; otherwise it throws. |

### Microphone and volume

| Method | What it does |
| - | - |
| `setMicMuted(muted)` | Mutes (`true`) or unmutes (`false`) the microphone. |
| `isMicMuted()` | Whether the microphone is muted. |
| `setVolume(volume)` | Sets how loud the agent plays, from 0 to 1. |
| `getOutputVolume()` | The volume set with `setVolume()`, 0 to 1. |
| `getInputVolume()` | How loud the visitor's microphone is right now, 0 to 1. |
| `getInputByteFrequencyData()` | The visitor's sound as frequencies (`Uint8Array`, 0 to 255). |
| `getOutputByteFrequencyData()` | The agent's sound as frequencies. |
| `enableAudioCapture(options)` | Starts capturing the call's audio. See [Audio](https://docs.tryhamsa.com/developers/sdks/web-sdk/audio.md). |
| `disableAudioCapture()` | Stops capturing. |

### Analytics

`getConnectionStats()`, `getAudioLevels()`, `getPerformanceMetrics()`, `getParticipants()`, `getTrackStats()` and `getCallAnalytics()`. See [Read call statistics](https://docs.tryhamsa.com/developers/sdks/web-sdk/events.md#read-call-statistics).

### Events

| Method | What it does |
| - | - |
| `on(event, handler)` | Listen for an event. See [Events](https://docs.tryhamsa.com/developers/sdks/web-sdk/events.md). |
| `once(event, handler)` | Listen for the next time only. |
| `off(event, handler)` | Stop listening. |

### LiveKit objects

The SDK runs on [LiveKit](https://docs.livekit.io/client-sdk-js/). If you build on LiveKit yourself, for example with its React components:

| Method | Returns |
| - | - |
| `getRoom()` | The call's LiveKit `Room`, or `null`. |
| `getRemoteAudioTrack()` | The agent's audio track, or `undefined`. |

## Page tools

Each function in `tools`:

| Field | What it is |
| - | - |
| `function_name` | The web tool's name, exactly as in **APIs & MCPs**. |
| `fn` | Your function. It gets the arguments and returns the answer. |
| `description`, `parameters`, `required` | Accepted, but the agent uses the web tool you set up in Hamsa, not these. |

How to set up the web tool, read its arguments, return an answer and handle failures: [Web tools](https://docs.tryhamsa.com/agents/tools/web-tools.md).

## Errors

`HamsaApiError` extends `Error` with `messageKey`, `status`, `params` and `retryAfter`. The keys and what they mean: [If a call fails to start](https://docs.tryhamsa.com/developers/sdks/web-sdk/start-calls.md#if-a-call-fails-to-start).

## Exports

```typescript theme={null}
import HamsaVoiceAgent, { HamsaApiError, RpcError } from "@hamsa-ai/voice-agents-sdk";

import type {
  StartOptions,
  HamsaVoiceAgentEvents,
  CallStartedData,
  AgentState,
  ReceivedMessage,
  MessageRole,
  DTMFDigit,
  Tool,
  AudioCaptureOptions,
  AudioCaptureMetadata,
  AudioCaptureFormat,
  AudioCaptureSource,
  AudioCaptureCallback,
  CallAnalyticsResult,
  ConnectionStatsResult,
  AudioLevelsResult,
  PerformanceMetricsResult,
  TrackStatsResult,
  ParticipantData,
  JobDetails,
} from "@hamsa-ai/voice-agents-sdk";
```

`HamsaVoiceAgent` is also a named export. The SDK also re-exports LiveKit's `Room`, `RemoteParticipant`, `RemoteTrack`, `RemoteTrackPublication`, `LocalTrack` and `RpcInvocationData` types.

Event handlers are typed: `agent.on("callStarted", ({ jobId }) => ...)` knows `jobId` is a string.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.