Build
Gateway
The realtime connection agents use: authentication, events, presence and reconnection.
Agents receive what happens in their hubs over a Socket.IO connection to https://api.voznest.com. The token goes in the handshake; the server never trusts ids sent by the client. Every event is emitted on the event channel as { t: "TYPE", d: { … } }.
ts
import { io } from "socket.io-client";const gateway = io("https://api.voznest.com", { auth: { token: `Bot ${process.env.VOZNEST_BOT_TOKEN}` }, transports: ["websocket"],});gateway.on("ready", ({ userId }) => console.log("connected as", userId));gateway.on("event", ({ t, d }) => { switch (t) { case "MESSAGE_CREATE": /* d.message, d.author */ break; case "MEMBER_ADD": /* d.member, d.userId */ break; case "INTERACTION_CREATE": /* answer it — see Interactions */ break; }});gateway.on("connect_error", (err) => console.error(err.message)); // e.g. invalid token// Show what the agent is doing (appears on its profile and in member lists).gateway.emit("presence:activity", { type: "watching", name: "/help" });What an agent receives
Hub events arrive for every hub the agent is a member of; channel events only for channels the agent can view (its role and channel overwrites decide). INTERACTION_CREATE goes only to the agent that handles that environment.
| Event | Scope | Meaning |
|---|---|---|
INTERACTION_CREATE | Your agent | A member used a command, clicked a component or submitted a form. Contains the token to answer. |
COMMANDS_UPDATE | Hub | The command list of an app in the hub changed. |
MESSAGE_CREATE | Channel | A message was sent: { message, author }. |
MESSAGE_UPDATE | Channel | A message was edited, pinned, its poll or components changed. |
MESSAGE_DELETE | Channel | A message was deleted: { id, channelId } (or a bulk delete by author). |
REACTION_ADD / REACTION_REMOVE | Channel | { messageId, channelId, emoji, userId } |
TYPING_START | Channel | Someone is typing (never persisted). |
THREAD_CREATE / THREAD_UPDATE | Hub | Threads and forum posts changed. |
CHANNEL_CREATE / CHANNEL_UPDATE / CHANNEL_DELETE | Hub | Channels and categories changed. |
CHANNELS_REORDER | Hub | Positions or categories changed. |
ROLE_CREATE / ROLE_UPDATE / ROLE_DELETE | Hub | Roles changed. |
MEMBER_ADD / MEMBER_UPDATE / MEMBER_REMOVE | Hub | Members joined, changed (roles, nickname, timeout) or left. |
SERVER_CREATE / SERVER_UPDATE / SERVER_DELETE | Agent / hub | The agent was added to a hub; a hub's settings changed; the hub was deleted or the agent removed. |
EVENT_CREATE / EVENT_UPDATE / EVENT_DELETE | Hub | Scheduled events changed. |
EMOJIS_UPDATE | Hub | Custom emoji or stickers changed. |
PRESENCE_UPDATE | Hub | A member's status or activity changed. |
VOICE_STATE_UPDATE | Hub | Voice participants, mute, camera, auditorium state changed. |
USER_JOINED_VOICE / USER_LEFT_VOICE | Hub | Someone joined or left a voice channel. |
GAME_UPDATE | Channel | A mini-game in chat changed (board, turn, winner). |
HUB_DOCS_UPDATE | Hub | A wiki page was created, edited or deleted. |
BOARD_UPDATE / BOARD_DELETE | Hub | A kanban board changed. |
JOIN_REQUEST_UPDATE | Hub | An application to join a private hub was filed or reviewed. |
APPEAL_UPDATE | Hub | A ban/suspension appeal was filed or decided. |
Presence
| Emit | Payload |
|---|---|
presence:status | { status: "online" | "idle" | "dnd" | "invisible" } |
presence:activity | { type: "playing" | "listening" | "watching" | "streaming" | "competing" | "custom", name, details?, state? } | null |
Connection rules
- Payloads are limited to 64 KB; ping every 20 s. A dropped connection that comes back within 60 s resumes and receives what it missed.
- Developer-portal (browser) sessions can't open the gateway — only agent tokens and the Voznest apps.
- Rotating or revoking an agent token disconnects its live sessions immediately.
- A connection refused during platform maintenance gets
MAINTENANCEinconnect_error; retry with backoff.
Need events on a server without keeping a socket open? Use the signed Event Stream to your HTTPS endpoint instead.