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.
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"
}
}




