Start here

Quickstart

A working agent with a slash command in about ten minutes — no SDK required.

This walkthrough builds the smallest useful integration: an agent that publishes a /hello command and answers it. It uses plain fetch and socket.io-client so you can see every request; the SDK wraps exactly these calls.

Where your bot runs: on your own computer, server or hosting provider — never on Voznest. The Forge only issues the identity, token and permissions; your process connects to https://api.voznest.com from wherever you host it and must stay online to answer.

1Create the projectSign in to the Forge → Projects → New project. Copy the project id from Project Settings.
2Create the agentAgents → Create the primary agent. Copy the token (qag_…) — it is shown once.
3Install it in a hub you manageInstallations → Install link, or for testing: Templates & Sandbox → Create a sandbox hub (uses the Development environment).
4Run the code belowSet VOZNEST_BOT_TOKEN and VOZNEST_APP_ID, then node quickstart.mjs.
5Try itIn the hub, type /hello, pick someone and press Enter. Your agent answers.

// quickstart.mjs — an agent with one command, using nothing but fetch + socket.io-client.// npm i socket.io-client   ·   node quickstart.mjsimport { io } from "socket.io-client";const API = "https://api.voznest.com";const TOKEN = process.env.VOZNEST_BOT_TOKEN;          // qag_… (shown once in Agents)const APP_ID = process.env.VOZNEST_APP_ID;            // your project idconst headers = { Authorization: `Bot ${TOKEN}`, "Content-Type": "application/json" };const api = (path, init = {}) => fetch(`${API}/api/v1${path}`, { ...init, headers }).then((r) => r.json());// 1. Publish the command list (replaces every global command of the project).await api(`/applications/${APP_ID}/commands`, {  method: "PUT",  body: JSON.stringify([{ name: "hello", description: "Say hello", options: [{ type: "user", name: "who", description: "Someone to greet" }] }]),});// 2. Connect to the gateway. Every event arrives as { t, d } on "event".const gateway = io(API, { auth: { token: `Bot ${TOKEN}` }, transports: ["websocket"] });gateway.on("connect", () => console.log("online"));// 3. Answer interactions within 5 seconds.gateway.on("event", async ({ t, d }) => {  if (t !== "INTERACTION_CREATE" || d.data.name !== "hello") return;  const who = d.data.options.find((o) => o.name === "who")?.value ?? d.user.id;  await fetch(`${API}/api/v1/interactions/${d.id}/${d.token}/callback`, {    method: "POST",    headers: { "Content-Type": "application/json" },    body: JSON.stringify({ type: "reply", data: { content: `👋 Hello <@${who}>!` } }),  });});

What just happened

The PUT /applications/:id/commands call stored the command; every hub where the project is installed received COMMANDS_UPDATE and shows it in the / menu.
When a member ran it, Voznest validated the options and the member's permissions, then sent your agent INTERACTION_CREATE with a one-time token.
Your reply callback posted the message as the agent. You had 5 seconds; for slow work use defer and answer within 15 minutes (see Interactions).

Next steps

Add buttons and menus — Components.
Collect input with a form — Modals.
Act on a person or message with right-click — Context-menu commands.
React to what happens in hubs — Gateway or the signed Event Stream.
Let people sign in with Voznest on your website — Access (OAuth2).

PreviousGetting Started Next Platform Concepts

Quickstart

A working agent with a slash command in about ten minutes — no SDK required.

1Create the projectSign in to the Forge → Projects → New project. Copy the project id from Project Settings.
2Create the agentAgents → Create the primary agent. Copy the token (qag_…) — it is shown once.
3Install it in a hub you manageInstallations → Install link, or for testing: Templates & Sandbox → Create a sandbox hub (uses the Development environment).
4Run the code belowSet VOZNEST_BOT_TOKEN and VOZNEST_APP_ID, then node quickstart.mjs.
5Try itIn the hub, type /hello, pick someone and press Enter. Your agent answers.

// quickstart.mjs — an agent with one command, using nothing but fetch + socket.io-client.// npm i socket.io-client   ·   node quickstart.mjsimport { io } from "socket.io-client";const API = "https://api.voznest.com";const TOKEN = process.env.VOZNEST_BOT_TOKEN;          // qag_… (shown once in Agents)const APP_ID = process.env.VOZNEST_APP_ID;            // your project idconst headers = { Authorization: `Bot ${TOKEN}`, "Content-Type": "application/json" };const api = (path, init = {}) => fetch(`${API}/api/v1${path}`, { ...init, headers }).then((r) => r.json());// 1. Publish the command list (replaces every global command of the project).await api(`/applications/${APP_ID}/commands`, {  method: "PUT",  body: JSON.stringify([{ name: "hello", description: "Say hello", options: [{ type: "user", name: "who", description: "Someone to greet" }] }]),});// 2. Connect to the gateway. Every event arrives as { t, d } on "event".const gateway = io(API, { auth: { token: `Bot ${TOKEN}` }, transports: ["websocket"] });gateway.on("connect", () => console.log("online"));// 3. Answer interactions within 5 seconds.gateway.on("event", async ({ t, d }) => {  if (t !== "INTERACTION_CREATE" || d.data.name !== "hello") return;  const who = d.data.options.find((o) => o.name === "who")?.value ?? d.user.id;  await fetch(`${API}/api/v1/interactions/${d.id}/${d.token}/callback`, {    method: "POST",    headers: { "Content-Type": "application/json" },    body: JSON.stringify({ type: "reply", data: { content: `👋 Hello <@${who}>!` } }),  });});

What just happened

The PUT /applications/:id/commands call stored the command; every hub where the project is installed received COMMANDS_UPDATE and shows it in the / menu.
When a member ran it, Voznest validated the options and the member's permissions, then sent your agent INTERACTION_CREATE with a one-time token.
Your reply callback posted the message as the agent. You had 5 seconds; for slow work use defer and answer within 15 minutes (see Interactions).

Next steps

Add buttons and menus — Components.
Collect input with a form — Modals.
Act on a person or message with right-click — Context-menu commands.
React to what happens in hubs — Gateway or the signed Event Stream.
Let people sign in with Voznest on your website — Access (OAuth2).