Everything starts with an app. An app on its own gives you "Log in with Vortex". Turn on a guild for it and your guild's channels, roles, bans and moderation settings are what people see and use on your site, and anything they send shows up in Vortex too.
Apps and guilds
| App without a guild | App with a guild | |
|---|---|---|
| Sign in with Vortex | Yes | Yes |
| Chat, channels and roles | No | Yes |
| Connections | CDN script, npm SDK | Embed, CDN script, npm SDK |
| Bans | From the app's Bans section | From the guild's Moderation section |
Partners with guild access can turn on a guild from the app's Advanced section, or pick Embed chat when creating the app to get one right away.
Choose a connection
vortex.send and vortex.onmessage.
npm SDK
Full control from your Node.js server, including your own "Log in
with Vortex" and bots.
| Embed | CDN script | npm SDK | |
|---|---|---|---|
| Setup | Paste an iframe | Add a script tag | Install a package |
| UI | Ready-made, styled in your app's settings | Yours | Yours |
| Runs in | Browser (Vortex iframe) | Browser (your page) | Your server |
| Sign in | Vortex popup | Redirect or popup to Vortex | Your own "Log in with Vortex" flow |
| Client secret | No | No | Yes, server only |
| Needs a guild | Yes | Only for chat | Only for chat and app tokens |
| Act as your app | No | No | Yes (read channels, post announcements) |
| Best for | Adding chat to a page fast | Custom chat widgets | Apps with accounts, bots, sync |
You can switch types any time from your app's Connection section. Your app, guild, channels and members stay the same.
Quick start
- Join the Partner Program. Apply from Become a Partner. Once you're accepted, your apps live under Partner Tools → Your Apps.
- Create an app. Pick how it connects: CDN script, npm SDK, or Embed chat (which creates a guild). You get a client ID (public) and, for the SDK, a client secret (keep it on your server).
- Set up your guild, if you have one. Create channels and roles, and set a default role for new members.
- Allow your sites. Under Where it works, either allow any website or add your site tag, domains or server IPs. See Site access.
- Add it to your site by following the guide for your type.
Signed in as a partner: code samples on these pages use your client
ID, .
How it works
Your guild is the source
For apps with a guild, channels, roles, permissions, bans, slowmode and the profanity filter all come from that guild. When someone signs in on your site for the first time they join your guild with its default role. Banning someone in your guild blocks them on your site as well.
People sign in with Vortex
Your site never sees passwords or email addresses. People approve your app in a Vortex window that shows its name, icon, links and the site they're on. They can disconnect any time from Settings → Connected Apps, which signs them out everywhere your app is used.
Test and production mode
New apps start in test mode: only the app's owners and Vortex staff can sign in. When you're ready to launch, ask the team to switch it to production so everyone can use it.
Co-owners
Invite up to 5 friends to help manage an app from its Owners section. They can change settings, sites and the guild once they accept. Only the owner can invite people, turn on a guild or delete the app.
Scopes
If you don't ask for specific scopes, you get identify,
plus chat.read and chat.write when your app
has a guild.
| Scope | Lets you | Used by |
|---|---|---|
identify |
See the person's username, avatar, rank and name color | All apps |
chat.read |
Read messages in your guild's channels | Apps with a guild |
chat.write |
Send, edit, delete and report messages as that person, and use any moderator permissions their guild roles give them | Apps with a guild |
guild.read |
Read your channels and messages as your app | SDK app tokens, with a guild |
guild.announce |
Post announcements as your app | SDK app tokens, with a guild |
guild.moderate |
Timeout, ban and unban members, and manage their roles, as your app | SDK app tokens, with a guild |
Tokens
-
Access tokens last 1 hour and are sent as
Authorization: Bearer .... - Refresh tokens last 30 days and change every time you use one. Reusing an old refresh token signs that session out, so always save the newest one.
- Sign-in codes last 2 minutes and work once.
The CDN script and SDK refresh tokens for you.
Safety built in
- Every sign-in window shows which website is asking, and people can report the app from it.
- Embeds and the CDN script use PKCE, so a stolen sign-in code is useless.
- Only sites you allow can use your app. You can block any site at any time.
- Messages from your site go through the same moderation as Vortex itself.
Limits and rules
- You can own 1 app, or 3 with Nexus. Each app can have one guild.
- Messages are up to 2000 characters. Slowmode and per-user rate limits apply.
- App announcements are limited to 10 per minute.
- Up to 100 domains and 25 server IPs per app.
- Your site must not pretend to be Vortex or collect Vortex passwords. Partners must follow the Partner Policy, the Terms of Service and the Community Guidelines, including actively moderating their app and guild.
Getting help
Check the troubleshooting section at the end of each guide first. For anything else, reach the team on Discord.