Cacholla Website

Item recebido com sucesso.


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.
  • amount número inteiro de petiscos deve estar entre 1 e 1.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"
  }
}