Skip to main content
Advanced For developers who want the people on a stream to talk, type or see each other. After this page you can join the project’s chat room from your own page and build your own chat interface on its events. Chat is a separate entry point of the same package: @streampixel/web-sdk/voice. A page that does not import it downloads no chat code. The SDK draws no chat interface: it gives you methods and events, and you draw the people, the messages and the buttons.
npm only. The script-tag build does not include chat.

Before you start

  • Turn chat on for the project in the dashboard: Built-in voice and text chat. While it is off, stream.voiceToken is undefined and VoiceChat.for() rejects.
  • You need a running stream: chat is created from a stream object. See Quick start.
  • If your site sends a Content-Security-Policy, allow the chat server. See Content-Security-Policy.

Add chat to your page

1

Install the package

Chat is in the package you already have. There is nothing extra to install.
2

Create the chat for a stream

VoiceChat.for() loads the chat code and prepares the chat. It does not connect yet.
3

Listen, then join

Attach your listeners first, so you see the first list of people. Then call join().
roster fires with yourself as localParticipant. Open the page in a second browser: each page sees the other in remoteParticipants.
4

Turn the microphone on from a button

The microphone starts off. Turn it on when the viewer asks for it. The browser shows its permission prompt the first time.
Everyone on the same project who joins is in the same room. Pass roomId for a separate room inside the project’s room. When the stream ends, the chat leaves the room by itself.
A page with a list of people, a message list, a text field and a microphone button. It leaves out styling and the error handling around Streampixel.create().
chat.ts

VoiceChat.for(stream, options)

Returns a Promise of the chat object. It rejects when the project has chat off, and with an EngineLoadError when the chat code cannot be loaded.
Streampixel
required
The stream this chat belongs to. The chat uses the stream’s project and its chat token.
object
required

Methods

Events

{ from, text, avatar? }
A chat message arrived, or you sent one. from is the sender’s id, or 'You' for your own message.
{ localParticipant, remoteParticipants }
Someone joined or left, started or stopped speaking, or changed microphone or camera. Redraw your list of people from it.
{ from, avatar? }
Someone is typing.
{ name, kind?, message }
The microphone or camera could not be opened. message is a short sentence: permission denied, no device found, or the device is in use by another app. name is the browser’s error name.
localParticipant is null when you are not in the room.
videoTrack is the track object of the chat library (LiveKit). The SDK types it as unknown, so cast it. This is a pattern: test it in your page.
Remote audio plays by itself: you do not attach audio elements. Browsers block sound until the viewer interacts with the page, so the SDK starts the audio on the viewer’s first click, tap or key press.
The capture sizes are small on purpose, so that sending a camera does not take bandwidth from the stream.

Chat the app asks for

Some apps put the viewer into chat themselves, by sending a comms message. The SDK does not join by itself: listen for the message and join.
Coming from Epic’s Pixel Streaming library? Its method names work on the stream object too: emitUIInteraction(), emitConsoleCommand() and addResponseEventListener(). They are the same calls as send(), consoleCommand() and on('ueMessage'). Use whichever you know. See Talk to your Unreal app.
The app sends { "message": { "type": "comms", "value": { "roomId": "...", "name": "..." } } } to join a room, and "value": "disconnect" to leave.

Chat in a shared session

Chat works the same for the host and the viewers of a shared session. Each page creates its own chat from its own stream.

Content-Security-Policy

Chat connects to the chat server on LiveKit Cloud. If your site sends a Content-Security-Policy, add this to connect-src:
The chat code itself is downloaded from the same two hosts as the stream engine, with the same checks, so script-src needs nothing extra. The full list is in Installation.

Troubleshooting

The project’s chat is off, so the ticket carried no chat token. Turn chat on in the dashboard, then start a new stream. Check stream.voiceToken before you call VoiceChat.for().
The chat code could not be downloaded or verified. It is loaded like the stream engine, in the same version as the stream’s engine. See the reasons in Errors and disconnects.
The platform refused the chat token, or the chat server could not be reached. Check your Content-Security-Policy first. On a dedicated or on-premises deployment, pass platformHost to VoiceChat.for(): it is not taken from the stream.
The browser did not give the microphone: the viewer refused the prompt, there is no device, or another app is using it. The deviceError event says which. toggleMic() also resolves to false before join().
Browsers block sound until the viewer interacts with the page. The SDK starts the audio on the first click, tap or key press.
Chat is not in the script-tag build. Install the package with npm and use a bundler.

Next steps

Shared sessions

One app for many people: the natural place for chat.

Talk to your Unreal app

Messages between your page and the app, such as comms.

The engine and updates

One level up: how the stream engine and the chat code are loaded and verified.

Stream API

Reference: voiceToken and everything else on the stream object.