npm SDK

Install

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

socket.io-client is only needed for live updates. Set your integration type to npm SDK to get a client secret. It's shown once, so store it in an environment variable straight away.

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

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

Demo app

A complete Express app that signs people in with Vortex, shows your guild's channels and recent messages, and lets them send messages. Download it, put your client ID and secret in .env, add http://localhost:3000 to your Domains, then run npm install and npm start.

Log in with Vortex

The standard OAuth flow: send people to Vortex, they approve, and Vortex sends them back to your redirectUri with a code you swap for tokens.

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

const app = express();
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));

const vortex = new Vortex({
  clientId: "vtx_your_client_id",
  clientSecret: process.env.VORTEX_CLIENT_SECRET,
});
const redirectUri = "https://yoursite.com/auth/vortex/callback";

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

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

  const tokens = await vortex.exchangeCode({
    code: req.query.code,
    redirectUri,
    codeVerifier: saved.codeVerifier,
  });
  // tokens.user is the Vortex profile: { id, username, avatar, rank, color, ... }
  await db.users.upsert({ vortexId: tokens.user.id, username: tokens.user.username, tokens });
  req.session.userId = tokens.user.id;
  res.redirect("/");
});

• The redirectUri must be on an allowed site. For servers, add your domain under Domains or your server's IP under Server IPs. See Site access.
• Always check state. It stops other sites from finishing a sign-in on your users' behalf.
• If someone cancels, Vortex returns ?error=access_denied.

Acting as a user

Wrap a person's tokens in a session. It refreshes access tokens automatically and tells you when to save new ones.

const user = vortex.forUser(savedTokens, {
  onRefresh: (tokens) => db.users.update({ vortexId }, { tokens }),
});

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

Acting as your app

App sessions don't need a person. Use them for bots, syncing and announcements.

const bot = vortex.app();

const { channels } = await bot.guild();
const { messages } = await bot.messages(channels[0].id);
await bot.announce(channels[0].id, "Server restarts in 10 minutes!");

Announcements appear as highlighted system messages with your app's name. They're limited to 10 per minute.

Live updates

Both user and app sessions can connect for live events. By default you join every channel the session can see.

const live = await vortex.app().connect();

live.on("ready", () => console.log("Connected"));
live.on("message", (msg) => {
  console.log(`#${msg.channelId} ${msg.author.username}: ${msg.content}`);
});
live.on("error", (err) => console.error(err.message));

// Later
live.leave(channelId);
live.close();

Connections reconnect and renew their tokens on their own.

Reference: Vortex

new Vortex(options)

Methods

Tokens

{
  accessToken: "eyJ...",
  refreshToken: "vtxr_...",   // null for app tokens
  expiresAt: 1767225600000,   // ms timestamp
  scopes: ["identify", "chat.read", "chat.write"],
  user: { ... }               // only from exchangeCode
}

Reference: sessions

Both sessions

UserSession

Moderation methods need guild.moderate on app sessions (included by default), or the right guild role on user sessions. See the moderation API for the rules. Display vortexStaff, timeout status and Vortex mute status when showing profiles.

Partners must show a rules popup with an accept button, keep the rules viewable, report messages through report(), and never send a message as a user who did not write it.

AppSession

Realtime

The Message, Channel, Guild and User shapes are in the API reference. The SDK's Message matches the CDN script's, minus html and mentionsMe.

Errors

Everything throws VortexError, with the HTTP status and response body when there is one.

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

try {
  await user.send(channelId, text);
} catch (err) {
  if (err instanceof VortexError && err.status === 429) {
    // slowmode or rate limit, try again later
  }
}

Troubleshooting

"This site can't use this integration yet" on the Vortex sign-in page

Your redirectUri's domain isn't allowed. Add it under Domains.

"redirect_uri mismatch"

Pass exactly the same redirectUri to exchangeCode as you did to getAuthorizeUrl.

"Invalid or expired refresh token"

An old refresh token was reused. Make sure onRefresh saves new tokens, and that two servers don't refresh the same tokens at once.

"Realtime needs socket.io-client"

Run npm install socket.io-client.