Skip to content

Commit 69eb0a3

Browse files
ishita1805ravindra-cloudflareswapnilmadavi
authored
feat(realtimekit): add broadcast message api (#27320)
* feat: add docs for realtime stores * fix: remove local store docs * fix: ci checks [skip style guide checks] * fix: slugs * fix: add redirects for changed slugs * fix: ci checks [skip style guide checks] * feat(wip): add release notes * feat: add release notes for realtimekit web sdks [skip style guide checks] * fix: add formatting for code blocks * chore: pull from target [skip style guide checks] * feat: add broadcast message api docs [skip style guide checks] * chore: fix lint errors * fix(commit-suggestions): added commit suggestions Co-authored-by: Swapnil Madavi <30936566+swapnilmadavi@users.noreply.github.com> * fix: use ProductReleaseNotes component for rtk release notes * fix: create a folder for release notes * fix: revert changes to productReleaseNotes * fix: revert changes to productReleaseNotes * fix: revert release notes changes * fix: revert settings.json * fix: add sdk selector to broadcast api docs * revert: pnpm lock changes --------- Co-authored-by: Ravindra Singh Rathor <rsrathor@cloudflare.com> Co-authored-by: Swapnil Madavi <30936566+swapnilmadavi@users.noreply.github.com>
1 parent 9349794 commit 69eb0a3

File tree

1 file changed

+372
-0
lines changed
  • src/content/docs/realtime/realtimekit/collaborative-stores

1 file changed

+372
-0
lines changed

‎src/content/docs/realtime/realtimekit/collaborative-stores/broadcast.mdx‎

Lines changed: 372 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,372 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Message Broadcast APIs
4+
slug: realtime/realtimekit/broadcast-apis
5+
sidebar_position: 2
6+
---
7+
8+
import RTKSDKSelector from "~/components/realtimekit/RTKSDKSelector/RTKSDKSelector.astro";
9+
import RTKCodeSnippet from "~/components/realtimekit/RTKCodeSnippet/RTKCodeSnippet.astro";
10+
11+
The broadcast APIs allow a user to send custom messages to all other users in a meeting.
12+
13+
<RTKSDKSelector />
14+
15+
### Broadcasting a Message
16+
17+
The Participants module on the meeting object allows you to broadcast messages to all other users in a meeting (or to other meetings in case of connected meetings) over the signaling channel.
18+
19+
<RTKCodeSnippet id="web-react">
20+
21+
| Param | Type | Description | Required |
22+
| --------- | ------------------------------ | -------------------------------------------------------------------------------------- | -------- |
23+
| `type` | `Exclude<string, 'spotlight'>` | Message type identifier used to distinguish different kinds of broadcasts. | Yes |
24+
| `payload` | `BroadcastMessagePayload` | Data sent with the message. Keys map to boolean, number, string, Date, or `ActiveTab`. | Yes |
25+
| `target` | `BroadcastMessageTarget` | Optional target filter for which participants or meetings receive the message. | No |
26+
27+
- If target is omitted, the message is broadcast to all participants in the current meeting, including the local participant.
28+
- If `target.participantIds` is provided, the message is sent only to those participants in the current meeting.
29+
- If `target.presetNames` is provided, the message is sent to all participants whose preset name is in the list.
30+
- If `target.meetingIds` is provided, the message is broadcast to all specified meetings (multi‑meeting broadcast).
31+
32+
```ts
33+
const participants = useRealtimeKitSelector((m) => m.participants);
34+
participants.broadcastMessage(
35+
type: Exclude<string, 'spotlight'>,
36+
payload: BroadcastMessagePayload,
37+
target?: BroadcastMessageTarget,
38+
): Promise<void>
39+
```
40+
41+
```ts
42+
type BroadcastMessagePayload = {
43+
[key: string]: boolean | number | string | Date | ActiveTab;
44+
};
45+
46+
type BroadcastMessageTarget =
47+
| { participantIds: string[] }
48+
| { presetNames: string[] }
49+
| { meetingIds: string[] };
50+
```
51+
52+
</RTKCodeSnippet>
53+
54+
<RTKCodeSnippet id="web-web-components">
55+
56+
| Param | Type | Description | Required |
57+
| --------- | ------------------------------ | -------------------------------------------------------------------------------------- | -------- |
58+
| `type` | `Exclude<string, 'spotlight'>` | Message type identifier used to distinguish different kinds of broadcasts. | Yes |
59+
| `payload` | `BroadcastMessagePayload` | Data sent with the message. Keys map to boolean, number, string, Date, or `ActiveTab`. | Yes |
60+
| `target` | `BroadcastMessageTarget` | Optional target filter for which participants or meetings receive the message. | No |
61+
62+
- If target is omitted, the message is broadcast to all participants in the current meeting, including the local participant.
63+
- If `target.participantIds` is provided, the message is sent only to those participants in the current meeting.
64+
- If `target.presetNames` is provided, the message is sent to all participants whose preset name is in the list.
65+
- If `target.meetingIds` is provided, the message is broadcast to all specified meetings (multi‑meeting broadcast).
66+
67+
```ts
68+
meeting.participants.broadcastMessage(
69+
type: Exclude<string, 'spotlight'>,
70+
payload: BroadcastMessagePayload,
71+
target?: BroadcastMessageTarget,
72+
): Promise<void>
73+
```
74+
75+
```ts
76+
type BroadcastMessagePayload = {
77+
[key: string]: boolean | number | string | Date | ActiveTab;
78+
};
79+
80+
type BroadcastMessageTarget =
81+
| { participantIds: string[] }
82+
| { presetNames: string[] }
83+
| { meetingIds: string[] };
84+
```
85+
86+
</RTKCodeSnippet>
87+
88+
<RTKCodeSnippet id="web-angular">
89+
90+
| Param | Type | Description | Required |
91+
| --------- | ------------------------------ | -------------------------------------------------------------------------------------- | -------- |
92+
| `type` | `Exclude<string, 'spotlight'>` | Message type identifier used to distinguish different kinds of broadcasts. | Yes |
93+
| `payload` | `BroadcastMessagePayload` | Data sent with the message. Keys map to boolean, number, string, Date, or `ActiveTab`. | Yes |
94+
| `target` | `BroadcastMessageTarget` | Optional target filter for which participants or meetings receive the message. | No |
95+
96+
- If target is omitted, the message is broadcast to all participants in the current meeting, including the local participant.
97+
- If `target.participantIds` is provided, the message is sent only to those participants in the current meeting.
98+
- If `target.presetNames` is provided, the message is sent to all participants whose preset name is in the list.
99+
- If `target.meetingIds` is provided, the message is broadcast to all specified meetings (multi‑meeting broadcast).
100+
101+
```ts
102+
meeting.participants.broadcastMessage(
103+
type: Exclude<string, 'spotlight'>,
104+
payload: BroadcastMessagePayload,
105+
target?: BroadcastMessageTarget,
106+
): Promise<void>
107+
```
108+
109+
```ts
110+
type BroadcastMessagePayload = {
111+
[key: string]: boolean | number | string | Date | ActiveTab;
112+
};
113+
114+
type BroadcastMessageTarget =
115+
| { participantIds: string[] }
116+
| { presetNames: string[] }
117+
| { meetingIds: string[] };
118+
```
119+
120+
</RTKCodeSnippet>
121+
122+
### Subscribe to Messages
123+
124+
Use the `broadcastedMessage` event to listen for messages sent via `broadcastMessage` and handle them in your application.
125+
126+
<RTKCodeSnippet id="web-react">
127+
128+
```ts
129+
const participants = useRealtimeKitSelector((m) => m.participants);
130+
participants.on("broadcastedMessage", ({ type, payload, timestamp }) => {
131+
// handle message
132+
});
133+
```
134+
135+
</RTKCodeSnippet>
136+
137+
<RTKCodeSnippet id="web-web-components">
138+
139+
```ts
140+
meeting.participants.on(
141+
"broadcastedMessage",
142+
({ type, payload, timestamp }) => {
143+
// handle message
144+
},
145+
);
146+
```
147+
148+
</RTKCodeSnippet>
149+
150+
<RTKCodeSnippet id="web-angular">
151+
152+
```ts
153+
meeting.participants.on(
154+
"broadcastedMessage",
155+
({ type, payload, timestamp }) => {
156+
// handle message
157+
},
158+
);
159+
```
160+
161+
</RTKCodeSnippet>
162+
163+
### Rate Limiting & Constraints
164+
165+
- The method is rate‑limited (server‑side + client‑side) to prevent abuse.
166+
- Default client‑side config in the deprecated module: maxInvocations = 5 per period = 1s.
167+
- The Participants module exposes a `rateLimitConfig` and `updateRateLimits(maxInvocations, period)` for tuning on the client, but server‑side limits may still apply.
168+
- The event type cannot be `spotlight`. This is reserved for internal use by the SDK.
169+
170+
### Examples
171+
172+
#### Broadcast to everyone in the meeting
173+
174+
<RTKCodeSnippet id="web-react">
175+
```ts
176+
const participants = useRealtimeKitSelector((m) => m.participants);
177+
await participants.broadcastMessage("HAND_RAISE", {
178+
raised: true,
179+
userId: meeting.self.userId,
180+
sentAt: new Date(),
181+
});
182+
183+
participants.on(
184+
"broadcastedMessage",
185+
({ type, payload, timestamp }) => {
186+
if (type === "HAND_RAISE") {
187+
// payload.raised, payload.userId, payload.sentAt
188+
}
189+
},
190+
);
191+
192+
````
193+
194+
</RTKCodeSnippet>
195+
196+
197+
<RTKCodeSnippet id="web-web-components">
198+
```ts
199+
await meeting.participants.broadcastMessage("HAND_RAISE", {
200+
raised: true,
201+
userId: meeting.self.userId,
202+
sentAt: new Date(),
203+
});
204+
205+
meeting.participants.on(
206+
"broadcastedMessage",
207+
({ type, payload, timestamp }) => {
208+
if (type === "HAND_RAISE") {
209+
// payload.raised, payload.userId, payload.sentAt
210+
}
211+
},
212+
);
213+
214+
````
215+
216+
</RTKCodeSnippet>
217+
218+
<RTKCodeSnippet id="web-angular">
219+
```ts
220+
await meeting.participants.broadcastMessage("HAND_RAISE", {
221+
raised: true,
222+
userId: meeting.self.userId,
223+
sentAt: new Date(),
224+
});
225+
226+
meeting.participants.on(
227+
"broadcastedMessage",
228+
({ type, payload, timestamp }) => {
229+
if (type === "HAND_RAISE") {
230+
// payload.raised, payload.userId, payload.sentAt
231+
}
232+
},
233+
);
234+
235+
````
236+
237+
</RTKCodeSnippet>
238+
239+
#### Broadcast to a specific set of participants.
240+
241+
Only the participants with those participantIds receive the message.
242+
243+
<RTKCodeSnippet id="web-react">
244+
```ts
245+
const participants = useRealtimeKitSelector((m) => m.participants);
246+
await participants.broadcastMessage(
247+
"PRIVATE_NOTE",
248+
{ message: "You are on stage in 30 seconds" },
249+
{
250+
participantIds: ["peer-id-1", "peer-id-2"],
251+
},
252+
);
253+
````
254+
255+
</RTKCodeSnippet>
256+
257+
<RTKCodeSnippet id="web-web-components">
258+
```ts
259+
await meeting.participants.broadcastMessage(
260+
"PRIVATE_NOTE",
261+
{ message: "You are on stage in 30 seconds" },
262+
{
263+
participantIds: ["peer-id-1", "peer-id-2"],
264+
},
265+
);
266+
````
267+
268+
</RTKCodeSnippet>
269+
270+
<RTKCodeSnippet id="web-angular">
271+
```ts
272+
await meeting.participants.broadcastMessage(
273+
"PRIVATE_NOTE",
274+
{ message: "You are on stage in 30 seconds" },
275+
{
276+
participantIds: ["peer-id-1", "peer-id-2"],
277+
},
278+
);
279+
````
280+
281+
</RTKCodeSnippet>
282+
283+
#### Broadcast to a preset
284+
285+
All participants whose preset name is `speaker` receive the message.
286+
287+
<RTKCodeSnippet id="web-react">
288+
```ts
289+
const participants = useRealtimeKitSelector((m) => m.participants);
290+
await participants.broadcastMessage(
291+
"STAGE_INSTRUCTION",
292+
{ text: "Prepare for Q&A" },
293+
{
294+
presetNames: ["speaker"],
295+
},
296+
);
297+
```
298+
299+
</RTKCodeSnippet>
300+
301+
<RTKCodeSnippet id="web-web-components">
302+
```ts
303+
await meeting.participants.broadcastMessage(
304+
"STAGE_INSTRUCTION",
305+
{ text: "Prepare for Q&A" },
306+
{
307+
presetNames: ["speaker"],
308+
},
309+
);
310+
```
311+
312+
</RTKCodeSnippet>
313+
314+
<RTKCodeSnippet id="web-angular">
315+
```ts
316+
await meeting.participants.broadcastMessage(
317+
"STAGE_INSTRUCTION",
318+
{ text: "Prepare for Q&A" },
319+
{
320+
presetNames: ["speaker"],
321+
},
322+
);
323+
```
324+
325+
</RTKCodeSnippet>
326+
327+
#### Broadcast across multiple meetings
328+
329+
All participants in the specified meetings receive the message.
330+
331+
<RTKCodeSnippet id="web-react">
332+
333+
```ts
334+
const participants = useRealtimeKitSelector((m) => m.participants);
335+
await participants.broadcastMessage(
336+
"GLOBAL_ANNOUNCEMENT",
337+
{ text: "The event will end in 5 minutes." },
338+
{
339+
meetingIds: ["meeting-1", "meeting-2"],
340+
},
341+
);
342+
```
343+
344+
</RTKCodeSnippet>
345+
346+
<RTKCodeSnippet id="web-web-components">
347+
348+
```ts
349+
await meeting.participants.broadcastMessage(
350+
"GLOBAL_ANNOUNCEMENT",
351+
{ text: "The event will end in 5 minutes." },
352+
{
353+
meetingIds: ["meeting-1", "meeting-2"],
354+
},
355+
);
356+
```
357+
358+
</RTKCodeSnippet>
359+
360+
<RTKCodeSnippet id="web-angular">
361+
362+
```ts
363+
await meeting.participants.broadcastMessage(
364+
"GLOBAL_ANNOUNCEMENT",
365+
{ text: "The event will end in 5 minutes." },
366+
{
367+
meetingIds: ["meeting-1", "meeting-2"],
368+
},
369+
);
370+
```
371+
372+
</RTKCodeSnippet>

0 commit comments

Comments
 (0)