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

# WebSocket Connectivity

> Unpod exposes your agent as a WebSocket endpoint. Any browser, app, or client connects to it. Speech is processed entirely by Unpod.

## How It Works

When you create an agent on Unpod, it is automatically available as a WebSocket endpoint. Any client - browser, mobile app, desktop, IoT device - can connect to that endpoint and have a real-time voice conversation.

Your agent code does not change. Speech processing (STT, VAD, barge-in, endpointing, TTS) all happens on Unpod's side. Your AgentRunner just receives text and returns text, exactly as it does for phone calls.

WebSocket connectivity

Client

BrowserWeb pageMobile appYour app, any platformAny clientDesktop, IoT device

audio

Unpod runs

WSS endpointCreated with your agentSpeech inSTT + VAD, endpointingSpeech outTTS + barge-in

text intext out

You run

AgentRunnerSame code as phone calls

Unpod runs itYou run itOutside bothSpeech stays on Unpod. Your AgentRunner receives text and returns text.

***

## Connecting a Client

Unpod exposes a standard WebSocket URL per agent voice. Your client connects with a short-lived token, minted against that voice's `pipe_id` - browser sessions are the one surface still keyed on the pipe id rather than the `agent_id`:

> [!WARNING]
>
> `@unpod/web-sdk` is **not yet published on npm**. The snippet below is the
> intended shape, not something you can `npm install` today. To hear an agent in a
> browser now, use the
> [Playground](https://app.unpod.ai/playground?tab=preview).

```typescript theme={null}
import { UnpodSession } from "@unpod/web-sdk";

const session = new UnpodSession({
  token: "<session-token-from-your-backend>",
});

await session.connect();   // starts mic + speaker, full duplex audio

session.on("agent_reply", (text) => console.log("Agent:", text));
session.on("user_turn",   (text) => console.log("User:", text));

await session.disconnect();
```

Clients can be anything that speaks WebSocket - browser SDK, mobile SDK, a raw WebSocket client, or a third-party integration.

***

## Generating a Session Token

Your backend generates a short-lived token for each user session. Pass it to the client - never expose your API key on the frontend.

```python theme={null}
from unpod import AsyncClient

async def get_session_token(pipe_id: str, user_id: str) -> str:
    # reads UNPOD_PLATFORM_TOKEN + UNPOD_ORG_HANDLE from .env; see the
    # credential table in /agent-sdk/setup-checklist
    async with AsyncClient() as client:
        token = await client.sessions.create_token(
            pipe_id=pipe_id,
            metadata={"user_id": user_id},
        )
        return token.token   # single-use, expires in 60s
```

Return the token to your frontend via your own API. The client passes it to `UnpodSession`.

***

## Same Agent, Multiple Entry Points

Your AgentRunner accepts sessions from all sources on the same `agent_id`. You do not need separate agents for phone calls and web/app clients.

Unpod voice stack

Caller

PhonePSTN, dials a numberBrowserWebRTC / WebSocketMobile appSession token

audio

Unpod runs

Number & carrierUnpod rails, or your trunkSpeech inSTT + VAD, from the voice profileOrchestratorTurns, barge-in, dispatchSpeech outTTS, streamed to the caller

text turnreply text

You run

AgentRunnerRegisters over WSSYour brainDialogMachine, LLM, any PythonTools & APIsYour systems

Unpod runs itYou run itOutside bothAudio never reaches your side. The bridge carries text in, text out.

The `CallContext` tells you how the session arrived:

```python theme={null}
from unpod import CallContext
from superdialog import DialogMachine

async def handle_call(ctx: CallContext) -> None:
    if ctx.direction == "inbound":
        print("caller dialled a number, or a client connected")
    elif ctx.direction == "outbound":
        print("your backend initiated the call")

    ctx.session.dialog_machine = DialogMachine("agent.yaml", llm="anthropic/claude-haiku-4-5")
    await ctx.session.run()
```

***

## What Unpod Handles

Everything audio-related is managed by Unpod on both phone and WebSocket sessions:

| Capability | Phone | WebSocket |
| - | - | - |
| STT (transcription) | Yes | Yes |
| VAD (turn detection) | Yes | Yes |
| Barge-in detection | Yes | Yes |
| TTS (synthesis) | Yes | Yes |
| Recording | Yes | Yes |
| Transcript storage | Yes | Yes |

Your code only ever sees text.

> [!NOTE]
>
> Media binding is handled entirely on Unpod's side. A media worker joins the
> LiveKit room for the session and bridges the caller's audio; your dialog brain
> connects over a separate text-only channel and never touches the audio stream
> or any SDP negotiation. This is why the same agent code runs unchanged across
> phone and WebSocket sessions.

***

## Next Steps

> [card] [AgentRunner & Sessions](https://docs.unpod.ai/agent-sdk/agent-runner.md)
>
> Capacity, env vars, graceful shutdown, and the session controls -
> say(), transfer, end - that work for all session types.


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