API
Plugins
Crie e gerencie plugins no Portal de Desenvolvedores.
Lembrando: a URL da sua webhook deve ser pública, não pode ser localhost ou algo do tipo.
Use nosso Embed Editor para criar as mensagens.
Como o plugin recebe comandos
Quando alguém usa c.nome_do_comando, o Cacholla envia uma requisição POST para o webhook cadastrado:
{
"type": "command",
"name": "nome_do_comando",
"commandName": "nome_do_comando",
"invokedAs": "nome_no_servidor",
"interactiontoken": "TOKEN_INTERNO",
"prompttoken": "TOKEN_TEMPORARIO",
"user": {
"id": "ID_DO_USUARIO",
"username": "usuario",
"displayname": "Nome no servidor",
"permissions": ["SendMessages"]
},
"guild": {
"id": "ID_DO_SERVIDOR",
"name": "Nome do servidor",
"size": 42
},
"channel": {
"id": "ID_DO_CANAL",
"name": "geral",
"type": 0,
"parentId": null,
"topic": null
},
"args": ["argumentos"]
}
Servidor em Node.js
const http = require("http");
const server = http.createServer((request, response) => {
if (request.method !== "POST" || request.url !== "/cacholla") {
response.writeHead(404, { "Content-Type": "application/json" });
return response.end(JSON.stringify({ message: "Rota não encontrada." }));
}
let body = "";
request.on("data", chunk => {
body += chunk;
});
request.on("end", () => {
let event;
try {
event = JSON.parse(body);
} catch {
response.writeHead(400, { "Content-Type": "application/json" });
return response.end(JSON.stringify({ message: "JSON inválido." }));
}
if (event.type === "command") {
response.writeHead(200, { "Content-Type": "application/json" });
return response.end(JSON.stringify({
content: `Olá, ${event.user.displayname}!`,
components: [{
type: 1,
components: [{
type: 2,
style: 1,
label: "Receber dica",
custom_id: "plugin_dica"
}]
}]
}));
}
if (event.type === "component" && event.customId === "plugin_dica") {
response.writeHead(200, { "Content-Type": "application/json" });
return response.end(JSON.stringify({ ok: true }));
}
response.writeHead(200, { "Content-Type": "application/json" });
response.end(JSON.stringify({ ok: true }));
});
});
server.listen(3000, "127.0.0.1", () => {
console.log("Webhook ouvindo em http://127.0.0.1:3000/cacholla");
});
Servidor em Python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/cacholla")
def cacholla_webhook():
event = request.get_json(silent=True) or {}
if event.get("type") == "command":
user = event.get("user") or {}
return jsonify({
"content": f"Olá, {user.get('displayname', 'usuário')}!",
"components": [{
"type": 1,
"components": [{
"type": 2,
"style": 1,
"label": "Receber dica",
"custom_id": "plugin_dica"
}]
}]
})
if event.get("type") == "component":
if event.get("customId") == "plugin_dica":
return jsonify({"ok": True})
return jsonify({"ok": True})
if __name__ == "__main__":
app.run(host="127.0.0.1", port=3000)
Enviar uma resposta efêmera
Use o interactiontoken recebido no evento.
curl -X POST "https://cacholla.website/api/interactions/reply?interactiontoken=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": {
"content": "Esta resposta só aparece para você.",
"components": [{
"type": 1,
"components": [{
"type": 2,
"style": 1,
"label": "Ação",
"custom_id": "meu_botao"
}]
}]
}
}'
O reply envia uma resposta efêmera. Botões e menus enviados nessa resposta continuam funcionando.
Editar a mensagem principal
curl -X POST "https://cacholla.website/api/interactions/edit?interactiontoken=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": {
"content": "Mensagem atualizada"
}
}'
Editar a última resposta efêmera
curl -X POST "https://cacholla.website/api/interactions/editreply?interactiontoken=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": {
"content": "Resposta atualizada"
}
}'
As rotas reply, edit e editreply aceitam content, embeds e components no formato de mensagem do Discord.
Evento de botão ou menu
Quando o usuário aperta um componente enviado pelo plugin, o Cacholla envia este evento:
{
"type": "component",
"customId": "meu_botao",
"componentType": 2,
"values": [],
"interactiontoken": "NOVO_TOKEN_INTERNO",
"prompttoken": "NOVO_TOKEN_TEMPORARIO",
"user": {
"id": "ID_DO_USUARIO",
"username": "usuario",
"displayname": "Nome no servidor"
},
"guild": {
"id": "ID_DO_SERVIDOR",
"name": "Nome do servidor"
},
"channel": {
"id": "ID_DO_CANAL",
"name": "geral"
}
}
Use customId para identificar o botão ou opção. Use o novo interactiontoken para responder.
Permissões aprovadas para o plugin
Antes, o desenvolvedor solicita os tipos de permissão na aba Permissões do portal. A equipe do Cacholla revisa essa solicitação junto às outras revisões de plugins. Depois da aprovação do Cacholla, o dono do servidor ou alguém com Gerenciar Servidor pode liberar cargos e canais específicos na aba Plugins do painel do servidor. Cada cargo ou canal é selecionado no campo e incluído pelo botão Adicionar.
O servidor rejeita qualquer permissão que ainda não tenha sido aprovada pelo Cacholla. No painel do servidor, use os campos Canal e Cargo e clique em Adicionar para montar a lista liberada. As mudanças entram no aviso padrão do painel — “Você tem configurações não salvas. Deseja salvar?” — e são gravadas ao clicar em Salvar.
O desenvolvedor solicita aprovação no portal de plugins. A integração HTTP equivalente é:
POST /api/plugins/developer/ID_DO_PLUGIN/permissions-request
Content-Type: application/json
{"scopes": ["manage_roles", "send_messages", "message_events"]}
Os escopos disponíveis são manage_roles, send_messages e message_events. O portal apresenta cada permissão como um campo booleano (marcado para solicitar, desmarcado para não solicitar); a API recebe no campo scopes uma lista com os nomes marcados. A equipe do Cacholla revisa a solicitação em Revisões da loja de plugins; até a aprovação, os servidores não conseguem liberar esses recursos. manage_roles também autoriza consultar os cargos do servidor e os cargos de um membro; message_events autoriza receber conteúdo de mensagens nos canais que o servidor liberar.
Ao salvar, o servidor valida que quem configura pode gerenciar cargos, que cada cargo está abaixo dos cargos mais altos dessa pessoa e do bot, e que pessoa e bot podem enviar mensagens nos canais selecionados. Cargos gerenciados não são aceitos. Remova um item da lista para revogar o acesso correspondente. Cada servidor mantém uma autorização separada. Se o plugin não tiver aprovação do Cacholla para aquele tipo de permissão, o servidor não pode liberá-la.
Adicionar ou remover um cargo
Gere o Token de ações do plugin na aba Permissões do portal de desenvolvedor. Ele aparece uma única vez; redefini-lo invalida o token anterior. Guarde-o como segredo no servidor do plugin e nunca o coloque no navegador ou em código público. Use-o somente para as ações de cargos e mensagens. O membro precisa estar no servidor, e o cargo deve estar na lista aprovada. O bot verifica novamente a hierarquia antes de cada alteração.
POST /api/plugins/ID_DO_PLUGIN/actions/role
Authorization: Bearer TOKEN_DE_ACOES
Content-Type: application/json
{
"guildId": "ID_DO_SERVIDOR",
"action": "add",
"roleId": "ID_CARGO_APROVADO",
"memberId": "ID_MEMBRO"
}
action aceita add ou remove. A resposta inclui changed: true quando o cargo mudou e changed: false quando o membro já estava no estado solicitado. A permissão de hierarquia é verificada sobre o cargo que será atribuído/removido: ele precisa estar abaixo do cargo mais alto do bot e não pode ser gerenciado por integração. A posição dos cargos do membro-alvo não bloqueia a atribuição; o bot também pode atribuir cargo ao dono do servidor. O bot precisa da permissão Gerenciar cargos. O limite é de 3 alterações por plugin e servidor a cada 10 segundos. Excesso retorna HTTP 429.
O mesmo escopo permite consultar cargos do servidor e de um membro. Use o token de ações:
GET /api/plugins/ID_DO_PLUGIN/actions/roles?guildId=ID_DO_SERVIDOR&memberId=ID_DO_MEMBRO
Authorization: Bearer TOKEN_DE_ACOES
memberId é opcional. A resposta contém roles, memberRoles e allowedRoleIds (os cargos que o servidor autorizou o plugin a alterar). A consulta não consome o limite de alterações de cargo.
Enviar mensagem em canal aprovado
POST /api/plugins/ID_DO_PLUGIN/actions/message
Authorization: Bearer TOKEN_DE_ACOES
Content-Type: application/json
{
"guildId": "ID_DO_SERVIDOR",
"channelId": "ID_CANAL_APROVADO",
"message": {"content": "Olá!"}
}
message também pode ser uma string. Menções não são acionadas automaticamente. O limite de envio é de 5 mensagens por plugin e servidor a cada 10 segundos. Excesso retorna HTTP 429. Esses limites se aplicam somente às rotas de envio e alteração de cargos.
O token de ações não substitui o interactiontoken usado para responder/editar interações ou solicitar compras. Ele é exclusivo para gerenciar cargos e enviar mensagens nos canais aprovados.
Receber mensagens por webhook
Solicite message_events em permissions-request e aguarde a aprovação do Cacholla. Depois, o administrador do servidor autoriza canais específicos em Plugins. Para cada mensagem nova de usuário nesses canais, o webhook cadastrado pelo plugin recebe um POST JSON com type: "message", guild, user, channel e message (incluindo conteúdo e anexos). Mensagens de bots e webhooks não são encaminhadas. O token de ações não é necessário para receber esse evento, e ele não usa o limite das rotas de envio de mensagens.
Exemplo do corpo:
{
"type": "message",
"guild": {"id": "ID_DO_SERVIDOR", "name": "Servidor"},
"user": {"id": "ID_DO_MEMBRO", "username": "usuario", "displayName": "Usuário"},
"channel": {"id": "ID_DO_CANAL", "name": "geral", "type": 0, "parentId": null},
"message": {"id": "ID_DA_MENSAGEM", "content": "Olá!", "createdAt": "2026-11-21T12:00:00.000Z", "attachments": []}
}
Solicitar uma compra
Use o prompttoken recebido em um evento de comando ou componente:
curl -X POST "https://cacholla.website/api/plugins/pay-prompt" \
-H "Content-Type: application/json" \
-d '{
"prompttoken": "TOKEN_TEMPORARIO",
"amount": 250,
"message": "Desbloquear este recurso?"
}'
prompttoken: token temporário recebido no evento.amountnúmero inteiro de petiscos deve estar entre1e1.000.000.000.message: descrição opcional de até 500 caracteres.
O usuário precisa confirmar em Comprar antes da cobrança.
Depois da confirmação, o webhook recebe:
{
"type": "pay_prompt",
"name": "nome_do_comando",
"interactiontoken": "NOVO_TOKEN_INTERNO",
"amount": 250,
"user": {
"id": "ID_DO_USUARIO",
"username": "usuario",
"displayname": "Nome no servidor"
},
"guild": {
"id": "ID_DO_SERVIDOR",
"name": "Nome do servidor"
},
"channel": {
"id": "ID_DO_CANAL",
"name": "geral"
}
}




