vsyncDOCUMENTAÇÃO

Fundamentos de Apps

Bots

Crie seu primeiro bot, entenda o token e a autenticação e saiba qual é a origem da API.

Esta página mostra como criar um bot, como ele se autentica e onde fica a API. Se você quer só o caminho mais curto, vá para os Primeiros passos.

Passo a passo: criar seu primeiro bot#

  1. Entre no site, abra Configurações de usuário e, no grupo "Configurações do app", clique em Desenvolvedores.
  2. Clique em Novo aplicativo, escolha um nome (2 a 32 caracteres) e confirme.
  3. Aparece a janela Token do bot. Copie o token agora: ele é mostrado uma única vez. Se perder, use Bot → Redefinir token (o antigo deixa de funcionar).
  4. Na aba Geral você define descrição (até 400 caracteres), tags (até 5), avatar e banner. Na aba Bot você muda o nome de usuário do bot e liga Bot público, se quiser.
  5. Abra a aba OAuth2. Marque as permissões do bot (no mínimo Ver canais e Enviar mensagens) e copie o Link gerado.
  6. Abra o link (ou cole no chat de um servidor e clique nele: abre o modal dentro do app). Escolha o servidor e clique em Continuar. Você precisa ser dono do servidor ou ter a permissão Gerenciar servidor.
  7. Rode o código. O caminho mais rápido é o projeto pronto da pasta bot/:
Bash
cd bot
npm install
cp .env.example .env     # no Windows: copy .env.example .env
# edite o .env e cole o token em VSYNC_BOT_TOKEN
npm start

Se preferir um arquivo só, use docs/examples/hello-bot.mjs (Node 20 ou mais novo, npm i ws) ou docs/examples/hello-bot.py (Python 3.10 ou mais novo). Quando aparecer "Online como ..." no terminal, vá ao chat do servidor, envie !ping ou digite /ola.

Autenticação#

Toda chamada REST do bot leva o cabeçalho:

Texto
Authorization: Bot <token>
  • Formato do token: <base64url do id do aplicativo>.<48 caracteres hexadecimais>. A API só guarda um hash; o token nunca é exibido de novo.
  • Redefinir: Desenvolvedores → seu aplicativo → Bot → Redefinir token. O token anterior para de funcionar na hora e o bot precisa ser reiniciado com o novo.
  • Segurança: nunca coloque o token no código, no Git, em prints ou em mensagens. Use variáveis de ambiente (por exemplo um arquivo .env listado no .gitignore). Se vazar, redefina.
  • Chave de assinatura: é outra credencial (aba Bot), usada só para validar requisições HTTP de interações. Veja Receber interações por HTTP.
  • Token inválido em rotas do bot devolve 401. Bots recebem 403 ("Bots não podem usar esta rota.") nas rotas pessoais: /developer, /social, /spotify, /auth, /webhooks, /oauth2/authorize, /guild-layout e /me.

Base URL#

Os exemplos usam estas variáveis:

Bash
API=https://api.vsync.lat     # origem da API (porta padrão: PORT=4000 em api/server/index.ts)
TOKEN=cole-o-token-aqui

A "base URL" é a origem da API, sem barra no final: https://api.vsync.lat.

  • REST: $API/guilds/...
  • Gateway: wss://api.vsync.lat/gateway (é a mesma origem trocando https por wss).
  • Em PowerShell: $API = "https://api.vsync.lat" e $H = @{ Authorization = "Bot $TOKEN" }, depois Invoke-RestMethod -Headers $H -Uri "$API/bot/me".