For the complete documentation index, see llms.txt. This page is also available as Markdown.

Chat over the SSE transport

Send text to a Convai character over Server-Sent Events, keep the API key on your server, play the character's voice and run the client under Node.

Chat with a Convai character over the SSE transport: text in, with the reply streamed back as text and, optionally, as speech. Each message is one HTTP POST whose response is a stream of events, and nothing stays open between messages. There is no WebRTC, no room and no microphone, so the SSE transport also runs under Node. Use this page to set up a chat, keep your API key off the page, play the character's voice, or call a character from a server.

Prerequisites

  • The Convai Web SDK installed. See Web SDK quickstart.

  • An interaction API URL: the production or staging endpoint above, your self-hosted endpoint, or your own server route that forwards to one.

Connect and send a message

Supplying interactionApiUrl selects the SSE transport when transport is omitted. You can also set transport: 'sse' explicitly.

src/App.tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

export default function App() {
  const client = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    interactionApiUrl: 'YOUR_INTERACTION_API_URL',
  });

  return <ConvaiWidget convaiClient={client} />;
}
src/main.ts
import { ConvaiClient } from '@convai/web-sdk/core';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  interactionApiUrl: 'YOUR_INTERACTION_API_URL',
});

client.on('characterSessionId', (id) => console.log('session', id));
client.on('messagesChange', (messages) => {
  const last = messages.at(-1);
  if (last) console.log(last.type, last.content);
});
client.on('botTurnCompleted', () => console.log('reply finished'));

await client.connect();
client.sendUserTextMessage('Say hello in exactly five words.');

Two configurations make connect() throw:

Configuration
Error

transport: 'sse' without interactionApiUrl

interactionApiUrl is required when using the SSE transport

transport: 'sse' with enableVideo: true

The SSE transport supports text interactions only

Key behaviours

  • connect() makes no network request. It marks the session ready and emits connect and botReady at once. The first request goes out when you send a message.

  • The character session ID arrives on the first interaction. There is no /connect handshake, so the server assigns the ID on the first message and the client emits characterSessionId. The event can fire again on later messages with the same value, so treat it as idempotent.

  • An API key travels as Authorization: Bearer …, an auth token as API-AUTH-TOKEN. When you supply both, the SDK sends only authToken. Up to 1.9.3 the SDK sent authToken as a Bearer value too, which the interaction API rejects with 401.

  • botTurnCompleted marks the end of a reply. turnEnd never fires on SSE, because it depends on the character's speaking state, which this transport does not report.

  • Microphone, video, screen share and lip sync do nothing on this transport. Speech output is the exception; see Play the character's voice.

Keep the API key on a server route

An API key in browser code is visible to anyone who opens the page. Point interactionApiUrl at a route on your own server instead. The route adds the key, pins the character, and streams the response back unbuffered so text arrives as it is generated.

In the browser, pass placeholders for the key and character, because the route supplies the real values:

Set CONVAI_API_KEY, CONVAI_CHARACTER_ID and CONVAI_INTERACTION_API_URL as server environment variables only. A VITE_ or NEXT_PUBLIC_ prefix bundles them into the page.

Play the character's voice

Speech is off by default on SSE. With ttsEnabled: true, the same response that carries the reply's text also carries its speech as audioData events. toggleTts(enabled) changes the setting for the next message.

The SDK emits the audio but does not play it, and neither ConvaiWidget nor createConvaiWidget() plays it for you. Each audioData chunk has these fields:

  • audio: base64-encoded signed 16-bit little-endian PCM, with no WAV header.

  • sample_rate and channels: read them from every chunk when you build audio buffers rather than hard-coding them.

This player schedules the chunks back to back with Web Audio, starts muted, and unmutes from a speaker button:

In React, subscribe in an effect instead: useEffect(() => client.on('audioData', play), [client]). on() returns the unsubscribe function, so the effect cleans up after itself.

Playback notes

  • Unlock audio on a gesture. Call AudioContext.resume() from a click or key press, or the browser keeps the context suspended and plays nothing.

  • Stop queued audio when the user sends. botTurnCompleted fires when the last chunk has been delivered, not when it has finished playing, so the previous reply can still be speaking.

  • Text and audio arrive independently. bot-llm-text messages and audioData chunks do not wait for each other.

  • There is no speaking state. isSpeaking means little without a microphone. Drive any speaking indicator from your own sources' onended.

Use the client under Node or on a server

SSE needs neither WebRTC nor a DOM, so it is the only transport that runs outside a browser: Node scripts, server-side rendering, serverless functions, CI checks and batch jobs. Import @convai/web-sdk/core there. The root and @convai/web-sdk/react entry points load browser-only code.

Your own typed messages do not appear in chatMessages as user entries; the transcript fills from server-sent messages, as on the other transports. Render the user's input from your own state.

API reference

Property / Method
Type
Description

transport

"livekit" | "websocket" | "sse"

Selects the transport. Resolves to "sse" when omitted and interactionApiUrl is set; otherwise "livekit".

interactionApiUrl

string

The interaction API endpoint, or your server route that forwards to it. Required for SSE.

ttsEnabled

boolean

Generates speech for each reply. Defaults to false on SSE.

toggleTts(enabled)

(enabled: boolean) => void

Turns speech on or off for the next message.

sendUserTextMessage(text, options?)

(text: string, options?: SendUserTextMessageOptions) => void

Sends one text message as one POST.

sendInterruptMessage()

() => void

Stops the reply in progress.

characterSessionId event

(id: string) => void

Emits the session ID the server assigned. Can repeat with the same value.

audioData event

(data: AudioDataEvent) => void

Emits one speech chunk: audio (base64 PCM), sample_rate, channels, includes_wav_header (always false).

botTurnCompleted event

(data: unknown) => void

Fires when a reply has been fully delivered.

Next steps

To decide between SSE and the realtime transports, and to set up the recommended SSE chat with a realtime voice mode, see Choose a transport.

Last updated

Was this helpful?