Chat

Overview

The Chat module provides a unified, multi-platform chat system that aggregates messages from Twitch, YouTube, Kick, and Trovo into a single real-time stream. It supports message history with pagination, moderation actions (bans, timeouts, message deletion), user profiles with enrichment data from a ProfileService, moderator notes, emote rendering (Twitch, 7TV, BTTV, FFZ), polls, predictions, and raid management. Messages are buffered in Redis, flushed to TimescaleDB in batches, and broadcast to all connected WebSocket clients in real time.

Architecture

Backend

• GraphQL (apps/api/src/graphql/chat.rs) -- Queries for chat history, message count, user profiles, emotes, moderation log, and moderator notes. Mutations for sending messages, moderation actions, and CRUD on user notes.
• Crate (crates/lo-chat/src/) -- Core chat logic including ChatBuffer (Redis-backed message buffering), ChatFilter/ChatMessageInput types, ProfileService (caching + circuit breaking for platform API enrichment), emote set types, moderation log, and platform user management.
• Database -- Chat messages are stored in TimescaleDB (platform_chat_messages hypertable). Platform users are tracked in PostgreSQL (platform_users). Moderator notes in platform_user_notes. Moderation log entries in moderation_log.
• YouTube Member Badges -- Custom-tier-badge image URLs are sourced from YouTube's internal InnerTube endpoint (the public Data API does not expose them) and cached in Redis. Inline-enriched into platform_chat_messages.badges at INSERT time so chat history scrollback renders correctly. See Member Badges for the full architecture, configuration, and GDPR considerations.
• Real-time -- Messages are broadcast via Redis pub/sub to all WebSocket subscribers for the account. The PendingChatAccounts state tracks which accounts have buffered messages needing flush.

Frontend

• Next.js API proxy routes call GraphQL internally; browser hooks use the /api/chat/* proxy and keep popout-token support on every fetch.
• The Multichat UI renders messages with emotes, badges, colors, reply threading, platform/broadcast filters, keyword tabs, rule colors, per-user highlight colors (each highlighted user carries its own colour — the shared highlight token by default, a custom colour, or switched off to park the entry — edited in a colour dialog opened from the chip's colour button, with a live preview and an explicit Apply/Cancel), notification sounds (per keyword rule, plus one fixed sound for the whole highlighted-user list — a keyword rule's sound wins when a message matches both), and hidden/deleted-message display controls.
• The tab bar (platform + keyword tabs) is a single horizontally-scrolling row: it never wraps to a second line, so a crowded bar or a narrow pop-out costs no chat height. Desktop shows edge arrows and fades only while the row overflows; touch swipes instead. The + (new rule) and gear (settings) are anchored outside the scroll area. The active tab scrolls into view on selection and on reload-restore. Keyword tabs are drag-sortable on a mouse (@dnd-kit, 5px activation so a click still selects); touch keeps the Filters-list up/down arrows — both persist into the same keywordTabs order.
• User info modal fetches a unified profile combining DB data with live platform API enrichment. Its message history still shows rows that the feed hides as deleted, so moderators keep audit context. From the chat (not the event feed), it also carries one-click Highlight / Hide buttons that write the same name-based, cross-platform rule as the Filters tab via the shared @lumio/chat-filters toggle helpers (toggleHighlightUser is three-valued — add / switch a parked entry back on / remove — so a second click never stacks a duplicate); the buttons are prop-gated on a filters setter, so the event-feed variant of the card never offers a folgenlos toggle.
• Chat filters and keyword tabs live in localStorage with an account-scoped key plus an unscoped mirror for token popouts; the shared @lumio/chat-filters matcher keeps dashboard and popout behavior identical. A storage-event listener re-reads the filter/tab keys when another document writes them, so a Highlight/Hide toggle made in the OBS popout reaches the dashboard tab (and vice-versa) without a reload.

API

GraphQL Queries

Query	Permission	Description
chatHistory(filter: ChatFilterInput)	chat:read	Paginated chat message history with filters for platform, user, date range, keyword search, and YouTube liveChatId (broadcast-level)
chatMessageCount	chat:read	Total message count for the account
platformUserProfile(platform, platformUserId)	chat:userinfo	Unified user profile with platform API enrichment via ProfileService
searchPlatformUsers(query, platforms, limit)	chat:userinfo	Prefix-search the account's known chatters by username/display name for the filter name-completion (min 2 chars, else empty; capped at 25)
emotes(platform, channelId)	chat:read	Emote sets for a platform/channel (Twitch, 7TV, BTTV, FFZ, Trovo, Discord)
userEmotes	chat:read	Twitch emotes available to the authenticated user (subs, globals, follower)
platformUserNotes(platform, platformUserId)	chat:notes	List moderator notes for a platform user
moderationLog(platform, platformUserId, page, limit)	chat:userinfo	Moderation action history for a user

GraphQL Mutations

Mutation	Permission	Description
sendChatMessage(input: ChatMessageInputGql!)	chat:write	Buffer a chat message in Redis and broadcast via pub/sub
sendChatToPlatform(input: SendToPlatformInput!)	chat:write	Send a chat message to a platform (twitch, youtube, kick, trovo). The message is authored by the logged-in user's platform identity (their Twitch/Google login), so they need a login connection for the target provider. The target chat is the broadcaster's stream — for YouTube the active liveChatId is read from the polling worker's Redis cache (same source as youtubeActiveStreams), so invited members can post even though they themselves have no active stream. With multiple concurrent broadcasts the caller must pass liveChatId to choose which one to post to.
createPlatformUserNote(platform, platformUserId, note)	chat:notes	Create a moderator note on a user
updatePlatformUserNote(noteId, note)	chat:notes	Update an existing moderator note
deletePlatformUserNote(noteId)	chat:notes	Delete a moderator note
updateUserTreatment(platform, platformUserId, treatment)	chat:ban	Update chat user treatment (none, active_monitoring, restricted); Twitch syncs to Helix best-effort
moderateChat(input: ModerationInput!)	chat:ban / chat:timeout / chat:delete	Perform a moderation action (ban, timeout, delete) on Twitch, YouTube, Kick, or Trovo. Permission checked per action type. YouTube auto-resolves the active liveChatId from the polling worker's Redis cache when not supplied. After a successful ban/timeout the server soft-deletes every message from the affected user and broadcasts a chat:clear_user WebSocket event so all connected clients grey those messages out — same UX as the platform's native chat. Platform capability differs: Twitch and YouTube support delete + timeout + ban; Kick supports delete only; Trovo's moderation API is not publicly available, so no moderation action succeeds there. When a platform rejects an action the mutation returns success: false with a human-readable details reason (as HTTP 200, not an error) — the client surfaces that reason and leaves the user's messages untouched.
cancelRaid	chat:raid	Cancel a pending Twitch raid
endPoll(pollId, status?)	chat:poll	End an active Twitch poll (status defaults to TERMINATED)
endPrediction(predictionId, status, winningOutcomeId?)	chat:prediction	End/cancel a Twitch prediction (RESOLVED requires winningOutcomeId)

REST Endpoints

All paths live under /v1. Bodies are snake_case and mirror the GraphQL inputs.

Method	Path	Permission	Description
GET	/v1/chat/history	chat:read	Paginated chat history (filter by platform, user, date, keyword search, YouTube live_chat_id)
GET	/v1/chat/history/count	chat:read	Total message count for the account
POST	/v1/chat/message	chat:write	Ingest/buffer a message (bot-facing)
POST	/v1/chat/send	chat:write	Send a chat message to a connected platform
POST	/v1/chat/moderate	chat:ban / chat:timeout / chat:delete	Ban, timeout, or delete on twitch / youtube / kick / trovo (permission resolved per action). Mirrors the GraphQL moderateChat mutation 1:1 — same fields, same auto-resolve of live_chat_id for YouTube, same chat:clear_user broadcast on ban/timeout.
DELETE	/v1/chat/raid	chat:raid	Cancel the current Twitch raid
DELETE	/v1/chat/poll	chat:poll	End the current Twitch poll
DELETE	/v1/chat/prediction	chat:prediction	Lock/resolve the current Twitch prediction
GET	/v1/chat/users/search	chat:userinfo	Prefix-search known chatters by username/display name for the filter name-completion. ?q= (min 2 chars, else empty), optional ?platform= (comma-separated), ?limit= (capped at 25). Mirrors GraphQL searchPlatformUsers 1:1.
GET	/v1/chat/users/{platform}/{platform_user_id}	chat:userinfo	Unified user profile (DB + enrichment)
GET	/v1/chat/users/{platform}/{platform_user_id}/moderation-log	chat:userinfo	Moderation action history
GET	/v1/chat/users/{platform}/{platform_user_id}/notes	chat:notes	List moderator notes
POST	/v1/chat/users/{platform}/{platform_user_id}/notes	chat:notes	Create a moderator note
PATCH	/v1/chat/users/{platform}/{platform_user_id}/notes/{note_id}	chat:notes	Update a moderator note
DELETE	/v1/chat/users/{platform}/{platform_user_id}/notes/{note_id}	chat:notes	Delete a moderator note
PUT	/v1/chat/users/{platform}/{platform_user_id}/treatment	chat:ban	Set user treatment (none, active_monitoring, restricted)

Keyword search

chatHistory accepts a keyword search filter so a keyword tab can pull older matches from TimescaleDB instead of only what is left in the in-browser buffer. It is exposed as ChatFilterInput.search (GraphQL, [String!]) and as the comma-separated search query parameter on GET /v1/chat/history (REST, e.g. ?search=hello,world). A message is a candidate when its body contains any of the keywords (case-insensitive substring). The server predicate is a coarse message ILIKE-any-keyword — a deliberate superset of the shared @lumio/chat-filters matcher, which the client re-checks so live and back-loaded messages judge identically.

• Always time-bounded. A keyword search never scans the whole hypertable: it always carries a lower time bound — the caller's from when supplied, otherwise the last 12 hours. Plain (non-search) history queries are unchanged and impose no implicit floor. Because a keyword search is capped to a window and the daily retention sweep bounds the data, "no older matches in the window" is an expected, ordinary end state.
• Bounded input. At most 20 keywords, each at most 100 characters (after trimming and dropping blanks). A violation returns 400 BAD_REQUEST with the identical message on GraphQL and REST — the shared lo_chat::validate_search_terms backs both. Wildcard metacharacters (%, _) inside a keyword match literally. REST splits the single search query parameter on commas, so a keyword that itself contains a comma cannot be expressed through REST; use GraphQL ChatFilterInput.search: [String!] for comma-containing keywords.
• No new permission or flag. search only narrows the existing history surface, which is already gated on chat:read + feature:multichat.

The client side (useMultichat / Multichat) drives this window:

• Per-tab paging. loadMore runs in two modes: for a keyword tab it pages the keyword search window (from seeded once at 12 h on first open); otherwise it pages the general history. Paging state (page / hasMore) is kept per view so one tab never inherits another's exhausted end.
• Capped follow-on. A candidate page can yield zero visible rows (the server pre-filter is a superset of the matcher). The infinite-scroll keeps loading — hard-capped at 5 pages per trigger — until a row matches or the window is exhausted, so a keyword with no recent hits never loops. Back-loaded rows are tagged __source: "history" (client-only) and merged by created_at with dedupe on platform_message_id ?? id, keeping the list chronological and duplicate-free; the same MAX_MESSAGES = 500 cap applies to the prepend path, trimmed at the newest end.
• Reliable end state. The BFF (/api/chat/history) passes the GraphQL total / page / pages through, so hasMore is read from page < pages rather than guessed from the page length; a failed first fetch leaves paging retryable instead of permanently off.

Name completion (searchPlatformUsers)

The Hidden users and Highlighted users filter lists offer an @-completion bound to the account's real chatter base — the platform_users table, which upsert_platform_user writes on every incoming message. searchPlatformUsers (GraphQL) and GET /v1/chat/users/search (REST) back it, returning the slim { platform, platformUserId, username, displayName, avatarUrl, lastSeenAt, messageCount } shape.

• Prefix match, both name columns. Case-insensitive prefix (prefix%) on username and display_name. %, _, and \ in the query match literally (the same escaping as member search). Ordered last_seen_at DESC, message_count DESC — whoever wrote most recently ranks first.
• Minimum two characters. A query shorter than 2 characters (after trimming) returns an empty list, not an error — the UI queries on every keystroke. platforms (GraphQL [String!], REST comma-separated ?platform=) restricts the platforms; omit for all. limit is hard-capped at 25 regardless of the requested value.
• Same guard as the profile query. feature:multichat + chat:userinfo, identical to platformUserProfile, so the completion never surfaces a user the caller could not already inspect — and without chat:userinfo the search returns nothing (no data leak). The account is always derived server-side from the (cookie or popout) token, never from a client parameter, so a popout with ?token=lm_pop_* gets results without sending an account id.
• Indexed prefix. Backed by (account_id, lower(username) text_pattern_ops) and the matching display_name index (20260805000001_platform_users_search_prefix_index) so a per-keystroke prefix lookup range-scans instead of full-scanning the monotonically growing, never-pruned table. The predicate uses lower(col) LIKE … (not ILIKE) to match the index expressions exactly.
• All four platforms populate it. Twitch, YouTube, Kick, and Trovo all upsert_platform_user on their chat path, so a chatter on any platform appears in the completion after their first message. (Trovo's chat-path upsert was added in ZAF-294; it previously only broadcast chat.)

Permissions

Permission	Description
chat:read	Read chat messages, view emotes
chat:write	Send/ingest chat messages
chat:userinfo	View user profiles, follow status, moderation log
chat:delete	Delete chat messages
chat:ban	Ban/unban chat users
chat:timeout	Timeout chat users
chat:notes	Manage moderator notes on platform users
chat:raid	Cancel raids
chat:poll	End polls
chat:prediction	End predictions

Database

Table	Database	Description
platform_chat_messages	TimescaleDB	Chat messages hypertable with compression. Fields: id, account_id, platform, channel_name, user_id, username, display_name, message, emotes (JSONB), badges (JSONB), color, is_mod, is_sub, is_vip, sub_tier, platform_message_id, reply fields, deleted_at, deleted_by, action, action_duration_secs. created_at is populated from the platform timestamp (YouTube publishedAt, Twitch metadata.message_timestamp, Kick webhook created_at, Trovo send_time) so re-ingested backlog stays chronologically aligned across platforms. A partial UNIQUE index on (account_id, platform, platform_message_id, created_at) makes ingestion idempotent — workers re-fetching the live-chat backlog after a restart no longer create duplicates. The action column records why a row was hidden ("ban", "timeout", "delete"); action_duration_secs carries the timeout length. Both survive a page refresh so the UI keeps rendering "Hidden by X" / "Blocked 5min by X" instead of the generic "Deleted by X". The live_chat_id column stores the YouTube live chat ID for broadcast-level filtering, enabling the Multichat to show messages from a specific broadcast when multiple YouTube streams are active simultaneously.
platform_users	PostgreSQL	Platform user profiles with ban status, treatment, follower info, enrichment timestamps
platform_user_notes	PostgreSQL	Moderator notes on platform users (created_by, created_by_name)
moderation_log	PostgreSQL	Log of moderation actions (ban, timeout, delete) with target user/message, moderator, reason, duration

Data Flow

1. Platform adapter (Twitch IRC, YouTube live chat, etc.) receives a message.
2. Message is sent to the API via sendChatMessage GraphQL mutation.
3. Message is buffered in Redis via ChatBuffer::push().
4. Message is broadcast via Redis pub/sub to all connected WebSocket clients.
5. PendingChatAccounts tracks the account for the background flush worker.
6. Flush worker periodically (every 5s) writes buffered messages from Redis to TimescaleDB in batches.
7. Frontend receives the message via WebSocket and renders it with emotes and badges.

Flush durability

ChatBuffer::flush() reads and deletes an account's Redis buffer atomically, so the drained batch is briefly the only surviving copy. Two safeguards keep that copy from being lost:

• Re-queue on failed INSERT. If the batch INSERT fails, the flush worker re-queues the drained messages onto the Redis buffer (ChatBuffer::requeue) and re-arms the account so the next tick retries, instead of dropping them. Because ingestion is idempotent (the partial UNIQUE index → ON CONFLICT DO NOTHING), a retry after a partial insert never duplicates rows. Only if Redis is also unreachable are the messages genuinely lost, and that path logs loudly.
• Restart recovery. The pending-account set is in-process, so an API restart would otherwise orphan any buffer whose account does not chat again. On startup the flush worker scans Redis (SCAN lumio:chat:buffer:*) and re-seeds the pending set (ChatBuffer::pending_account_ids), so buffers written before the restart are still drained.

ChatMessageInput.user_treatment is a live-broadcast-only snapshot and is intentionally not persisted per message — the durable source is the platform_users.user_treatment column, read back by the profile/GraphQL layer on load.

Retention

Each plan advertises a chat retention window via plans.chat_retention_days (shown in Admin and on billing). Enforcement is handled by a background sweep (apps/api/src/workers/chat_retention.rs) that hard-deletes rows in the platform_chat_messages hypertable older than each account's plan window.

• Per-account, not a table-wide TimescaleDB policy. Retention is plan-dependent while add_retention_policy is table-wide, so the sweep resolves each account's window (api::db::plans::list_account_chat_retention) and issues a per-account delete (lo_chat::delete_old_messages). The (account_id, created_at DESC) index keeps each delete cheap.
• Per-account override respected. The effective window is the account's account_limits.chat_retention_days override when set, otherwise the plan's plans.chat_retention_days — the same COALESCE(override, plan) precedence the admin limits API applies. An account granted extended retention is never purged on the shorter plan default.
• chat_retention_days = 0 = keep forever. Those accounts are excluded from the sweep entirely.
• Config-gated. The worker only runs when chat.retention_enforcement_enabled is true. It is disabled by default (dev/test/staging keep their history so test data is not purged too quickly) and enabled in production (config/production.toml). Cadence is chat.retention_sweep_interval_secs (default 86400 = daily); a sweep also runs once on startup.

Setting	ENV	Default
chat.retention_enforcement_enabled	LUMIO__CHAT__RETENTION_ENFORCEMENT_ENABLED	false (dev) · true (production)
chat.retention_sweep_interval_secs	LUMIO__CHAT__RETENTION_SWEEP_INTERVAL_SECS	86400

Deletion is permanent — retention runs in addition to moderation soft-deletes (which only set deleted_at/deleted_by and keep the row).

Erasure (GDPR Art. 17)

Retention is time-driven and plan-scoped; erasure is event-driven and removes a data subject's chat PII immediately, independent of any retention window. platform_chat_messages stores the raw message text, username/display_name, avatar_url, the platform user_id, and identity badges/emotes (JSONB) — all personal data. Two paths hard-delete it (api::services::chat_privacy):

• On account dissolution. POST /v1/accounts/{id}/dissolve (and the GraphQL dissolveAccount) erase every platform_chat_messages row for the account before deleting the account itself. The table lives in TimescaleDB, so the main-database DELETE FROM accounts … CASCADE never reaches it; purging first also avoids orphaned rows that the retention sweep — which only resolves windows for accounts that still exist — could never reach.
• On data-subject request. POST /v1/admin/privacy/chat/erase (GraphQL eraseChatSubjectData), gated by admin:privacy-erase, hard-deletes every row authored by a subject across all accounts. The subject is identified by exactly one of lumio_user_id, or platform + user_id. The YouTube member-erasure endpoint (DELETE /v1/admin/privacy/youtube/member/{id}) additionally runs this same chat purge for the member's (platform = 'youtube', user_id) rows.

Every erasure writes a chat_pii_erasure audit event (account-scoped for a dissolution; one global event plus one per affected account for a subject request). Erasure is a hard delete, distinct from moderation soft-deletes that keep the plaintext.

Moderation Permission Matrix

Moderation availability is gated by two independent layers:

1. Actor → target hierarchy — getChatPermissions (apps/web/src/app/(main)/(app)/dashboard/chat/chat-permissions.ts) encodes each platform's role model (who may act on whom). The matrix below mirrors it.
2. Platform capability — platformSupportsModeration (apps/web/src/lib/moderation.ts) greys out actions the platform's API simply cannot perform, regardless of role. Twitch and YouTube support delete + timeout + ban; Kick supports delete only (timeout and ban are greyed out); Trovo supports no moderation actions (its API is not publicly available, so delete, timeout, and ban are all greyed out).

If an action still reaches the backend and is rejected, the mutation returns success: false with a human-readable details reason; the client shows that reason as an error toast and does not hide the user's messages. The matrix below mirrors the actor → target hierarchy:

Twitch — broadcaster, lead-mod, mod hierarchy (Twitch's three-tier model):

Actor → Target	Self	Broadcaster	Lead Mod	Mod	User
Broadcaster	only delete (own)	—	delete + ban + timeout	delete + ban + timeout	delete + ban + timeout
Lead Mod	only delete (own)	—	delete only	delete only	delete + ban + timeout
Mod	—	—	—	—	delete + ban + timeout

Lead Mods and Mods cannot ban or timeout other moderators (only the broadcaster can). Lead Mods can delete other mods' messages but not ban them.

YouTube — strict three-tier (broadcaster + mod = "staff"). YouTube's Data API rejects liveChatBans.insert / liveChatMessages.delete against staff with HTTP 403 even when the broadcaster is the actor. Lumio therefore hides the moderation dropdown entirely when the target is a moderator or the broadcaster:

Actor → Target	Self	Broadcaster	Mod	User
Any role	only broadcaster can delete own	—	—	delete + ban + timeout

UI labels also differ on YouTube — "Timeout" reads as "Vorübergehend blockieren" / "Block temporarily" and "Ban" reads as "Auf diesem Kanal ausblenden" / "Hide on this channel" to mirror YouTube Studio's wording.

Kick & Trovo — the actor → target hierarchy follows the same lenient pattern as Twitch's broadcaster ↔ mod tier (broadcaster can act against mods, mods cannot act against staff). On top of that hierarchy the platform-capability layer applies: Kick exposes only message deletion — the timeout and ban controls are greyed out; Trovo has no publicly available moderation API — delete, timeout, and ban are all greyed out. A moderator therefore sees at a glance what each platform can do instead of clicking into a server error.

Ban / Timeout Sweep (chat:clear_user)

A successful ban or timeout on any platform triggers a server-side sweep that mirrors the platform's native chat behaviour:

1. lo_chat::soft_delete_user_messages sets deleted_at, deleted_by, action ("ban" | "timeout"), and action_duration_secs on every undeleted row of the affected user.
2. The server publishes a chat:clear_user event to lumio:chat:{account_id} with payload {platform, platform_user_id, deleted_by, action, duration_secs}.
3. All connected clients (dashboard + popouts + member sessions) immediately grey out the matching messages and append the localised suffix:
   • Twitch ban → "Banned by X" / "Gebannt von X"
   • Twitch timeout → "Timed out 5min by X" / "Timeout 5min von X"
   • YouTube ban → "Hidden by X" / "Ausgeblendet von X"
   • YouTube timeout → "Blocked 5min by X" / "Vorübergehend blockiert 5min von X"

After a page refresh the suffix survives because action and action_duration_secs are persisted in platform_chat_messages.

External ban/timeout events (e.g. issued from a platform's own UI) flow through the same code path: apps/api/src/workers/twitch_eventsub.rs reacts to Twitch channel.ban notifications, and apps/api/src/routes/webhooks.rs reacts to Kick moderation.banned webhooks, each performing the identical sweep + broadcast. (Chat messages live in TimescaleDB, so the sweep targets tsdb, not the main Postgres pool.)

Single-message delete ingest

Beyond bans, individual message removals made outside Lumio are ingested so the Multichat stays in sync. Every ingested deletion follows the same invariant as Lumio's own moderation: the message is never hard-deleted — it is soft-deleted (deleted_at marker) via lo_chat::soft_delete_message and additionally recorded in the affected user's moderation log (platform, target_user_id, action, target_message_id). The soft-delete's deleted_at IS NULL guard makes ingest idempotent: a duplicate delete (e.g. an EventSub echo of a Lumio-initiated delete) flips no row and is skipped, so no duplicate log entry is written.

Platform	Single-message delete ingest	Source
Twitch	✅ moderator delete	EventSub channel.chat.message_delete (twitch_eventsub.rs). The event carries the target user + message id but not the acting moderator, so the removal is attributed generically ("moderator").
YouTube	✅ moderator delete + author retract	gRPC live-chat MessageDeletedEvent / MessageRetractedEvent and the InnerTube MessageDeleted path (youtube.rs).
Lumio	✅	moderateChat / POST /v1/chat/moderate (graphql/chat.rs, routes/chat.rs).
Kick	❌ — platform limitation	Kick's public webhook catalog exposes no message-delete event (only chat.message.sent, follows, subs, livestream status, moderation.banned). Bans still sweep the user's messages via moderation.banned.
Trovo	❌ — platform limitation	Trovo's Open Platform delivers no moderation/delete events (webhooks only channel.subscribe / channel.spell; the chat WebSocket carries only follower/subscriber/gift/spell/chat types).

YouTube Channel Emotes (display only)

Channel-custom emotes (:_yourchannel-purr: style) live inside InnerTube messageRuns and are not exposed by YouTube's Data API or our gRPC streamList. Lumio harvests them out-of-band:

Component	Role
apps/api/src/workers/youtube.rs (poll cycle)	The YouTube chat worker polls get_live_chat for chat + member badges and, from the same response, extracts channel-custom emotes (emojiId of form <channelId>/<emoteId>) via parse_emote_observations
crates/lo-chat/src/youtube_emote_cache.rs::merge_channel_emotes	Writes lumio:yt:channel_emotes:{channel_id} — JSON map :shortcut: → { id, url }, TTL identical to the badge cache (cache_ttl_seconds, default 14d). The Redis-key namespace aligns with the existing lumio:yt:tier_badges:* / lumio:yt:member:* family.
apps/api/src/workers/youtube.rs::process_text_chat	At chat ingest, scans displayMessage for :shortcut: patterns, looks up the cache, attaches matching entries to ChatMessageInput.emotes in the same JSON shape as Twitch ingest
apps/web/src/app/(main)/(app)/dashboard/chat/message-content.tsx	Existing emote renderer; per-message channel emotes take priority over the static standard-emote set (:smile:, :cry:, etc.) so a streamer's :smile: upload wins over the platform fallback

Lumio is read-only on this — we never upload emotes/badges to YouTube and we don't host the images (URLs point at yt3.ggpht.com). Cold-cache caveat: the very first occurrence of an emote on a channel may render as plain :shortcut: text until the chat worker's next InnerTube poll has populated the cache.

Key Files

Path	Description
apps/api/src/graphql/chat.rs	GraphQL queries and mutations
crates/lo-chat/src/	Core chat crate (buffer, filter, profile service, emotes, moderation)
apps/api/src/services/emotes.rs	Emote fetching from Twitch, 7TV, BTTV, FFZ, Trovo, Discord
apps/api/src/services/moderation.rs	Per-platform Twitch/YouTube/Kick moderation HTTP calls invoked from moderateChat and POST /v1/chat/moderate
apps/api/src/workers/chat_retention.rs	Config-gated background sweep that enforces per-plan chat_retention_days by deleting expired platform_chat_messages
crates/lo-chat/src/youtube_emote_cache.rs	Channel-custom emote cache (lumio:yt:channel_emotes:*) — both written and read by the YouTube chat worker
apps/api/src/workers/youtube.rs	The single YouTube chat worker: harvests member-tier badges and channel-custom emotes inline from its InnerTube poll cycle and enriches chat messages
apps/api/src/state.rs	PendingChatAccounts shared state
shared/chat-filters/src/	Shared hide/highlight and keyword-tab matcher used by dashboard, popout, and tests
apps/web/src/hooks/use-multichat.ts	Browser hook for live chat, history paging, keyword-search back-fill, token fetches, and per-tab paging state
apps/web/src/lib/chat-display.ts	Pure display filter for platform/broadcast scoping, deleted-message hiding, keyword-tab views, and hidden-message removal (default) or placeholders
apps/web/src/lib/chat-persistence.ts	Defensive localStorage persistence for chat filters, keyword tabs, and active platform selection
apps/web/src/components/keyword-tab-dialog.tsx	Keyword-rule editor for tab visibility, platform scope, match mode, color, and notification sound
apps/web/src/components/popout-settings.tsx	General/Filter settings tabs for display toggles, deleted-message visibility, hidden-message style, notification volume, and keyword-rule management