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..2384a8b --- /dev/null +++ b/src/content/changelog/websockets/2026-08-30-audience-queue-topic.mdx @@ -0,0 +1,7 @@ +--- +title: New channel.chatbot.audiencequeue topic +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. 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..4674db9 --- /dev/null +++ b/src/content/docs/websockets/topics/chatbot-audiencequeue.md @@ -0,0 +1,144 @@ +--- +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. + +## Payload + +| Parameter | Type | Description | +| --------- | ---- | ----------- | +| `room` | `string` | Channel ID | +| `data.event` | `string` | Event type (e.g., `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": "member.enqueued", + "payload": {} + } +} +``` + +## Events + +### Queue Events + +| Event | Description | +| ----- | ----------- | +| `queue.created` | A queue was opened | +| `queue.updated` | Queue settings changed, or the queue was paused or resumed | +| `queue.deleted` | The queue was closed | + +#### queue.created + +```json +{ + "event": "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. + +#### queue.updated + +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`. + +#### queue.deleted + +```json +{ + "event": "queue.deleted", + "payload": null +} +``` + +The payload is always `null`. + +### Member Events + +| Event | Description | +| ----- | ----------- | +| `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": "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 |