From 0d2b7036b970c07fbbe8faf37bf52ad4b9f478f8 Mon Sep 17 00:00:00 2001 From: Styler Date: Sun, 30 Aug 2026 12:42:42 +0200 Subject: [PATCH 1/3] Document channel.chatbot.audiencequeue topic New topic page with all six audience queue events and payload schemas, sidebar and overview registration, and a changelog entry. The events mirror the legacy socket.io room so dashboard clients can switch transports without changing event handling. Claude-Session: https://claude.ai/code/session_016vv5p52Wse4wbTJ3onmFEq --- astro.config.mjs | 1 + .../2026-08-30-audience-queue-topic.mdx | 9 ++ .../topics/chatbot-audiencequeue.md | 146 ++++++++++++++++++ src/content/docs/websockets/topics/index.mdx | 1 + 4 files changed, 157 insertions(+) create mode 100644 src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx create mode 100644 src/content/docs/websockets/topics/chatbot-audiencequeue.md diff --git a/astro.config.mjs b/astro.config.mjs index 2c3baa2..13aba3a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -297,6 +297,7 @@ export default defineConfig({ label: 'Chatbot', items: [ 'websockets/topics/chatbot-status', + 'websockets/topics/chatbot-audiencequeue', 'websockets/topics/chatbot-counters', 'websockets/topics/chatbot-modules-emotecombo', 'websockets/topics/chatbot-modules-pyramid', diff --git a/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx new file mode 100644 index 0000000..3cabcac --- /dev/null +++ b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx @@ -0,0 +1,9 @@ +--- +title: New channel.chatbot.audiencequeue topic +description: Audience queue (viewer queue) events are now published over the Astro gateway, with the same event names and payloads as the legacy socket.io room. +date: 2026-08-30 +--- + +The new [`channel.chatbot.audiencequeue`](/websockets/topics/chatbot-audiencequeue) topic delivers audience queue events in real time: queue opened, updated, and closed, plus member joins, selections, and removals. + +Events keep the same names and payloads as the legacy socket.io room `audience-queue::{channelId}`, so existing clients can switch transports without changing their event handling. diff --git a/src/content/docs/websockets/topics/chatbot-audiencequeue.md b/src/content/docs/websockets/topics/chatbot-audiencequeue.md new file mode 100644 index 0000000..109de18 --- /dev/null +++ b/src/content/docs/websockets/topics/chatbot-audiencequeue.md @@ -0,0 +1,146 @@ +--- +title: Audience Queue +description: "Real-time audience queue (viewer queue) events for queue lifecycle and member changes" +wsTopic: 'channel.chatbot.audiencequeue' +scope: 'bot:read' +keywords: +- StreamElements +- WebSocket +- audience queue +- viewer queue +- queue +- chatbot +- real-time +--- + +This topic carries every audience queue event: queue lifecycle changes and member changes. The audience queue backs the chatbot's [Viewer Queue](/chatbot/modules/viewerqueue) module and the `!queue` command. + +Events keep the same names and payloads as the legacy socket.io room `audience-queue::{channelId}`, so clients can switch transports without changing their event handling. + +## Payload + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `room` | `string` | Channel ID | +| `data.event` | `string` | Event type (e.g., `audience-queue:created`) | +| `data.payload` | `object` | Event-specific payload data | + +## Example + +```json +{ + "id": "01KC4840ZZ1BAMK5R2V9QX9BNA", + "ts": "2026-08-30T14:30:00Z", + "type": "message", + "topic": "channel.chatbot.audiencequeue", + "room": "577c0455f9a31ea72a36b2b3", + "data": { + "event": "audience-queue:member-enqueued", + "payload": {} + } +} +``` + +## Events + +### Queue Events + +| Event | Description | +| ----- | ----------- | +| `audience-queue:created` | A queue was opened | +| `audience-queue:updated` | Queue settings changed, or the queue was paused or resumed | +| `audience-queue:deleted` | The queue was closed | + +#### audience-queue:created + +```json +{ + "event": "audience-queue:created", + "payload": { + "isSuspended": false, + "title": "Viewer games", + "audienceMemberGroups": ["subscriber", "vip"], + "maxQueueSize": 25, + "createdAt": "2026-08-30T14:30:00Z", + "updatedAt": "2026-08-30T14:30:00Z", + "statusChangeLog": [ + { + "timeStamp": "2026-08-30T14:30:00Z", + "status": "opened" + } + ] + } +} +``` + +The payload is an [AudienceQueue](#audiencequeue) object. + +#### audience-queue:updated + +Same payload as `audience-queue:created`, with the current queue state. When the queue is paused or resumed, `isSuspended` changes and a new entry appears in `statusChangeLog`. + +#### audience-queue:deleted + +```json +{ + "event": "audience-queue:deleted", + "payload": null +} +``` + +The payload is always `null`. + +### Member Events + +| Event | Description | +| ----- | ----------- | +| `audience-queue:member-enqueued` | A member joined the queue | +| `audience-queue:member-selected` | A member was selected, by hand or at random | +| `audience-queue:member-removed` | A member was removed from the queue or the selection | + +All member events carry an [AudienceQueueMember](#audiencequeuemember) payload: + +```json +{ + "event": "audience-queue:member-enqueued", + "payload": { + "id": "12345678", + "username": "viewer123", + "displayName": "Viewer123", + "watchTime": 340, + "audienceGroups": ["subscriber"], + "position": 4 + } +} +``` + +## Data Types + +### AudienceQueue + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `isSuspended` | `boolean` | Whether the queue is paused | +| `title` | `string` | Queue title | +| `audienceMemberGroups` | `array` | Groups allowed to join: `everyone`, `vip`, `subscriber`, `follower` | +| `maxQueueSize` | `number` | Maximum number of queued members (0 = unlimited) | +| `createdAt` | `string` | Queue creation time (ISO 8601) | +| `updatedAt` | `string` | Last update time (ISO 8601) | +| `statusChangeLog` | `array` | Status history entries with `timeStamp` and `status` (`opened`, `suspended`, `unsuspended`, `closed`) | + +### AudienceQueueMember + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `id` | `string` | The member's user ID on the streaming platform | +| `username` | `string` | Username | +| `displayName` | `string` | Display name, which can differ from the username | +| `watchTime` | `number` | Watch time in minutes (Twitch only, otherwise 0) | +| `audienceGroups` | `array` | Groups the member belongs to: `everyone`, `vip`, `subscriber`, `follower` | +| `position` | `number` | Position in the queue | + +## Related + +- [Viewer Queue](/chatbot/modules/viewerqueue) - The chatbot module these events belong to +- [Chatbot Status](/websockets/topics/chatbot-status) - Chatbot connection status changes +- [Websockets](/websockets) - General information about the Astro Websocket Gateway diff --git a/src/content/docs/websockets/topics/index.mdx b/src/content/docs/websockets/topics/index.mdx index 803b322..a4c73f7 100644 --- a/src/content/docs/websockets/topics/index.mdx +++ b/src/content/docs/websockets/topics/index.mdx @@ -69,4 +69,5 @@ Unlinked topics are valid for subscription but are not yet documented. Topics ma | `channel.chatbot.timers` | `bot:read` | Chatbot timer updates | | [channel.chatbot.counters](/websockets/topics/chatbot-counters) | *(none)* | Chatbot counter value changes | | `channel.chatbot.filters` | `bot:read` | Chatbot filter updates | +| [channel.chatbot.audiencequeue](/websockets/topics/chatbot-audiencequeue) | `bot:read` | Audience queue (viewer queue) lifecycle and member events | | [channel.chatbot.timeout](/websockets/topics/chatbot-timeout) | — | User timeout notifications | From 26422d0bea8ea1e25841b20c2d95e331750afefc Mon Sep 17 00:00:00 2001 From: Styler Date: Sun, 30 Aug 2026 12:51:35 +0200 Subject: [PATCH 2/3] Use astro event naming convention Astro payloads use dot-separated event names (queue.created, member.selected, ...); the legacy socket.io names stay on the old transport. Adds a migration table mapping the two. Claude-Session: https://claude.ai/code/session_016vv5p52Wse4wbTJ3onmFEq --- .../2026-08-30-audience-queue-topic.mdx | 4 +- .../topics/chatbot-audiencequeue.md | 45 ++++++++++++------- 2 files changed, 31 insertions(+), 18 deletions(-) diff --git a/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx index 3cabcac..089ae76 100644 --- a/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx +++ b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx @@ -1,9 +1,9 @@ --- title: New channel.chatbot.audiencequeue topic -description: Audience queue (viewer queue) events are now published over the Astro gateway, with the same event names and payloads as the legacy socket.io room. +description: Audience queue (viewer queue) events are now published over the Astro gateway, with the same payloads as the legacy socket.io room. date: 2026-08-30 --- The new [`channel.chatbot.audiencequeue`](/websockets/topics/chatbot-audiencequeue) topic delivers audience queue events in real time: queue opened, updated, and closed, plus member joins, selections, and removals. -Events keep the same names and payloads as the legacy socket.io room `audience-queue::{channelId}`, so existing clients can switch transports without changing their event handling. +Payloads match the legacy socket.io room `audience-queue::{channelId}`; event names follow Astro's dot-separated convention (`queue.created`, `member.selected`, ...). The topic page has the full mapping. diff --git a/src/content/docs/websockets/topics/chatbot-audiencequeue.md b/src/content/docs/websockets/topics/chatbot-audiencequeue.md index 109de18..6c2040f 100644 --- a/src/content/docs/websockets/topics/chatbot-audiencequeue.md +++ b/src/content/docs/websockets/topics/chatbot-audiencequeue.md @@ -15,14 +15,14 @@ keywords: This topic carries every audience queue event: queue lifecycle changes and member changes. The audience queue backs the chatbot's [Viewer Queue](/chatbot/modules/viewerqueue) module and the `!queue` command. -Events keep the same names and payloads as the legacy socket.io room `audience-queue::{channelId}`, so clients can switch transports without changing their event handling. +Payloads match the legacy socket.io room `audience-queue::{channelId}`, but event names follow Astro's dot-separated convention - see the [migration table](#migrating-from-socketio) below. ## Payload | Parameter | Type | Description | | --------- | ---- | ----------- | | `room` | `string` | Channel ID | -| `data.event` | `string` | Event type (e.g., `audience-queue:created`) | +| `data.event` | `string` | Event type (e.g., `queue.created`) | | `data.payload` | `object` | Event-specific payload data | ## Example @@ -35,7 +35,7 @@ Events keep the same names and payloads as the legacy socket.io room `audience-q "topic": "channel.chatbot.audiencequeue", "room": "577c0455f9a31ea72a36b2b3", "data": { - "event": "audience-queue:member-enqueued", + "event": "member.enqueued", "payload": {} } } @@ -47,15 +47,15 @@ Events keep the same names and payloads as the legacy socket.io room `audience-q | Event | Description | | ----- | ----------- | -| `audience-queue:created` | A queue was opened | -| `audience-queue:updated` | Queue settings changed, or the queue was paused or resumed | -| `audience-queue:deleted` | The queue was closed | +| `queue.created` | A queue was opened | +| `queue.updated` | Queue settings changed, or the queue was paused or resumed | +| `queue.deleted` | The queue was closed | -#### audience-queue:created +#### queue.created ```json { - "event": "audience-queue:created", + "event": "queue.created", "payload": { "isSuspended": false, "title": "Viewer games", @@ -75,15 +75,15 @@ Events keep the same names and payloads as the legacy socket.io room `audience-q The payload is an [AudienceQueue](#audiencequeue) object. -#### audience-queue:updated +#### queue.updated -Same payload as `audience-queue:created`, with the current queue state. When the queue is paused or resumed, `isSuspended` changes and a new entry appears in `statusChangeLog`. +Same payload as `queue.created`, with the current queue state. When the queue is paused or resumed, `isSuspended` changes and a new entry appears in `statusChangeLog`. -#### audience-queue:deleted +#### queue.deleted ```json { - "event": "audience-queue:deleted", + "event": "queue.deleted", "payload": null } ``` @@ -94,15 +94,15 @@ The payload is always `null`. | Event | Description | | ----- | ----------- | -| `audience-queue:member-enqueued` | A member joined the queue | -| `audience-queue:member-selected` | A member was selected, by hand or at random | -| `audience-queue:member-removed` | A member was removed from the queue or the selection | +| `member.enqueued` | A member joined the queue | +| `member.selected` | A member was selected, by hand or at random | +| `member.removed` | A member was removed from the queue or the selection | All member events carry an [AudienceQueueMember](#audiencequeuemember) payload: ```json { - "event": "audience-queue:member-enqueued", + "event": "member.enqueued", "payload": { "id": "12345678", "username": "viewer123", @@ -139,6 +139,19 @@ All member events carry an [AudienceQueueMember](#audiencequeuemember) payload: | `audienceGroups` | `array` | Groups the member belongs to: `everyone`, `vip`, `subscriber`, `follower` | | `position` | `number` | Position in the queue | +## Migrating from socket.io + +Payloads are identical across both transports; only the event names change: + +| socket.io event | Astro event | +| --------------- | ----------- | +| `audience-queue:created` | `queue.created` | +| `audience-queue:updated` | `queue.updated` | +| `audience-queue:deleted` | `queue.deleted` | +| `audience-queue:member-enqueued` | `member.enqueued` | +| `audience-queue:member-selected` | `member.selected` | +| `audience-queue:member-removed` | `member.removed` | + ## Related - [Viewer Queue](/chatbot/modules/viewerqueue) - The chatbot module these events belong to From bdfe27a075d4d0a8ace6f5c2bde60e2ca3a72199 Mon Sep 17 00:00:00 2001 From: Styler Date: Sun, 30 Aug 2026 12:52:28 +0200 Subject: [PATCH 3/3] Drop socket.io mentions Claude-Session: https://claude.ai/code/session_016vv5p52Wse4wbTJ3onmFEq --- .../2026-08-30-audience-queue-topic.mdx | 4 +--- .../websockets/topics/chatbot-audiencequeue.md | 15 --------------- 2 files changed, 1 insertion(+), 18 deletions(-) diff --git a/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx index 089ae76..2384a8b 100644 --- a/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx +++ b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx @@ -1,9 +1,7 @@ --- title: New channel.chatbot.audiencequeue topic -description: Audience queue (viewer queue) events are now published over the Astro gateway, with the same payloads as the legacy socket.io room. +description: Audience queue (viewer queue) events are now published over the Astro gateway. date: 2026-08-30 --- The new [`channel.chatbot.audiencequeue`](/websockets/topics/chatbot-audiencequeue) topic delivers audience queue events in real time: queue opened, updated, and closed, plus member joins, selections, and removals. - -Payloads match the legacy socket.io room `audience-queue::{channelId}`; event names follow Astro's dot-separated convention (`queue.created`, `member.selected`, ...). The topic page has the full mapping. diff --git a/src/content/docs/websockets/topics/chatbot-audiencequeue.md b/src/content/docs/websockets/topics/chatbot-audiencequeue.md index 6c2040f..4674db9 100644 --- a/src/content/docs/websockets/topics/chatbot-audiencequeue.md +++ b/src/content/docs/websockets/topics/chatbot-audiencequeue.md @@ -15,8 +15,6 @@ keywords: This topic carries every audience queue event: queue lifecycle changes and member changes. The audience queue backs the chatbot's [Viewer Queue](/chatbot/modules/viewerqueue) module and the `!queue` command. -Payloads match the legacy socket.io room `audience-queue::{channelId}`, but event names follow Astro's dot-separated convention - see the [migration table](#migrating-from-socketio) below. - ## Payload | Parameter | Type | Description | @@ -139,19 +137,6 @@ All member events carry an [AudienceQueueMember](#audiencequeuemember) payload: | `audienceGroups` | `array` | Groups the member belongs to: `everyone`, `vip`, `subscriber`, `follower` | | `position` | `number` | Position in the queue | -## Migrating from socket.io - -Payloads are identical across both transports; only the event names change: - -| socket.io event | Astro event | -| --------------- | ----------- | -| `audience-queue:created` | `queue.created` | -| `audience-queue:updated` | `queue.updated` | -| `audience-queue:deleted` | `queue.deleted` | -| `audience-queue:member-enqueued` | `member.enqueued` | -| `audience-queue:member-selected` | `member.selected` | -| `audience-queue:member-removed` | `member.removed` | - ## Related - [Viewer Queue](/chatbot/modules/viewerqueue) - The chatbot module these events belong to