@vortex-chat/sdk

Server-side SDK for Vortex partner integrations. Use it to build your own Login with Vortex, read and send chat as your users, post announcements as your app, and stream realtime events. It runs on your backend only, so never ship your client secret to a browser.

Requires Node 18+. Realtime events also need socket.io-client.

npm install @vortex-chat/sdk socket.io-client

Setup

1. Open Partner Tools → Your Apps on Vortex and create an app with npm SDK as the connection (or switch an existing app to it under Connection). An app can have a guild, which adds chat, channels, roles and members. Without one it's sign-in only.
2. Copy the client ID and secret. The secret is only shown once, but you can rotate it.
3. Under Where it works, allow the site your callback runs on (for example https://yoursite.com). For backends, the Domains or Server IPs tabs work best. Any callback URL on an allowed site works, so there's no list of callback URLs to maintain.

const { Vortex } = require("@vortex-chat/sdk");

const vortex = new Vortex({
  clientId: process.env.VORTEX_CLIENT_ID,
  clientSecret: process.env.VORTEX_CLIENT_SECRET,
});

Login with Vortex

app.get("/auth/vortex", (req, res) => {
  const { url, state, codeVerifier } = vortex.getAuthorizeUrl({
    redirectUri: "https://yoursite.com/auth/vortex/callback",
  });
  req.session.vortex = { state, codeVerifier };
  res.redirect(url);
});

app.get("/auth/vortex/callback", async (req, res) => {
  const pending = req.session.vortex;
  if (!pending || req.query.state !== pending.state)
    return res.status(400).send("Bad state");
  if (req.query.error) return res.redirect("/");

  const tokens = await vortex.exchangeCode({
    code: req.query.code,
    redirectUri: "https://yoursite.com/auth/vortex/callback",
    codeVerifier: pending.codeVerifier,
  });
  // tokens.user is { id, username, avatar, rank, color, ... }
  req.session.vortexTokens = tokens;
  res.redirect("/");
});

Always check state, and keep tokens on your server. Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use, so always save the newest one.

Acting as a user

const user = vortex.forUser(req.session.vortexTokens, {
  onRefresh: (tokens) => {
    req.session.vortexTokens = tokens;
  },
});

const me = await user.me();
const channels = await user.channels();
const { messages } = await user.messages(channels[0].id, { limit: 50 });
await user.send(channels[0].id, "Hello from my site!");

Messages sent this way go through all of Vortex's normal rules (slow mode, spam protection, mutes, bans and filters) and show up on Vortex, Discord bridges and every other integration in real time.

Acting as your app

App tokens use your client secret and can only see your own guild.

const app = vortex.app();
const { guild, channels } = await app.guild();
await app.announce(channels[0].id, "Server restart in 5 minutes!");

Realtime

const live = await vortex.app().connect(); // joins every channel your guild has
live.on("message", (msg) =>
  console.log(`${msg.author.username}: ${msg.content}`),
);
live.on("delete", ({ id }) => console.log("deleted", id));
live.on("error", (err) => console.warn(err.message));

vortex.forUser(tokens).connect() works the same way and only receives what that user can see.

Moderation

Your app (with guild.moderate) and members with moderator roles can time out, ban and manage roles:

const bot = vortex.app();
await bot.timeout(userId, 60, "Spamming"); // minutes, up to 28 days
await bot.ban(userId, { reason: "Scam links" }); // add { minutes } for a temporary ban
await bot.unban(userId);
await bot.addRole(userId, roleId);
const { bans, nextCursor } = await bot.bans(); // 25 at a time
const page2 = await bot.bans({ after: nextCursor });
const { members } = await bot.members({ q: "cherry" });

The same methods work on vortex.forUser(tokens), limited to what that member's guild roles allow. Members can only act on people ranked below them, and nobody can moderate the guild owner. See the Partner Policy.

Scopes

| Scope | Grants | | ---------------------- | ---------------------------------------------------------------------------------- | | identify | Username, avatar, rank and name color | | chat.read | Read the guild's channels | | chat.write | Send, edit and delete the user's own messages, and use their moderator permissions | | guild.read (app) | Read channels and messages as your app | | guild.announce (app) | Post announcements as your app | | guild.moderate (app) | Time out, ban and unban members, and manage their roles |

If you don't pass scopes, Vortex picks the defaults for your app: identify for apps without a guild, plus chat.read and chat.write for apps with one. Vortex never shares email addresses or passwords.

Chat scopes and app tokens (vortex.app()) need a guild. Apps without one get This app has no guild from guild and chat endpoints.

Rules

• Only show Vortex data inside your integration. Don't store message history long-term or share user data with third parties.
• Make it clear your community is run by you, not by Vortex.
• Revoke tokens when a user signs out: await vortex.revoke(tokens.refreshToken).
• Follow the Partner Policy.