Referência da API REST v1 do Falafy

Convenções

Versão na URL: /api/v1/.... Mudanças incompatíveis só em uma nova versão.
IDs: UUID v7 em texto. Use before/after com IDs para paginar (são ordenados pelo tempo).
Datas: ISO 8601. Campos: camelCase. Permissões: inteiro grande em texto (bitfield).
Erros: { code, message, status } com códigos estáveis em texto; veja limites e erros.
Recurso invisível = 404: um canal ou servidor que o bot não vê responde como se não existisse.
User-Agent recomendado: FalafyBot (https://seu.site, 1.0).

Rotas

Método	Rota (/api/v1)	Autenticação	O que faz
`GET`	`/users/@me`	Bot · Bearer identify	Usuário do token (com e-mail só com o escopo email).
`GET`	`/users/@me/servers`	Bot · Bearer servers	Servidores do usuário/bot com as permissões dele.
`GET`	`/users/{userId}`	Bot	Perfil público de alguém que divide servidor com o bot.
`POST`	`/users/@me/channels`	Bot	Abre (ou devolve) uma DM: { recipientId }.
`DELETE`	`/users/@me/servers/{serverId}`	Bot	O bot sai do servidor.
`GET`	`/oauth2/@me`	Bearer	Aplicação, escopos e validade do token OAuth2.
`GET`	`/applications/@me`	Bot	A aplicação do bot (chave pública, intents liberadas).
`GET`	`/gateway/bot`	Bot	URL do gateway e intervalo de heartbeat.
`GET`	`/servers/{serverId}`	Bot	Dados do servidor.
`GET`	`/servers/{serverId}/channels`	Bot	Canais que o bot enxerga.
`GET`	`/servers/{serverId}/roles`	Bot	Cargos do servidor.
`GET`	`/servers/{serverId}/members`	Bot + SERVER_MEMBERS	Membros (limit até 1000, after=userId).
`GET`	`/servers/{serverId}/members/{userId}`	Bot	Um membro.
`PUT`	`/servers/{serverId}/members/{userId}/roles/{roleId}`	Bot	Dá um cargo (GERENCIAR_CARGOS + hierarquia).
`DELETE`	`/servers/{serverId}/members/{userId}/roles/{roleId}`	Bot	Tira um cargo.
`GET`	`/channels/{channelId}`	Bot	Dados do canal.
`GET`	`/channels/{channelId}/messages`	Bot	Histórico (limit, before, after).
`POST`	`/channels/{channelId}/messages`	Bot	Envia: content, embeds, components, replyToId, mentions.
`GET`	`/channels/{channelId}/messages/{messageId}`	Bot	Uma mensagem.
`PATCH`	`/channels/{channelId}/messages/{messageId}`	Bot	Edita uma mensagem do bot.
`DELETE`	`/channels/{channelId}/messages/{messageId}`	Bot	Apaga (a do bot, ou qualquer uma com GERENCIAR_MENSAGENS).
`PUT`	`/channels/{channelId}/messages/{messageId}/reactions/{emoji}/@me`	Bot	Reage.
`DELETE`	`/channels/{channelId}/messages/{messageId}/reactions/{emoji}/@me`	Bot	Tira a reação.
`GET`	`/channels/{channelId}/messages/{messageId}/reactions/{emoji}`	Bot	Quem reagiu (até 100).
`POST`	`/channels/{channelId}/typing`	Bot	Mostra “digitando…”.
`GET`	`/channels/{channelId}/webhooks`	Bot	Webhooks do canal (GERENCIAR_WEBHOOKS).
`POST`	`/channels/{channelId}/webhooks`	Bot	Cria um webhook: { name }.
`GET · PATCH · DELETE`	`/webhooks/{webhookId}`	Bot	Gerencia um webhook.
`GET · PUT · POST`	`/applications/{appId}/commands`	Bot	Comandos globais (PUT substitui todos).
`GET · PATCH · DELETE`	`/applications/{appId}/commands/{commandId}`	Bot	Um comando global.
`GET · PUT · POST`	`/applications/{appId}/servers/{serverId}/commands`	Bot	Comandos de um servidor (valem na hora).
`POST`	`/interactions/{id}/{token}/callback`	token	Resposta inicial da interação.
`GET · PATCH · DELETE`	`/webhooks/{appId}/{token}/messages/@original`	token	A resposta original.
`POST`	`/webhooks/{appId}/{token}`	token	Follow-up.
`POST`	`/webhooks/{webhookId}/{token}`	token	Executa um webhook (?wait=true).
`GET · PATCH · DELETE`	`/webhooks/{webhookId}/{token}/messages/{messageId}`	token	Mensagem do webhook.

Mensagens com embeds e componentes

Bots podem enviar até 10 embeds (título até 256 caracteres, descrição até 4096, até 25 campos, 6000 caracteres no total) e até 5 linhas de componentes. Imagens de embeds precisam ser https; o app mostra um link para elas em vez de carregar a imagem de outro site.

{
  "content": "Topa uma partida?",
  "components": [
    { "type": 1, "components": [
      { "type": 2, "style": 3, "label": "Bora", "customId": "aceitar" },
      { "type": 2, "style": 5, "label": "Regras", "url": "https://exemplo.com/regras" }
    ]},
    { "type": 1, "components": [
      { "type": 3, "customId": "jogo", "placeholder": "Qual jogo?",
        "options": [{ "label": "CS2", "value": "cs2" }, { "label": "Valorant", "value": "val" }] }
    ]}
  ]
}

Conteúdo das mensagens

Sem a intent privilegiada MESSAGE_CONTENT, leituras pela API e eventos do gateway trazem content, embeds, anexos e componentes vazios, exceto em DMs, nas mensagens do próprio bot e nas que mencionam o bot.

Referência da API v1

Convenções

Rotas

Mensagens com embeds e componentes

Conteúdo das mensagens