Skip to content

Connect your app

A session starts with one HTTP request, sessions.connect, which returns the connect params. Your page hands those to the client, and the browser then negotiates WebRTC directly with the Voqalize machine that runs the session. Audio is direct UDP; transcripts, actions and your page’s events ride RTVI on the same peer connection’s data channel.

POST sessions.connect ──▶ connect params
│
└─▶ client.connect(params) ──▶ WebRTC, direct
POST https://app.voqalize.com/api/v1/sessions.connect
Authorization: Bearer <your key>
Content-Type: application/json
{
"agent_id": "06a2…",
"config": {
"tts": { "voice": "omnivoice/gauri", "language": "ta" },
"stt": { "language": "ta" },
"record": false
},
"init": { "order_id": "A-1183" }
}

Every field but agent_id is optional. A body with only agent_id starts a session in English with the agent’s recording default.

  • init is your data for the brain. It arrives untouched as session.init. It is stored on the session, so send identifiers and look them up in your own store. Context and history shows how a brain reads it.
  • config is how this session sounds and listens (tts, stt, idle, ack) and whether it records (record). Set the voice and language here when your server already knows the user’s language; the brain can still change them with session.configure(...), and it has the last word. Voice and language has the rules, including why a language goes on both legs.
  • display_name and metadata label the session in the console and in session reads. HTTP API has their limits.

The body is strict: an undeclared key is refused with 422, naming it.

{
"webrtc_request_params": {
"endpoint": "https://…/webrtc",
"headers": { "Authorization": "Bearer <session token>" }
},
"session_id": "…"
}

An ice_config key is added when the machine running the session has a relay of its own; forward it with the rest.

  • The endpoint is one machine, chosen for this session. It changes from one session to the next, so it can never be a constant in your page.
  • The session token is scoped to this session and expires in minutes. It is the only Voqalize credential the browser holds.
  • Forward the body; do not read it. The client takes these keys as they are. For the session’s status, timings and recordings, read the session later with get_session (Reading a call back).

Same route, same body, same response. What differs is which key signs it and where it runs.

Use this whenever starting a session depends on who the user is: their login, their plan, which agent they are entitled to. It is also the only path for native mobile apps, which send no Origin header.

  1. Your page asks your backend for connect params, authenticated however your app already authenticates.
  2. Your backend calls sessions.connect with the agent’s secret sk_ key, naming the init and config it decided this user gets.
  3. Your backend returns the response body and status to the page unchanged.
// your server: the only place the sk_ key exists
app.post("/api/voice/start", requireLogin, async (req, res) => {
const r = await fetch("https://app.voqalize.com/api/v1/sessions.connect", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VOQALIZE_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
agent_id: process.env.VOQALIZE_AGENT_ID,
init: { customer_id: req.user.id },
config: { record: req.body.consented === true },
}),
});
res.status(r.status).json(await r.json()); // relay the body and the status
});

Renaming or dropping a field breaks the page’s connect, so relay it whole.

A publishable pk_ key may sit in page source and call sessions.connect directly from the browser. It can start sessions for its one agent and do nothing else. Use it when anyone who can load the page may talk to the agent: a public demo, a marketing page, a support widget.

A pk_ key is locked to the list of origins it was minted with, at least one. Add every site that embeds it, including the http://localhost:5173 you develop against. A request from any other origin, or with no Origin header at all (a server or a native app), is refused with 403 origin_not_allowed. A pk_ may turn recording off but never on (below). Keys covers minting both kinds.

Install the client and @voqalize/client-transport as Client libraries shows, then:

import { PipecatClient } from "@pipecat-ai/client-js";
import { createVoqalizeTransport } from "@voqalize/client-transport";
const client = new PipecatClient({
transport: createVoqalizeTransport(),
enableMic: true,
});
const withRealHeaders = (p) => ({
...p,
webrtc_request_params: {
...p.webrtc_request_params,
headers: new Headers(p.webrtc_request_params.headers),
},
});
// From your server (above), or straight to sessions.connect with a pk_ key.
const params = await fetch("/api/voice/start", {
method: "POST",
credentials: "include",
}).then((r) => r.json());
await client.connect(withRealHeaders(params));

The client’s events and hooks then give you the transcript, the agent’s actions and a way to send your own events; Client libraries lists them.

withRealHeaders turns the plain headers object from JSON into a Headers instance. The transport requires one, and without it the offer request throws a TypeError that does not mention headers. TypeScript does not catch it, because the client types connect params as unknown.

Call connect yourself rather than startBotAndConnect: that helper passes the parsed response straight to the transport, leaving nowhere to apply this line.

Every error has the same envelope:

{
"error": { "code": "invalid_config", "message": "…", "details": { "code": "unsupported_language" } },
"info": "…",
"correlation_id": "…"
}

Branch on error.code. Show a person info, which repeats error.message where the client looks for it. Quote correlation_id when you ask us about a session.

The ones you will meet first:

  • 400 invalid_config: a voice or language Voqalize does not serve; check the catalog. A language on one leg only is refused at the offer instead, when client.connect runs.
  • 400 recording_not_permitted: record: true on a pk_ (below).
  • 403 origin_not_allowed: a pk_ from an origin not on its list.
  • 409 agent_not_configured: the agent has no way to reach a brain (Deploy the brain).

Error codes has every status, cause and fix.

A reload, or a link to another page of your site, closes the peer connection but not the session. The Voqalize machine holds a session for 10 seconds after its connection closes and accepts a fresh offer with the same session token as that session coming back, even after the token has expired.

Turn on keepAcrossPageLoads and the transport does it for you:

const transport = createVoqalizeTransport({ keepAcrossPageLoads: true });
const client = new PipecatClient({ transport, enableMic: true });
// On every page load.
if (transport.hasLiveCall) {
client.connect().catch(() => {
// The session ended while the page was away. hasLiveCall is now false.
});
}
// The "Start" button, as before.
await client.connect(withRealHeaders(params));
// The "End" button.
client.disconnectBot();
await client.disconnect();
  • The transport saves the params each connect() used, in sessionStorage. connect() with no arguments rejoins with them; params you pass always win.
  • Do not call sessions.connect on a rejoin. That starts a second session.
  • It forgets the session on disconnectBot() and when the machine refuses the rejoin: 410 for a session that ended, another 4xx for one it no longer holds. connect() then rejects once.
  • Do not hang up on pagehide. A page that never comes back ends the session when the 10-second hold runs out.
  • Construct the client with enableMic: true. Opening the microphone before the agent’s audio arrives is what lets the browser play it on a page nobody has tapped. For a user who was muted, call enableMic(false) once connected.
  • sessionStorage is per tab, so a second tab starts its own session. The saved params carry the session token: any script on your page can read them.
  • A page restored from the back/forward cache has lost its connection. Reload it on pageshow when event.persisted is true.

keepAcrossPageLoads is a browser feature of @voqalize/client-transport.

config.record overrides the agent’s recording default for one session. Omit it and the agent default applies.

  • record: false is always honoured, on either key, even on an agent that records by default. Send it when the user declines.
  • record: true is refused on a pk_ key with 400 recording_not_permitted, and no session starts: a key in page source must not be able to write voice into your storage. Send it from your server with an sk_ when the user consents.

A recorded session also records the user’s camera and screen whenever the page turns them on (Camera and screen). Recordings covers what is stored and how to read it.