Construir um plugin

Plugins são processos Python em sandbox. Escreva um handler, declare suas capacidades, envie um zip — executamos em um container Docker bloqueado e transmitimos eventos do Discord para ele via JSON-RPC.

O que é um plugin?

Um plugin é um pequeno programa que ouve eventos em um servidor Discord e reage a eles.

• Alguém entra em seu servidor → seu plugin envia uma mensagem de boas-vindas.
• Alguém digita /leaderboard → seu plugin responde com os 10 melhores usuários.
• Alguém reage a uma mensagem → seu plugin conta o voto e atualiza a contagem.

Você escreve Python. Você importa o SDK. Você decora uma função com @plugin.on_event("member_join") e escreve o que deve acontecer. A plataforma cuida do resto.

O que a plataforma faz por você

• Conecta ao Discord. Você nunca lida com gateways WebSocket, sharding, intents ou limites de taxa. A plataforma entrega eventos aos seus manipuladores, e uma única chamada ctx.discord.send_message(…) responde.
• Hospeda seu código. Nenhum servidor para alugar, nenhum Docker para gerenciar, nenhuma implantação às 2 AM. Envie seu código — a plataforma o executa em uma sandbox isolada.
• Fala com o mundo exterior. Chame APIs externas com ctx.http, mantenha conexões ativas abertas com ctx.ws e deixe a plataforma injetar chaves de API de segredos criptografados para que seu código nunca as toque. Veja HTTP de saída.
• Processa pagamentos. Defina um preço ou envie gratuitamente. Os clientes pagam através do Stripe e você fica com 70–85% da receita (o nível depende do seu volume dos últimos 30 dias), pago para seu banco automaticamente após um período de espera. Veja Vendendo seu plugin.
• Oferece a cada instalação uma página de configurações. Declare alguns widgets em JSON e os administradores recebem uma página de painel com tema para seu plugin — cartões de estatísticas, gráficos, formulários de configuração — sem você escrever uma linha de frontend. Veja Painéis.
• Envia suas atualizações. Publique uma nova versão e as instalações a selecionam automaticamente (os proprietários podem fixar uma versão para recusar). Sem e-mails de migração, sem "por favor, convide o bot novamente". Veja atualizações e reversão.
• Escalabilidade para você. Uma instalação ou um milhão — a plataforma lida com concorrência, tentativas, quotas.

O que você faz

Escreva a lógica que transforma eventos do Discord em ações. É isso. O fluxo fica assim:

Como um plugin é diferente de um "framework de bot Discord"

Preocupação	Plugin (esta plataforma)	Bot auto-hospedado (discord.py, etc.)
Conectar ao Discord	A plataforma faz	Você faz
Servidor para hospedar código	A plataforma fornece	Você aluga / gerencia
Pagamentos / Stripe	Plataforma cuida	Você constrói você mesmo
Instalação por cliente	Um clique para o cliente	Você guia cada cliente pelo OAuth
Dimensionamento / cotas / tentativas	Plataforma cuida	Você cuida
Avaliações / descoberta	Marketplace integrado	Você comercializa seu bot você mesmo
Superfície da API do Discord	Capacidade com restrição (declare o que você precisa)	Acesso completo (sua responsabilidade)

Onde você gastará seu tempo

1. Conectando eventos a handlers. Decoradores como @plugin.on_event("message_create") ou @plugin.on_slash_command("hello").
2. Armazenando estado. Configurações por servidor, contadores e placar de líderes vivem em ctx.kv (chave-valor, todo plugin tem) ou ctx.sql (SQL completo, uma capacidade que você solicita e é concedida após revisão da equipe). De qualquer forma, não há banco de dados para gerenciar.
3. (Opcional) Uma página de configurações. Solte um manifesto JSON e os clientes recebem uma página de painel que podem configurar seu plugin. Nenhum código frontend necessário.

Você pode construir e enviar seu primeiro plugin em uma tarde. As primeiras versões de novos desenvolvedores passam por uma breve revisão da equipe antes de aparecerem no marketplace; desenvolvedores estabelecidos que publicam de repositórios públicos geralmente ignoram a fila. Clique em "Começar" acima quando estiver pronto para escrever código. Prefere não começar de um arquivo em branco? O Construtor de Plugin escreve um primeiro rascunho funcional a partir de uma descrição, e o CLI yourbot o executa localmente antes de você enviar qualquer coisa.

A jornada completa em um relance

Todo plugin passa pelos mesmos cinco estágios, e estes documentos estão dispostos na mesma ordem — a barra de abas acima agrupa-os em Entender → Construir → Enviar → Referência. Cada estágio vincula-se à seção que o cobre:

Bom saber antes de você compilar

FAQ existente

Vá direto para a seção que responde sua pergunta. A caixa de filtro acima pesquisa apenas a aba em que você está.

Quero…	Vá para o
Reagir quando alguém entra, publica ou clica	Todos os eventos
comando de barra	Comandos de barra
Novas mensagens	events:message_content
Armazenar configurações ou contadores por servidor	Armazenamento de chave-valor
Manter uma chave de API sem codificá-la	Usuários com direitos
Executar consultas SQL reais	Armazenamento e E/S: SQL em sandbox
Chamar uma API externa	Mock de HTTP de saída
Manter uma conexão ao vivo com um servidor de jogo	Armazenamento e E/S: WebSockets
Fazer algo em um cronograma	Cronogramas Cron
Abra um formulário pop-up (modal)	Construir: Diálogos modais
Atualize uma mensagem quando um botão é clicado	Construir: Botões e menus
Adicione um tempo de espera ou limite de taxa a um comando	Armazenamento e E/S: Estado efêmero
Exibir configurações	Manifesto do Painel (JSON)
Construa uma interface de painel totalmente personalizada	Painéis: Modo Iframe
Testar meu plugin antes de fazer upload	Começar
Escreva testes unitários para meus manipuladores	Produção: Testes
Trate erros do SDK sem travar	Produção: Tratamento de erros
Entenda por que globals do módulo são redefinidos	Produção: Modo de pool
Ver o que meu plugin pode acessar	Referência: Catálogo de capacidades
Verificar cada tamanho e limite de taxa	Referência: Limites e cotas
Deletar Plugin	Nomeie seu plugin
Publicar & revisar	Publicar & revisar
Veja o que mudou em cada lançamento do SDK	Referência: changelog do SDK