Referência REST

Todas as rotas abaixo usam Authorization: Bot <token> (menos as marcadas como "sem cabeçalho Bot"). Corpo e respostas são JSON. Erros têm o formato { "error": "mensagem em português" }.

Nas rotas de servidor, :g é o id do servidor e :c o id do canal. Você os recebe no gateway (GUILD_CREATE, MESSAGE_CREATE) ou em GET /bot/guilds e GET /guilds/:g.

Aplicativo e bot#

Usuários#

prisma.since é desde quando o período atual de Prisma está ativo ("assinante desde"); o dono pode esconder o Prisma (prisma vem null) e o Pulse (pulsing: false). Para "entrou no servidor em", use GET /guilds/:g/members/:id, abaixo.

curl -s $API/users/$USER_ID -H "Authorization: Bot $TOKEN"

curl -s $API/bot/me -H "Authorization: Bot $TOKEN"

Comandos de barra#

Veja Interações e comandos. Resumo (aceitam o token do bot ou a sessão do dono):

:appId é o id do aplicativo (o mesmo do bot).

Anexos#

Bots enviam imagens, vídeos, áudios e arquivos como anexos, pelo mesmo fluxo que as pessoas usam no app (os bytes vão direto ao armazenamento privado por uma URL assinada; a API nunca os recebe). Para bots, só em canais de texto de servidor. Passo a passo com exemplos em curl e Node em Enviar imagens e arquivos.

# 1) preparar  2) PUT dos bytes (sem token)  3) concluir  4) usar na mensagem
curl -s -X POST $API/attachments/init -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"imagem.png","size":12345,"contentType":"image/png","scope":{"guildId":"'$G'","channelId":"'$C'"}}'
curl -s -X PUT "URL_DE_ENVIO" -H "Content-Type: application/octet-stream" --data-binary @imagem.png
curl -s -X POST $API/attachments/ID_DO_ANEXO/complete -H "Authorization: Bot $TOKEN"
curl -s -X POST $API/guilds/$G/channels/$C/messages -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"body":"Veja a imagem","attachments":["att:ID_DO_ANEXO"]}'

Regras e limites para bots:

• O bot precisa estar no servidor e ter SEND_MESSAGES e ATTACH_FILES no canal (sobrescritas do canal valem); senão 403 O bot não pode anexar arquivos aqui.. scope com dmUserId ou groupId responde 403 (bots não têm mensagens diretas).
• 100 MB por arquivo, fixo (413 { error, maxBytes, tier: "bot" }, sem upgrade). 10 envios pendentes por bot (429) e 20 init por minuto. Anexos por mensagem: 4 a 10, conforme o nível de Pulse do servidor (400 Envie até N anexos por mensagem.).
• O tipo (kind, mime) vem do conteúdo, conferido no complete; o contentType declarado não manda. warn: true marca executáveis.
• Um anexo só vira mensagem se estiver concluído, for do próprio bot e do mesmo canal do scope, e só uma vez (400 Anexo inválido.). Envio não concluído expira em 1 h; concluído e sem mensagem, em 24 h.
• A resposta da mensagem e os eventos do gateway trazem attachments (referências) e files (metadados), nunca URLs assinadas. 503 Envio de arquivos indisponível no momento. quando o armazenamento não está configurado.
• Respostas efêmeras de interação não aceitam anexos; respostas normais, follow-ups e edições aceitam o mesmo campo attachments (veja Anexos em respostas de interação).

Mensagens#

Canais de voz também têm mensagens: as rotas desta seção e as de Reações e Anexos valem para type: "voice" com as mesmas permissões dos canais de texto. Só categorias não têm mensagens.

Detalhes:

• body aceita até 2000 caracteres (formatação em Mensagens e embeds). Para o bot, body pode ficar vazio se houver embeds, componentes ou anexos. Mensagem sem nada devolve 400.
• embeds é uma lista de até 10 embeds (veja o schema do embed). Só contas de bot podem enviá-los: de pessoas, o campo é ignorado.
• components são botões e menus (veja Componentes e modais). Com embeds ou componentes, o body pode ficar vazio.
• replyToId responde a uma mensagem do mesmo canal.
• attachments recebe uma lista de referências att:<id> preparadas com as rotas de Anexos no mesmo canal. Exige ATTACH_FILES (403 O bot não pode anexar arquivos aqui.); referência inválida, de outro canal ou já usada dá 400 Anexo inválido.; acima do limite do servidor, 400 Envie até N anexos por mensagem..
• @everyone e @here só notificam se o bot tiver MENTION_EVERYONE no canal.
• Em canais com modo lento, o bot só fica isento com MANAGE_MESSAGES (ou MANAGE_CHANNELS). Sem isso, recebe 429 com { error, retryAfter } em segundos.
• A resposta de message traz id, guildId, channelId, authorId, body, embeds, components, attachments, files (metadados dos anexos: id, name, size, kind, mime, warn), reactions, replyToId, pinned, interaction, createdAt, editedAt e author (identidade completa, com bot: true).

curl -s -X POST $API/guilds/$G/channels/$C/messages \
  -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"body":"Olá do bot!","embeds":[{"title":"Oi","description":"Mensagem com embed","color":"#7c5cff"}]}'

curl -s -X PATCH $API/guilds/$G/channels/$C/messages/$M \
  -H "Authorization: Bot $TOKEN" -H "Content-Type: application/json" \
  -d '{"body":"Texto editado"}'

curl -s -X DELETE $API/guilds/$G/channels/$C/messages/$M -H "Authorization: Bot $TOKEN"

Reações#

A rota alterna: reagir de novo com o mesmo emoji remove a reação do bot. Aceita emojis unicode (até 16 unidades de texto) e o token de um emoji personalizado do servidor (veja Menções, emojis e escape); não há rota para remover reação de outra pessoa. O gateway avisa com MESSAGE_REACTION_ADD e MESSAGE_REACTION_REMOVE.

Canais#

slowmodeSeconds aceita 0, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200 ou 21600. O tópico tem até 300 caracteres. Nunca é possível apagar o último canal de texto do servidor.

Membros, cargos e moderação#

A hierarquia vale para bots como para pessoas: o bot só mexe em cargos e membros abaixo do seu cargo mais alto, e o cargo gerenciado nasce abaixo de quem o adicionou. Rotas de gerenciamento do servidor (PATCH /guilds/:g etc.) exigem MANAGE_GUILD e seguem as mesmas regras de qualquer membro.

Para listar membros e cargos, use GET /guilds/:g (campos members e roles) ou os dados do GUILD_CREATE no gateway. Para um só membro (um comando userinfo, por exemplo), GET /guilds/:g/members/:accountId:

curl -s $API/guilds/$G/members/$USER_ID -H "Authorization: Bot $TOKEN"
# { "member": { "id": "...", "username": "ana", "displayName": "Ana", "createdAt": 1791420368416, "prismaActive": true, "prismaSince": 1791500000000,
#               "pulsing": true, "pulseMonths": 2, "pulsingSince": 1792000000000, "pulseBadge": { "id": "PULSE_2", "months": 2 },
#               "nextPulseBadge": { "id": "PULSE_3", "months": 3, "at": 1799776000000 }, "nickname": null, "roleIds": [], "joinedAt": 1791420368416,
#               "timeoutUntil": null, "status": "online", ... } }

Os campos de cada pessoa (e o que o dono da conta pode esconder) estão em Objetos: usuário e membro.

Interações e webhooks (sem cabeçalho Bot)#

Estas rotas são autenticadas pelo token da interação na URL. Não envie Authorization: Bot nelas: /webhooks responde 403 a bots que enviam o cabeçalho.

attachments segue as regras de Anexos em respostas de interação (não vale em respostas efêmeras). Detalhes em Interações e comandos, Componentes e modais e tipos de interação e respostas.