メッセージブロードキャスト API

ブロードキャスト API を使うと、ミーティング内のほかの全ユーザーへカスタムメッセージを送信できます。

メッセージをブロードキャストする

meeting オブジェクトの Participants モジュールを使うと、シグナリングチャネル経由で、ミーティング内のほかの全ユーザー（接続されたミーティングがある場合は、ほかのミーティングへも）へメッセージをブロードキャストできます。

パラメーター	型	説明	必須
`type`	`Exclude<string, 'spotlight'>`	ブロードキャストの種類を区別するためのメッセージタイプ識別子です。	はい
`payload`	`BroadcastMessagePayload`	メッセージに付けるデータです。キーの値は boolean、number、string、Date、または `ActiveTab` です。	はい
`target`	`BroadcastMessageTarget`	メッセージを受け取る参加者またはミーティングを絞り込む任意のフィルターです。	いいえ

target を省略すると、ローカル参加者を含む、現在のミーティングの全参加者へメッセージがブロードキャストされます。
target.participantIds を指定すると、現在のミーティング内の該当参加者にだけメッセージが送られます。
target.presetNames を指定すると、プリセット名がその一覧に含まれる全参加者へメッセージが送られます。
target.meetingIds を指定すると、指定した全ミーティングへメッセージがブロードキャストされます（複数ミーティングへのブロードキャスト）。

const participants = useRealtimeKitSelector((m) => m.participants);
participants.broadcastMessage(
  type: Exclude<string, 'spotlight'>,
  payload: BroadcastMessagePayload,
  target?: BroadcastMessageTarget,
): Promise<void>

type BroadcastMessagePayload = {
	[key: string]: boolean | number | string | Date | ActiveTab;
};

type BroadcastMessageTarget =
	| { participantIds: string[] }
	| { presetNames: string[] }
	| { meetingIds: string[] };

パラメーター	型	説明	必須
`type`	`Exclude<string, 'spotlight'>`	ブロードキャストの種類を区別するためのメッセージタイプ識別子です。	はい
`payload`	`BroadcastMessagePayload`	メッセージに付けるデータです。キーの値は boolean、number、string、Date、または `ActiveTab` です。	はい
`target`	`BroadcastMessageTarget`	メッセージを受け取る参加者またはミーティングを絞り込む任意のフィルターです。	いいえ

target を省略すると、ローカル参加者を含む、現在のミーティングの全参加者へメッセージがブロードキャストされます。
target.participantIds を指定すると、現在のミーティング内の該当参加者にだけメッセージが送られます。
target.presetNames を指定すると、プリセット名がその一覧に含まれる全参加者へメッセージが送られます。
target.meetingIds を指定すると、指定した全ミーティングへメッセージがブロードキャストされます（複数ミーティングへのブロードキャスト）。

meeting.participants.broadcastMessage(
  type: Exclude<string, 'spotlight'>,
  payload: BroadcastMessagePayload,
  target?: BroadcastMessageTarget,
): Promise<void>

type BroadcastMessagePayload = {
	[key: string]: boolean | number | string | Date | ActiveTab;
};

type BroadcastMessageTarget =
	| { participantIds: string[] }
	| { presetNames: string[] }
	| { meetingIds: string[] };

パラメーター	型	説明	必須
`type`	`Exclude<string, 'spotlight'>`	ブロードキャストの種類を区別するためのメッセージタイプ識別子です。	はい
`payload`	`BroadcastMessagePayload`	メッセージに付けるデータです。キーの値は boolean、number、string、Date、または `ActiveTab` です。	はい
`target`	`BroadcastMessageTarget`	メッセージを受け取る参加者またはミーティングを絞り込む任意のフィルターです。	いいえ

target を省略すると、ローカル参加者を含む、現在のミーティングの全参加者へメッセージがブロードキャストされます。
target.participantIds を指定すると、現在のミーティング内の該当参加者にだけメッセージが送られます。
target.presetNames を指定すると、プリセット名がその一覧に含まれる全参加者へメッセージが送られます。
target.meetingIds を指定すると、指定した全ミーティングへメッセージがブロードキャストされます（複数ミーティングへのブロードキャスト）。

meeting.participants.broadcastMessage(
  type: Exclude<string, 'spotlight'>,
  payload: BroadcastMessagePayload,
  target?: BroadcastMessageTarget,
): Promise<void>

type BroadcastMessagePayload = {
	[key: string]: boolean | number | string | Date | ActiveTab;
};

type BroadcastMessageTarget =
	| { participantIds: string[] }
	| { presetNames: string[] }
	| { meetingIds: string[] };

メッセージを購読する

broadcastMessage で送られたメッセージは、broadcastedMessage イベントで受信し、アプリケーション側で処理します。

レート制限と制約

このメソッドには、悪用を防ぐためのレート制限（サーバー側とクライアント側）があります。
非推奨モジュールのデフォルトのクライアント側設定は、maxInvocations = 5、period = 1 秒です。
Participants モジュールは、クライアント側の調整用に rateLimitConfig と updateRateLimits(maxInvocations, period) を公開しています。ただし、サーバー側の制限は引き続き適用される場合があります。
イベントタイプに spotlight は使えません。SDK の内部用途として予約されています。

例

ミーティングの全員へブロードキャストする

const participants = useRealtimeKitSelector((m) => m.participants);
await participants.broadcastMessage("HAND_RAISE", {
	raised: true,
	userId: meeting.self.userId,
	sentAt: new Date(),
});

participants.on(
"broadcastedMessage",
({ type, payload, timestamp }) => {
if (type === "HAND_RAISE") {
// payload.raised, payload.userId, payload.sentAt
}
},
);

await meeting.participants.broadcastMessage("HAND_RAISE", {
	raised: true,
	userId: meeting.self.userId,
	sentAt: new Date(),
});

meeting.participants.on(
"broadcastedMessage",
({ type, payload, timestamp }) => {
if (type === "HAND_RAISE") {
// payload.raised, payload.userId, payload.sentAt
}
},
);

await meeting.participants.broadcastMessage("HAND_RAISE", {
	raised: true,
	userId: meeting.self.userId,
	sentAt: new Date(),
});

meeting.participants.on(
"broadcastedMessage",
({ type, payload, timestamp }) => {
if (type === "HAND_RAISE") {
// payload.raised, payload.userId, payload.sentAt
}
},
);

特定の参加者へブロードキャストする

指定した participantIds の参加者だけがメッセージを受け取ります。

const participants = useRealtimeKitSelector((m) => m.participants);
await participants.broadcastMessage(
	"PRIVATE_NOTE",
	{ message: "You are on stage in 30 seconds" },
	{
		participantIds: ["peer-id-1", "peer-id-2"],
	},
);

プリセットへブロードキャストする

プリセット名が speaker の全参加者がメッセージを受け取ります。

複数のミーティングへブロードキャストする

指定したミーティングの全参加者がメッセージを受け取ります。

const participants = useRealtimeKitSelector((m) => m.participants);
await participants.broadcastMessage(
	"GLOBAL_ANNOUNCEMENT",
	{ text: "The event will end in 5 minutes." },
	{
		meetingIds: ["meeting-1", "meeting-2"],
	},
);