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

# Voice SDK Quickstart

> Put a call button with your Telzino agent in a web page

The Voice SDK lets visitors talk to a Telzino voice agent from your own web page, with your own UI. The SDK handles the session, the microphone and the audio. You render the buttons and the transcript.

There are two packages:

* `@telzino/voice` is the core browser client. It works with any framework. It wraps LiveKit, so you never import `livekit-client` yourself.
* `@telzino/react` adds a provider and headless hooks on top of it. It includes no UI.

Looking for a ready-made widget instead? See [Web Embed](https://docs.telzino.com/integrations/web-embed.md).

## 1. Create a publishable key

A publishable key (`pk_live_...`) is safe to ship in a web page, because it only works from origins you list.

1. In the Telzino dashboard, open the **API Keys** page and find **Publishable keys**.
2. Create a key. Give it a name, such as `Marketing site`, and list its **Allowed origins**. Include `http://localhost:5173` (or your dev server) while developing.
3. Copy the key now. It is shown once.

> [!NOTE]
>
> Creating a publishable key requires a partner account user with the `create:api_keys` permission (a Telzino Admin). Reseller admins can view and revoke keys issued for their reseller, but cannot create them. If you do not see the create form, ask a Telzino Admin.

See [Authentication](https://docs.telzino.com/sdk/authentication.md) for how keys, origins and limits work.

## 2. Install

```sh Core theme={null}
npm i @telzino/voice
```

```sh React theme={null}
npm i @telzino/voice @telzino/react
```

## 3. Start a call

```ts Core theme={null}
import { TelzinoVoice } from '@telzino/voice';

const voice = new TelzinoVoice({ publishableKey: 'pk_live_...' });

const call = await voice.start({ agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f' });

call.on('transcript', (item) => console.log(item.role, item.text, item.final));
call.on('agentState', (state) => console.log('agent is', state));
call.on('ended', ({ reason }) => console.log('call ended:', reason));

await call.setMuted(true);
await call.setMuted(false);

await call.end();
```

```tsx React theme={null}
import { TelzinoProvider, useTelzino, useMuted, useAgentState, useTranscript, useNeedsUserGesture } from '@telzino/react';

const config = { publishableKey: 'pk_live_...' }; // inline objects are fine

function Call() {
  const { start, end, status, error } = useTelzino();
  const [muted, setMuted] = useMuted();
  const agentState = useAgentState();
  const transcript = useTranscript();
  const [needsGesture, resume] = useNeedsUserGesture();
  const live = status === 'connecting' || status === 'connected' || status === 'reconnecting';
  return (
    <div>
      <button onClick={() => (live ? end() : start({ agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f' }))}>{live ? 'Hang up' : 'Call'}</button>
      <button onClick={() => setMuted(!muted)} disabled={!live}>{muted ? 'Unmute' : 'Mute'}</button>
      <span>{agentState}</span>
      {needsGesture && <button onClick={resume}>Enable audio</button>}
      {error && <p role="alert">{error.message}</p>}
      <ul>{transcript.map((t) => <li key={t.id}>{t.role}: {t.text}</li>)}</ul>
    </div>
  );
}

export const App = () => <TelzinoProvider config={config}><Call /></TelzinoProvider>;
```

Replace the agent id with the id of one of your agents. `start()` asks for microphone permission, so call it from a user gesture such as a button click.

> [!WARNING]
>
> During the beta, point the SDK at the beta API with the `apiBaseUrl` option, for example `{ publishableKey: 'pk_live_...', apiBaseUrl: 'https://beta.telzino.io' }`. The default is `https://api.telzino.com`.

## Try the example app

The repository includes a complete demo, `examples/web-basic`, built with Vite, React and TypeScript. Copy `.env.example` to `.env.local` and set:

* `VITE_TELZINO_PUBLISHABLE_KEY`: your publishable key
* `VITE_TELZINO_AGENT_ID`: the agent to call
* `VITE_TELZINO_API_BASE_URL`: defaults to `https://beta.telzino.io`

Then build the packages and run the demo from the repo root:

```sh theme={null}
pnpm install
pnpm build
pnpm --filter web-basic dev
```

Open `http://localhost:5173`. The port is fixed so it matches the allowed origin. Click **Start call** and allow the microphone.

## Troubleshooting

* **A network error right away**: the page origin is not in the key's allowed origins. The browser blocks the request. Add the exact origin, including the port.
* **`permission_denied`**: microphone access was denied. Allow it in the browser's site settings and start again.
* **No sound**: the browser blocked audio playback. Show an "Enable audio" button and call `resumeAudio()` from its click handler. See [Core API](https://docs.telzino.com/sdk/core-api.md).

## Next steps

> [card] [Authentication](https://docs.telzino.com/sdk/authentication.md)
>
> Publishable and secret keys, origins and limits

> [card] [Core API](https://docs.telzino.com/sdk/core-api.md)
>
> TelzinoVoice and VoiceCall reference

> [card] [React](https://docs.telzino.com/sdk/react.md)
>
> Provider and hooks

> [card] [Events and errors](https://docs.telzino.com/sdk/events.md)
>
> Every event and error code


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