Browser SDK

Install @trelis/converse from npm. To hear Converse before integrating, open the playground.

Browser quickstart

1. Install the SDK

npm install @trelis/converse

2. Create a persistent key

Sign in to API & Billing and create a key. Keys begin with ck_ and are shown once. Store the key as a server-side secret; never put it in browser JavaScript.

3. Add a credential route to your backend

Your authenticated backend exchanges its persistent key for a short-lived credential bound to one browser session:

import { randomUUID } from 'node:crypto';

app.post('/voice/session', requireUser, async (_req, res) => {
  const upstream = await fetch('https://converse.trelis.com/api/v1/session-keys', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CONVERSE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ session_id: randomUUID() }),
  });
  res.status(upstream.status).json(await upstream.json());
});

Protect this route with your own user authentication. The browser should receive only the returned scoped credential.

4. Connect from the browser

import { ConverseClient } from '@trelis/converse';

const response = await fetch('/voice/session', {
  method: 'POST', credentials: 'same-origin',
});
if (!response.ok) throw new Error(`Voice credential failed: ${response.status}`);
const credential = await response.json();

const client = new ConverseClient({
  url: 'wss://converse.trelis.com/ws',
  sessionId: credential.session_id,
  apiKey: credential.api_key,
  mode: { kind: 'converse' },
});

client.addEventListener('utterance', ({ detail }) => {
  console.log('Assistant:', detail.text);
});
client.addEventListener('error', ({ detail }) => {
  console.error(detail.detail || detail.error);
});

startButton.addEventListener('click', async () => {
  await client.unlockAudio(); // keep this inside the user gesture
  await client.connect();
  await client.startMic();
});
stopButton.addEventListener('click', () => client.close());

Prepare the scoped credential before enabling the Start button. If it has sat unused for more than 10 minutes, mint a fresh one so the complete two-hour session window remains available.

Authentication

POST /api/v1/session-keys

Exchange a persistent key for a browser-safe session credential.

POST https://converse.trelis.com/api/v1/session-keys
Authorization: Bearer ck_your_key
Content-Type: application/json

{"session_id":"your-unique-session-id"}

HTTP/1.1 201 Created

{
  "api_key": "short-lived-session-key",
  "session_id": "your-unique-session-id",
  "expires_in": 7800
}

The scoped key expires after 130 minutes and works only with the returned session_id. It may be reused for sequential connections or reconnects carrying that ID until expiry; expiry also ends a connection still using it. Revoking the persistent key prevents new exchanges but does not invalidate scoped keys already issued.

session_id is 1–64 characters. The first character must be a letter, number, underscore or hyphen; later characters may also contain a period. In regex form: [A-Za-z0-9_-][A-Za-z0-9._-]{0,63}.

Browser SDK reference

ConverseClient(options)

Converse mode

mode: {
  kind: 'converse',
  voice: 'optional-voice-key',
  instructions: 'Optional application instructions',
  greeting: 'Hello!', // string, false, or omit for the default
  web_search: false,
  flow: false,
  tools: [],
  temperature: 0.7,
}

web_search defaults to false. Converse sessions may combine it with client tools; search joins the same automatic tool-selection loop as a managed lookup.

Methods

Properties: client.mode is the active mode configuration; client.responding is true while an assistant reply is active.

One-shot helpers

• sendFeedback({url, sessionId, rating?, text?, device?, browser?, apiKey?})
• sendClientError({url, sessionId?, detail, context?, apiKey?})

Both return promises and use a standalone WebSocket, so they can be called after the conversation socket has closed.

Advanced named exports are StreamingPlayer, MicCapture, EchoCanceller, needsSdkAec, audio conversion helpers, tagged-uplink helpers, and sample-rate/channel constants. Most applications should use ConverseClient rather than assembling these pieces.

Microphone, playback and echo cancellation

startMic() requests mono audio with echo cancellation enabled and noise suppression and automatic gain control disabled. The SDK chooses the available echo-cancellation path and feeds 16 kHz audio to Converse. Interruption detection remains server-side.

If you use pushMicFrame(), the SDK no longer owns capture. Supply echo-cancelled Float32 mono audio at 16 kHz. If assistant audio is audible through speakers and echo is not removed, the service may transcribe or react to its own voice.

Events

Server JSON events are shared by the browser and Python SDKs. In the browser, read fields from event.detail; in Python, read them from SessionEvent.data. Binary assistant audio and browser transport lifecycle events use the SDK-specific forms below.

Get an API key · Contact us