# Voqalize

> Voqalize adds voice to an existing web or mobile app. The user talks, the agent talks back and acts on the screen alongside them — and what they do in the app flows back as context.

Every page below is served as markdown. Drop the `.md` for the rendered page.

Start at [Voqalize](https://docs.voqalize.com/index.md) — the whole model on one page, with a link out of every branch. Check current status first, then use the task sections below to build and operate it.

## Start here

- [Current status and supported environments](https://docs.voqalize.com/overview/status.md): What is available today — SDK versions, clients, hosting, regions, stored data and retention, and where plans, limits and support are set.

## Build an agent

- [Build an embedded voice agent](https://docs.voqalize.com/build.md): Connect your app, implement the brain, deploy it, and verify a complete call.
- [A session, end to end](https://docs.voqalize.com/build/session.md): The whole path in order — the brain you write, the agent you create, the one request your server makes, and what happens while the call is up. Every step links to the page that goes deeper.
- [Quickstart](https://docs.voqalize.com/build/quickstart.md): A brain that answers, a call you can hear, in ten minutes. Install, write the brain, create an agent, open a page.
- [Connections and the handshake](https://docs.voqalize.com/build/connect.md): How a browser starts a Voqalize session — one HTTP request for the connect params, then pipecat's client on our transport. With a publishable key, or through your own backend.
- [Client libraries](https://docs.voqalize.com/build/pipecat.md): The browser half of a Voqalize call is pipecat's client with @voqalize/client-transport handling the media. What is ours, what is pipecat's, the stock path that still works, and which versions we hold to.
- [Your first brain](https://docs.voqalize.com/build/brain.md): The callbacks a brain implements, the one that is required, and the smallest brain that holds a conversation.
- [Speaking](https://docs.voqalize.com/build/brain/speaking.md): Speech is the only thing you yield. The frames that carry it, why a turn is many units, and what streaming buys the user.
- [Actions](https://docs.voqalize.com/build/brain/actions.md): The brain's second output. A typed message that renders on the page and is never spoken — declared as a pydantic model, dispatched from anywhere.
- [TypeScript types](https://docs.voqalize.com/build/brain/typescript.md): Your Action and AppEvent classes already describe every payload. `voqalize types` turns both into TypeScript unions so the browser half of each direction is derived rather than copied — and adding one becomes a compile error until it is handled.
- [Tools](https://docs.voqalize.com/build/brain/tools.md): Tool calls are local function calls in your process. The model speaks and then calls, a tool returns at once, and a result waits for the next request unless the model needs it now.
- [Context and history](https://docs.voqalize.com/build/brain/context.md): What the user did in the app arrives as context, so the two of you work together rather than past each other. The reverse channel, and what your brain remembers.
- [Transcripts and heard truth](https://docs.voqalize.com/build/brain/transcripts.md): Your history holds what the user heard, not what you intended to say. Where the finalized text comes from and where the record lives.
- [Bringing an agent you already have](https://docs.voqalize.com/build/existing-agent.md): You have an ADK, LangChain, OpenAI Agents or hand-rolled agent. What has to change to give it a voice, and what does not.
- [Deploy the brain](https://docs.voqalize.com/build/hosting.md): The brain_url is one WebSocket URL. Expose a route and let Voqalize dial it, or dial out to a Cortex relay — the same brain code either way.
- [Testing a brain](https://docs.voqalize.com/build/testing.md): Drive your brain over the real wire in text mode — no audio, no browser, no human — then inspect a live call.
- [Keys and authentication](https://docs.voqalize.com/build/keys.md): The secret key and the publishable key, both scoped to one agent. Which one your backend holds, which one ships in page source, and what the origin allowlist is actually doing.
- [The avatar](https://docs.voqalize.com/build/avatar.md): A 2.5-D talking head driven by the data channel. Voqalize already sends what it needs in every session; the browser half is one package, and your brain can drive the face directly.
- [Camera and screen](https://docs.voqalize.com/build/video.md): Record a session's camera and screenshare with the stock pipecat client. Turn lanes on with enableCam and enableScreenShare, optionally cap each lane's bitrate, and read the files back on one timeline.

## Improve the agent

- [Designing for voice](https://docs.voqalize.com/design.md): What changes when the output is spoken, the user can interrupt, and the screen is right there. The durable half of the problem.

## Operate

- [Operate](https://docs.voqalize.com/operate.md): Inspect one call, retrieve its artifacts, and monitor usage and limits.
- [Reading a call back](https://docs.voqalize.com/operate/reading-a-call.md): The record says what happened and is contract. Logs say why and are evidence. Milestones say how far the call got. Read them in that order, and check availability before concluding a call was silent.
- [Recordings](https://docs.voqalize.com/operate/recordings.md): Off by default, decided per call, one file per role — audio always, video when the page turns on the camera or screen. Who is allowed to turn recording on, why a publishable key is not, and what each recording state says is in storage.
- [Usage and limits](https://docs.voqalize.com/operate/usage.md): What Voqalize counts, how session duration is measured, which limits apply, and the one gap that tells you your embed is broken.

## API and protocols

- [API and protocol reference](https://docs.voqalize.com/reference.md): The contracts. The wire, the RTVI plane, the Brain API, the voice and language catalog, error codes, the HTTP API and the MCP server.
- [The Brain API](https://docs.voqalize.com/reference/brain.md): Every callback a brain may implement, its signature, and what it is handed. Which one is required, and which are generators.
- [The wire](https://docs.voqalize.com/reference/wire.md): One WebSocket per session between Voqalize and your brain — the framing, both planes, every message, and what each one obliges the other to do.
- [The RTVI plane](https://docs.voqalize.com/reference/rtvi.md): A whitelist of message types carried verbatim between your brain and your page. What crosses, what does not, and why the exclusions are the security property.
- [Voice & language catalog](https://docs.voqalize.com/reference/catalog.md): The recognizer languages and TTS voices a session can select, and how a brain moves them.
- [Error codes](https://docs.voqalize.com/reference/errors.md): Every code the wire can carry, what raises it, and whether the call survives it.
- [The HTTP API](https://docs.voqalize.com/reference/http-api.md): One route takes a key — sessions.connect, which starts a call. Its body, its strictness, and why management lives on MCP instead.
- [MCP server](https://docs.voqalize.com/reference/mcp.md): Create and manage agents, mint keys, set brain_urls, and read call records from your editor's agent — over a hosted, OAuth-authenticated MCP endpoint.