API de bots

Referência do gateway

Eventos entregues pelo gateway, códigos de fechamento da conexão e limites.

Como conectar e manter a conexão está em Gateway (tempo real). Aqui ficam os eventos, os códigos de fechamento e os limites.

Eventos#

Os eventos de canal só chegam se o bot vê o canal. Isso inclui os canais de voz, que também têm chat: MESSAGE_CREATE e os demais eventos de mensagem chegam para eles, e o objeto do canal traz type: "voice" (ou "text") para diferenciar. Mensagens de sistema (como "fulano entrou") não geram MESSAGE_CREATE. O bot recebe também as próprias mensagens: ignore author.bot.

GUILD_CREATE (ao conectar, e quando o bot é adicionado a um servidor). Traz o estado completo (até 1000 membros; memberCount é o total):

JSON

{
  "op": "dispatch", "seq": 1, "t": "GUILD_CREATE",
  "d": {
    "guild": { "id": "682f1017-...", "name": "Capture", "iconUrl": null, "ownerId": "bc86cc02-...", "partner": false, "verified": false, "description": "", "bannerUrl": null, "createdAt": 1791420368416 },
    "channels": [ { "id": "a8c57340-...", "guildId": "682f1017-...", "name": "geral", "type": "text", "parentId": "91a42fbc-...", "topic": "", "slowmodeSeconds": 0, "overwrites": [], "position": 0, "createdAt": 1791420368416, "lastMessageAt": null } ],
    "roles": [ { "id": "efb6b62a-...", "guildId": "682f1017-...", "name": "Capture Bot", "color": null, "permissions": ["SEND_MESSAGES", "ADD_REACTIONS"], "hoist": false, "managed": true, "botId": "1af40b9e-...", "position": 0, "createdAt": 1791420368477 } ],
    "members": [ { "id": "bc86cc02-...", "username": "anav78h", "displayName": "ana", "bot": false, "createdAt": 1791400000000, "prismaActive": true, "prismaPlan": "prisma", "prismaSince": 1791410000000, "pulsing": true, "pulseMonths": 0, "pulsingSince": 1791420368500, "pulseBadge": { "id": "PULSE_1", "months": 1 }, "nextPulseBadge": { "id": "PULSE_2", "months": 2, "at": 1796604368500 }, "nickname": null, "roleIds": [], "joinedAt": 1791420368416, "timeoutUntil": null, "online": false, "status": "offline", "activity": null } ],
    "memberCount": 3
  }
}

Cada item de members é um objeto de usuário com os campos de membro (nickname, roleIds, joinedAt, timeoutUntil e o pulsingSince daquele servidor).

GUILD_DELETE (o bot saiu, foi expulso ou banido, ou o servidor foi excluído):

JSON

{ "op": "dispatch", "seq": 9, "t": "GUILD_DELETE", "d": { "id": "682f1017-..." } }

MESSAGE_CREATE (mensagem nova; d é a mensagem completa):

JSON

{
  "op": "dispatch", "seq": 2, "t": "MESSAGE_CREATE",
  "d": {
    "id": "f251ec04-...", "guildId": "682f1017-...", "channelId": "a8c57340-...", "authorId": "bc86cc02-...",
    "body": "oi **bot** <@1af40b9e-...>", "attachments": ["att:Qm9iIGVudmlvdSBpc3Nv"], "replyToId": null, "embeds": [], "components": [],
    "files": [ { "id": "Qm9iIGVudmlvdSBpc3Nv", "name": "foto.png", "size": 48213, "kind": "image", "mime": "image/png", "warn": false } ],
    "mentionsEveryone": false, "mentionsHere": false, "interaction": null, "reactions": {}, "pinned": false,
    "createdAt": 1791420369298, "editedAt": null,
    "author": { "id": "bc86cc02-...", "username": "anav78h", "displayName": "ana", "bot": false, "avatarUrl": null, "online": false, "status": "offline" }
  }
}

Mensagens enviadas como resposta a um comando de barra trazem interaction: { applicationId, commandName, userId }. Anexos aparecem em attachments (referências att:<id>) e files (metadados: id, name, size, kind em image, video, audio ou file, mime, warn); o evento nunca traz URLs de download. Para baixar, use GET /attachments/:id (URL assinada de 5 minutos, para canais que o bot vê).

MESSAGE_UPDATE (edição, fixação ou mudança de reações): mesma forma da mensagem, com editedAt preenchido quando foi edição. MESSAGE_DELETE:

JSON

{ "op": "dispatch", "seq": 10, "t": "MESSAGE_DELETE", "d": { "id": "64d10f4c-...", "channelId": "a8c57340-...", "guildId": "682f1017-..." } }

MESSAGE_REACTION_ADD e MESSAGE_REACTION_REMOVE:

JSON

{ "op": "dispatch", "seq": 4, "t": "MESSAGE_REACTION_ADD", "d": { "messageId": "f251ec04-...", "channelId": "a8c57340-...", "guildId": "682f1017-...", "userId": "bc86cc02-...", "emoji": "👍" } }

CHANNEL_CREATE, CHANNEL_UPDATE e CHANNEL_DELETE:

JSON

{ "op": "dispatch", "seq": 12, "t": "CHANNEL_CREATE", "d": { "guildId": "682f1017-...", "channel": { "id": "85e23ae8-...", "guildId": "682f1017-...", "name": "novo", "type": "text", "parentId": null, "topic": "", "slowmodeSeconds": 0, "overwrites": [], "position": 0, "createdAt": 1791420369422, "lastMessageAt": null } } }

GUILD_MEMBER_ADD e GUILD_MEMBER_REMOVE (entrou; saiu, foi expulso ou banido):

JSON

{ "op": "dispatch", "seq": 15, "t": "GUILD_MEMBER_ADD", "d": { "guildId": "682f1017-...", "user": { "id": "6a7c6c99-...", "username": "betov78h", "displayName": "beto", "bot": false, "avatarUrl": null, "createdAt": 1791300000000, "prismaActive": false, "pulsing": false }, "joinedAt": 1791420369512 } }

joinedAt é quando a pessoa entrou (o mesmo valor que ela terá em members); user é o objeto de usuário completo. GUILD_MEMBER_REMOVE traz só { guildId, user }.

INTERACTION_CREATE (alguém usou um comando de barra do bot, clicou num botão ou menu, ou enviou um modal; type diz qual, veja a seção de tipos de interação). Exemplo de comando:

JSON

{
  "op": "dispatch", "seq": 17, "t": "INTERACTION_CREATE",
  "d": {
    "id": "127949ceb241c68faaabe120", "token": "4883bf4f5a8765c34471dedb7691c424",
    "applicationId": "1af40b9e-...", "type": "command",
    "guildId": "682f1017-...", "channelId": "a8c57340-...",
    "user": { "id": "bc86cc02-...", "username": "anav78h", "displayName": "ana", "bot": false, "createdAt": 1791400000000, "prismaActive": false, "pulsing": false },
    "member": { "nickname": null, "roleIds": ["efb6b62a-..."], "joinedAt": 1791420368416, "pulsingSince": null, "timeoutUntil": null },
    "data": { "name": "eco", "options": { "texto": "oi" } }
  }
}

user é quem usou o comando (objeto de usuário, com presença) e member é a parte dela que só existe naquele servidor (objeto de membro).

Não existem eventos de digitação, mudança de cargos/membros, presença de outras pessoas nem mensagens diretas. Os eventos VOICE_* existem só para bots dentro de um canal de voz (veja Voz). Para ler cargos ou membros atuais, use GET /guilds/:g.

Códigos de fechamento#

Código	Motivo	O que fazer
4001	`Token inválido` (identify errado) ou `Autenticação necessária` (não enviou identify em 10 s)	Corrija o token. Não reconecte em loop com token inválido
4002	`Payload inválido` (não é JSON de objeto)	Corrija o código
4003	`Não autenticado` (mandou algo antes do identify), `Conta suspensa` ou IP banido	Não reconecte
4004	`Muitas sessões` (máximo 2 conexões por bot)	Feche outra instância
4005	`Já autenticado` (enviou identify duas vezes)	Corrija o código
4008	`Limite excedido` (mais de 120 mensagens por minuto enviadas ao servidor)	Reduza o ritmo
4009	`Sem ping`	Reconecte e mantenha o ping
1009	Mensagem maior que 64 KiB	Envie menos dados
1011	Erro interno	Reconecte
1012	`Reiniciando` (servidor reiniciando)	Reconecte com backoff

O gateway aceita no máximo 30 aberturas de conexão por minuto por IP.

Limites do gateway#

Até 2 conexões simultâneas por bot.
Até 120 mensagens por minuto enviadas ao servidor (ping e presença contam).
Mensagens de até 64 KiB.