Livestreams

A livestream is a chat channel for an audience: a few hosts, any number of viewers. Viewers are not members, so they don't fill your member lists, unread badges or push notifications. They watch over their existing chat connection and can chat alongside the hosts. Every message is stored like any other, so it reaches your own database.

What you get

  • Hosts are the livestream's members (owners). They can send, edit and delete any message, rename the channel and switch viewer chat on or off.
  • Viewers join with one call, read the history, receive messages in real time and, unless the channel is read-only, send messages.
  • After a dropped connection the SDK joins again and fetches what the viewer missed.
  • A live viewer count.
  • No push notifications for livestream messages, and no typing indicators or read receipts for viewers.
  • History is replicated to your database (PostgreSQL, MySQL, MongoDB or HTTP endpoint) like every conversation.

Create a livestream

From your server (recommended):

import { ChatServer } from "byotalk/server";

const chatServer = new ChatServer({ secretKey: process.env.BYOTALK_SECRET_KEY! });
const live = await chatServer.conversations.create({
  type: "livestream",
  members: ["host_42"], // hosts
  ownerId: "host_42",
  name: "Launch day",
  viewersCanSend: true, // false = only hosts can send
});

Or from a host's client, when client conversation creation is enabled for the environment:

const live = await chat.livestreams.create({ name: "Launch day", hosts: ["cohost_7"] });

Watch and chat

const stream = await chat.livestreams.join(liveId);
stream.messages.items;                       // latest page
stream.on("message.new", (m) => render(m));
await stream.send({ text: "Hello from the crowd!" }); // forbidden when read-only

const viewers = await chat.livestreams.viewers(liveId);
await chat.livestreams.leave(liveId);

A connection can watch up to 10 livestreams at once.

Read-only and moderation

await chatServer.conversations.update(liveId, { viewersCanSend: false });
await chatServer.messages.delete(messageId);

Hosts can do the same from their client (PATCH /v1/conversations/{id} and message.delete). A viewer can edit and delete only their own messages.

Limits

  • Each connection may send 10 messages per second; messages in one livestream are strictly ordered.
  • Viewer connections count toward your plan's peak connections.
  • The viewer count is the number of live connections watching, not distinct people.

Protocol

Viewers use two socket frames, live.join {cid} and live.leave {cid} (see Realtime protocol). Over REST, viewers can read GET /v1/conversations/{id}, its members, messages and events, and send to POST /v1/conversations/{id}/messages.