Getting started

1. Make an application

Open the Developer Portal (in the app: Settings → Developer Portal) and choose New Application. Each application has one bot, with the same name and picture. The bot's id is the application's id, as on Discord. You can have up to 25 applications. Names are 2–32 characters, descriptions up to 190 (shown on the bot's profile).

2. Copy the token

Your bot's token is shown once, when the application is made or when you reset it. Voicaw only keeps a hash of it, so copy it somewhere safe straight away. It works like a password: anyone who has it can act as your bot.

Reset Token makes a new one. The old one stops working at once, and any gateway connections using it are closed (close code 4004).

3. Add the bot to a guild

The Installation tab builds an invite link from the permissions you tick:

https://app.voicaw.com/oauth2/authorize?client_id=123&scope=bot&permissions=3072

Whoever opens it picks one of their guilds where they have Manage Guild, can untick permissions, and adds the bot. permissions is Discord's bitfield (see Permissions). The bot gets a role of its own with those permissions, but only the ones the person adding it has. That role can be edited and moved like any other, but not deleted or given to anyone else. It goes when the bot leaves or is kicked.

A public bot (the default) can be added by anyone with the link. A private one only by you. You can take your bot out of a guild from the portal too.

4. Run it

Use any Discord library with Voicaw's addresses (see discord.js, discord.py and HTTP). Once the bot is connected to the gateway it shows as online, with a BOT tag next to its name.

import { Client, GatewayIntentBits } from 'discord.js';

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
  rest: { api: 'https://api.voicaw.com/api', cdn: 'https://api.voicaw.com/api/cdn' },
});

client.on('messageCreate', (message) => {
  if (message.content === '!ping') message.reply('pong');
});

client.login(process.env.VOICAW_TOKEN);

Deleting an application

Deleting an application takes its bot out of every guild and ends its token. Messages it sent stay, under its name.