Aplicações e bots
Uma aplicação é a identidade do seu bot no Concord. Criar uma cria junto um usuário marcado
como bot, e o id da aplicação é o id desse usuário — como no Discord, onde
application_id == bot user id.
A consequência prática é que não existe um segundo sistema de permissão nem um segundo protocolo: o bot entra num servidor, recebe cargo, fala no chat e entra na voz pelos mesmos caminhos que o aplicativo usa.
1. Criar a aplicação
No portal: app.concord.win/developers.
Ao criar, o token do bot aparece uma vez. Ele não é guardado em lugar nenhum em texto — o servidor só tem o hash. Se perder, gere outro; o antigo morre na hora e derruba quem estiver conectado com ele.
Pelo HTTP, a mesma coisa (precisa do cookie de sessão de quem está criando):
POST /api/applications
Content-Type: application/json
{"name": "Tocadiscos"}
{"id": "47", "name": "Tocadiscos", "token": "NDc.xxxxxxxx…"}
| Rota | O que faz |
|---|---|
GET /api/applications | suas aplicações |
GET /api/applications/{id} | uma, com bot, redirects e public |
PATCH /api/applications/{id} | muda name, description, public, redirects |
POST /api/applications/{id}/token | gera outro token do bot (derruba o anterior) |
POST /api/applications/{id}/secret | gera outro client secret (só para OAuth2) |
DELETE /api/applications/{id} | apaga: o bot sai de todos os servidores |
O client secret só serve para trocar código OAuth2 por token, do lado do servidor do seu bot. Para apenas instalar o bot, você não precisa dele.
2. Montar o link de convite
https://app.concord.win/oauth2/authorize?client_id=<id>&scope=bot&permissions=<bits>
permissions é a soma dos bits que o bot pede. Quem abrir o link vê a lista, escolhe o servidor e
autoriza. Duas regras valem sempre, do lado do servidor:
- ninguém dá o que não tem: o que é concedido é
pedido & permissões_de_quem_autoriza; - Administrador só o dono entrega.
Então pedir tudo não adianta nada: pedir demais só faz a tela de autorização parecer assustadora.
| Bit | Permissão | Bit | Permissão | |
|---|---|---|---|---|
1 << 0 | Administrador | 1 << 12 | Reagir a mensagens | |
1 << 1 | Gerenciar o servidor | 1 << 13 | Entrar na voz | |
1 << 2 | Gerenciar canais | 1 << 14 | Falar na voz | |
1 << 3 | Gerenciar cargos | 1 << 15 | Câmera e tela | |
1 << 4 | Expulsar membros | 1 << 16 | Silenciar membros | |
1 << 5 | Banir membros | 1 << 17 | Ver o registro de auditoria | |
1 << 6 | Gerenciar mensagens | 1 << 18 | Criar salas temporárias | |
1 << 7 | Criar convites | 1 << 19 | Ver canais | |
1 << 8 | Mencionar @todos | 1 << 20 | Gerenciar eventos | |
1 << 9 | Enviar mensagens | 1 << 21 | Moderar membros | |
1 << 10 | Anexar arquivos | 1 << 22 | Gerenciar aplicações | |
1 << 11 | Criar tópicos |
Para um bot de chat comum, o conjunto honesto é
Ver canais | Enviar mensagens | Reagir = 524288 | 512 | 4096 = 528896.
Um bot de música acrescenta Entrar na voz | Falar = 553472.
Público ou privado
Uma aplicação nasce privada: só você consegue instalá-la. Ligue "Qualquer um pode instalar" no portal quando quiser que outras pessoas usem o link.
3. Conectar
O bot se identifica com o cabeçalho Authorization: Bot <token> — tanto nas rotas /api/* quanto
na primeira mensagem do WebSocket. Veja Gateway.
const r = await fetch('https://app.concord.win/api/servers', {
headers: { Authorization: `Bot ${process.env.CONCORD_TOKEN}` },
});
4. Anunciar os comandos
Quando alguém digita / no começo de uma mensagem, o Concord mostra os comandos das aplicações
instaladas naquele servidor — nome, opções e descrição, agrupados por aplicação. Para o seu bot
aparecer ali, anuncie a lista com o token do bot. Ela é global da aplicação, não por servidor:
um PUT substitui a lista inteira.
PUT /api/applications/@me/commands
Authorization: Bot <token>
Content-Type: application/json
{
"commands": [
{
"name": "toca",
"description": "Toca uma música ou adiciona à fila",
"options": [
{ "name": "fonte", "description": "link ou busca", "required": true, "type": "string" }
]
},
{ "name": "pausa", "description": "Pausa o áudio" }
]
}
Limites: até 50 comandos; name com [a-z0-9-], de 1 a 32 caracteres; description de 1 a 160;
até 10 opções por comando (required e type são opcionais). GET na mesma rota devolve o que
está gravado.
O seletor só mostra: a mensagem continua chegando ao bot como texto (/toca nasa) pelo
gateway, e é o bot quem a interpreta. Com o nescord, o anúncio acontece sozinho
ao subir, a partir dos @Command() registrados.
O que o bot vira dentro do servidor
Quando alguém autoriza o convite, acontecem três coisas de uma vez:
- o bot entra como membro — aparece na lista com a etiqueta BOT;
- nasce um cargo gerenciado com o nome da aplicação e exatamente as permissões concedidas;
- esse cargo é dado ao bot.
O cargo gerenciado não pode ser editado nem apagado pela tela de cargos: ele pertence à aplicação. Para mexer no que o bot pode fazer, mude o cargo pelas rotas de cargo normais, ou remova e instale de novo com outras permissões.
Quem administra o servidor vê tudo isso em Configurações do servidor → Apps → Integrações, com as permissões concedidas, as negadas e o botão de remover.
Tirar o bot
DELETE /api/servers/{servidor}/integrations/{aplicacao}
Precisa de Gerenciar aplicações ou Administrador naquele servidor. O bot sai e o cargo gerenciado vai junto.
Limites que valem conhecer
- O token é do formato
<id em base64url>.<segredo>. O prefixo não é segredo; o resto é. - Trocar o token derruba a conexão atual do bot, não só a próxima.
- Apagar a aplicação remove o bot de todos os servidores e invalida o token e o segredo.