Bot do Discord

Conecte seu servidor do Discord ao PumaHelp: membros abrem tickets sem sair do Discord, cada ticket vira uma thread privada, e as respostas da sua equipe — enviadas pelo dashboard — chegam direto na conversa.

🚀 Antes de começar

Você vai precisar de:

• Administrador no servidor do Discord onde o bot será instalado;
• acesso de Owner ou Admin na sua organização no PumaHelp (para criar a API Key).

A configuração completa leva cerca de 10 minutos.

1. Convide o bot para o servidor

Use o link oficial de convite: discord.com/oauth2/authorize?client_id=1407072685565153350

O Discord vai pedir sua confirmação das permissões que o bot usa: ver o canal escolhido e enviar mensagens nele, criar a thread privada de cada ticket e escrever dentro dela, publicar as mensagens formatadas (o card de abertura e as respostas da sua equipe), mencionar o cargo de suporte para trazê-lo à thread, arquivar e trancar a thread quando o ticket é fechado, e apagar mensagens com menções indevidas dentro dos tickets.

2. Crie a API Key no Dashboard

A API Key é como o bot se autentica na sua organização — e criar a do bot leva dois cliques:

1. No dashboard, acesse Configurações → API Keys e clique em Criar Chave.
2. Em "Para que esta chave será usada?", clique em Bot do Discord — as permissões necessárias são selecionadas automaticamente e o nome é preenchido.
3. Clique em Gerar Chave.
4. Copie a chave agora. Por segurança, ela é exibida uma única vez. Se perder, basta gerar outra.

3. Configure o bot com /config

No seu servidor do Discord, digite /config (exige permissão de Administrador). Abre um painel — visível só para você — mostrando o estado de cada parte e o que ainda falta:

Seção	O que configurar
Discord	O canal onde as threads de ticket serão criadas e, opcionalmente, o cargo de suporte
PumaHelp	O subdomínio da sua organização (ex.: acme) e a API Key do passo 2
Categorias	Os tipos de ticket que aparecem no menu de abertura
Painel	Onde publicar a mensagem de abertura de tickets

Seguro por padrão

Tudo é preenchido em janelas próprias (modais) — nenhuma credencial é digitada no chat nem fica visível para outros membros. Ao salvar, o bot valida a API Key na hora: se algo estiver errado, você fica sabendo imediatamente. E ao editar depois, campos de credencial deixados em branco mantêm o valor já salvo.

E o webhook?

Ao salvar a API Key, o bot configura sozinho o webhook de retorno na sua organização — é por ele que as respostas dos agentes chegam ao Discord. Você verá a confirmação na própria resposta do /config ("webhook criado" ou "reaproveitado"). Se a sua Key não tiver as permissões de webhook, veja a configuração manual no fim da página.

Sobre o cargo de suporte

• Com cargo: ele é mencionado na abertura de cada ticket — é essa menção que adiciona a equipe à thread privada e a notifica.
• Sem cargo: o ticket abre sem menção; apenas o solicitante (e quem tem a permissão Gerenciar Threads) enxerga a thread no Discord. A equipe acompanha e responde pelo dashboard normalmente.

4. Crie as categorias e publique o painel

1. Em /config → Categorias, crie ao menos uma (ex.: "Suporte Técnico", "Financeiro"). Cada categoria define o assunto e as tags do ticket criado no PumaHelp, e pode ser associada a um dos seus grupos.
2. De volta ao painel do /config, clique em Publicar painel e escolha o canal. A mensagem com o menu de abertura aparece lá, pronta para os membros usarem.

💬 No dia a dia

• Abrir ticket: o membro escolhe a categoria no painel, descreve o problema e pode anexar até 10 arquivos (50 MB cada). Uma thread privada é criada na hora, e o ticket aparece no dashboard.
• Responder: pelo botão Responder na thread — com texto, anexos ou ambos.
• Respostas da equipe: enviadas pelo dashboard, chegam automaticamente à thread do Discord.
• Resolução: quando o ticket é resolvido, o membro pode responder para reabri-lo; sem resposta, a thread é arquivada automaticamente.

🔑 Permissões da API Key (referência)

O preset Bot do Discord seleciona exatamente estas:

Permissão	Para quê
ticket:create	abrir tickets a partir do Discord
ticket:update	enviar as respostas e mudar o status do ticket
file:upload	enviar os anexos postados no Discord
group:read	listar seus grupos ao configurar categorias
organization:read	validar a Key e identificar sua organização
webhook:read	encontrar o webhook de retorno, se já existir
webhook:create	criar o webhook de retorno automaticamente

❓ Problemas comuns

O comando /config não aparece. Recarregue o Discord (Ctrl+R no desktop, Cmd+R no macOS). E lembre: apenas administradores do servidor enxergam o comando.

"Não consegui validar a API Key" ao salvar. Confira o subdomínio (só o nome, sem .pumahelp.com) e se a Key foi criada com o preset Bot do Discord. Se você montou a Key manualmente, ela precisa incluir a permissão organization:read.

As respostas dos agentes não chegam ao Discord. Abra o /config → PumaHelp e salve novamente — o bot re-verifica e reconfigura o webhook de retorno. Se a mensagem avisar que a Key não tem as permissões de webhook, crie uma nova Key com o preset Bot do Discord (que já as inclui) ou siga a configuração manual.

Eu usava /configticket e /ticketoptions. Foram substituídos — ao usá-los, o bot responde com um botão que abre o /config, onde toda a configuração é feita agora.

Configurar o webhook manualmente

Só é necessário se a sua API Key não tiver as permissões webhook:read e webhook:create (Keys criadas antes do preset atual, por exemplo) e você preferir não criar outra:

1. No dashboard, acesse Configurações → Webhooks e crie um novo webhook.
2. URL: https://bot.pumahelp.com/webhook
3. Evento: marque ticket.updated — é o único que o bot usa.
4. Salve, copie a Webhook Key e informe-a no campo Webhook Secret do /config → PumaHelp. O valor digitado manualmente sempre tem precedência sobre o automático.