リアルタイムの部屋
リアルタイムの部屋（チャンネル）は、名前の付いた部屋の中で、メッセージを中にいる全員へ即座に届ける通り道です。チームの作業部屋、ライブイベント、問い合わせの窓口、ゲームならロビー・パーティー・対戦などに使えます。文字のメッセージ、スタンプ、入力中の表示、「準備OK」の合図、その場のお知らせなどは、この上に作ります。マルチプレイのルームと同じ接続を使い、ONにするまではOFFです。
kumodeck features on realtimeChannels
kumodeck config push --env developmentKUMODeckはメッセージを保存しません。 メッセージは部屋にいる人へ届けたら捨てます。データベースにも、本文のログにも残さず、録音もしません。履歴を残したいアプリは、自分のFunctionsとデータベースに保存します（履歴を残すを参照）。
入る・送る#
const ch = await kumo.realtime.join('lobby'); // 入る。「@」の無い部屋は最初に入った時にできる
ch.on('message', ({ from, type, data, at }) => { … }); // from = 送った人のプレイヤーID（自分のサーバーからは 'server'）
ch.send('msg', { text: 'hi' }); // 部屋にいるほかの全員へ
ch.members; // [{ id, displayName, anonymous }]
await ch.leave();sendは送りっぱなしで使えます。awaitするとmuted、send_forbidden、rate_limited、payload_too_largeが分かります。fromはサーバーがログインから付けるので、利用者（API の名前では players = プレイヤー）がほかの人のプレイヤーIDで送ることはできません。表示名は別の話です（安全のための決まりを参照）。
| イベント | 中身 |
|---|---|
message | { from, type, data, at }（at = サーバーの時刻、ミリ秒） |
playerJoined / playerLeft | 入った人 / { playerId, reason: 'left' | 'disconnected' | 'kicked' | 'banned' | 'time_limit' } |
self | { canSend, mutedUntil } — 自分がミュートされた・解除された・送れるようになった |
closed | { reason } — left、kicked、banned、deleted、time_limit、unavailable、connection_lost、replaced、unauthorized |
kumo.realtime.channelsで入っている部屋の一覧、kumo.realtime.on('connection', …)で接続の状態が分かります。接続が切れるとSDKがつなぎ直して同じ部屋に入り直します。切れていた間のメッセージは届きません。
部屋の種類#
| 名前 | できかた | 持ち主 | 入れる人 / 送れる人 |
|---|---|---|---|
@無し（lobby、team-12） | 最初に入った利用者 | なし | 誰でも / 誰でも |
@…、利用者が作る | kumo.realtime.create({ join, send, maxMembers }) | 作った人 | 'anyone'か'invited'（持ち主の名簿） |
@…、自分のサーバーが用意する | PUT /v1/realtime/channels/@…（秘密鍵） | なし | 自分の名簿（allow、speakers）。プレイヤーIDの無い人にもopenにできる |
@で始まる部屋は、入ろうとしただけでは作られません。無ければchannel_not_foundになります。
const party = await kumo.realtime.create({ join: 'invited' }); // 名前は自動で付く。party.name を友だちに渡す
await party.invite(playerId);
// 持ち主はほかに: uninvite、allowSend / disallowSend、mute(id, { seconds })、unmute、kick、ban、unban声でも話せるようにするには、voice: trueを付けて部屋を作ります（100人まで。9人以上は中継サーバーを通す）。音声通話を参照してください。
自分のサーバーから（秘密鍵）#
自分のサーバー（たとえばFunctions）から、秘密鍵で部屋を用意する・部屋で話す・ミュート / キック / BANすることができます。委任トークンでは使えません。
| 本文 | 応答 | |
|---|---|---|
PUT /v1/realtime/channels/:name（@の名前） | { join?, send?, open?, maxMembers?, allow?, speakers? } | 設定、名簿、今いる人 |
GET /v1/realtime/channels/:name | — | 同じもの（メッセージの本文はありません） |
DELETE /v1/realtime/channels/:name | — | { deleted: true } |
POST /v1/realtime/channels/:name/messages | { type, data? } | { delivered } — from: 'server'で届く |
POST /v1/realtime/channels/:name/moderate | { op, playerId, seconds? } | {} — opは持ち主と同じ |
安全のための決まり#
- 既定では全員にプレイヤーIDがあります。 SDKがゲストとして自動でログインさせるので、ミュート・キック・BAN・送信の上限が1人ずつ効きます。
- 開いた部屋は上限が厳しくなります。 プレイヤーIDの無い人が入れるのは、自分のサーバーが
openにした部屋だけです。そこでは上限が自動で厳しくなります（人数、メッセージの大きさ、送れる回数、1回30分まで）。IDの無い人は、つなぎ直すと別人になれるためです。 - 部屋の持ち主が部屋の秩序を守ります。 部屋を作った利用者は、その部屋でミュート・キック・BANができます。自分のサーバーはどの部屋でも同じことができます。アプリからBANした利用者は、どの部屋にも入れません。
- 表示名は誰かの証明になりません。証明になるのはプレイヤーIDです。 表示名は重複できます。誰でも「運営」や部屋の持ち主と同じ名前を付けられます。持ち主や運営の印は、表示名ではなくID（
ownerId、自分のサーバーに置いたIDの一覧、自分のサーバーからのメッセージならfrom === 'server'）で出してください。 - KUMODeckは発言を録音も保存もしません。 持つのは部屋の設定、名簿、今いる人だけです。
- 発言の中身の見張りは、クリエイターの責任です。 決まり（文字数、禁止語、誰が話せるか）を決め、困った発言があればすぐにミュート・キック・BANできるようにしておいてください。
上限#
| プレイヤーIDあり | 開いた部屋 / IDなし | |
|---|---|---|
| 1部屋の人数（既定 / 最大） | 200 / 1,000 | 50 / 50 |
メッセージの大きさ（data） | 4 KB | 1 KB |
| 1人の送信 | 毎秒10（瞬間20） | 毎秒1（瞬間3） |
| 部屋全体の送信 | 毎秒50（瞬間100） | 毎秒10（瞬間20） |
| 部屋にいられる時間 | 制限なし | 30分（time_limit） |
| 1接続で入れる部屋 | 8 | 2 |
自分のサーバーからは、鍵ごとに1分あたり送信600回、そのほか（用意・ミュート・キック・BAN）300回までです。
履歴を残す#
テンプレートから作った新しいプロジェクトには、AIエージェント用のチャットの Skill（レシピ）が.claude/skills/chat/に入っています。エージェントに「履歴付きのロビーのチャットを付けて」と頼むと、いくつか質問（どの部屋か、メッセージをどう確かめるか、文字数・回数・禁止語）をしてから、自分のFunctionsとデータベースにコードを足します。保存の前に自分のサーバーがplayers.verifyで送った人を確かめるので、保存されるプレイヤーIDはいつも本当に送った人です。部屋にも先に確かめるので、部屋でミュート・BANされた人（部屋にいない人）は、自分のサーバー経由でも書き込めません。コードもデータも自分のものです。
料金#
マルチプレイのルームと同じく原価どおりです（上乗せなし）。誰かがずっと話している部屋で1時間あたり約0.6セント（人数によらずほぼ同じ）、静かな部屋はほぼかかりません。