Integração com Discord

Visão Geral#

A integração do Pluggy Docs com o Discord adiciona busca na documentação, perguntas e respostas com inteligência artificial e resumos diários de canais de ajuda ao seu servidor Discord. Sua comunidade pode consultar a documentação da API, fazer perguntas e receber resumos automatizados de tópicos comuns de suporte.

Pré-requisitos#

Antes de começar, certifique-se de que você possui o seguinte:

• Acesso de administrador ao servidor Discord — Você precisa da permissão "Gerenciar Servidor" para adicionar bots.
• Uma instância do Pluggy Docs implantada — Sua plataforma de documentação deve ser acessível por meio de uma URL pública com HTTPS.
• Uma conta do Discord com acesso ao Discord Developer Portal.

Passo 1: Criar um Aplicativo Discord#

1. Vá para o Discord Developer Portal e clique em Novo Aplicativo.
2. Insira um nome para seu aplicativo (por exemplo, "Pluggy Docs") e concorde com os Termos de Serviço do Desenvolvedor.
3. Clique em Criar.

Você será levado à página de Informações Gerais do aplicativo. Anote o ID do Aplicativo e a Chave Pública — você precisará deles mais tarde.

Passo 2: Criar um Usuário Bot#

1. Navegue até Bot na barra lateral esquerda.
2. Clique em Adicionar Bot, depois confirme clicando em Sim, faça isso!.
3. Nas configurações do bot, você pode opcionalmente personalizar o nome de usuário e o avatar do bot.

Passo 3: Configurar Permissões do Bot#

O bot precisa de permissões específicas para funcionar corretamente. Navegue até OAuth2 > Gerador de URL na barra lateral esquerda e selecione as seguintes Permissões do Bot:

Essas permissões serão solicitadas quando o bot for adicionado a um servidor.

Passo 4: Configurar Intenções de Gateway#

As Intenções de Gateway controlam quais eventos seu bot recebe do Discord. Navegue até Bot na barra lateral esquerda e ative as seguintes Intenções de Gateway Privilegiadas:

Sob Guilda (não privilegiada), certifique-se de que o seguinte esteja ativado:

Passo 5: Configurar a URL do Ponto de Interações#

A URL do Ponto de Interações informa ao Discord onde enviar os comandos slash e os payloads de interação.

1. Navegue até Informações Gerais na barra lateral esquerda.
2. No campo URL do Ponto de Interações, insira:

https://your-domain/api/discord/interactions

Substitua your-domain pelo seu domínio real de implantação do Pluggy Docs. O Discord enviará uma solicitação de verificação para esta URL — seu servidor deve responder com a validação de assinatura correta para que a URL seja aceita.

3. Clique em Salvar Alterações.

Passo 6: Configurar Variáveis de Ambiente#

Você precisa de três variáveis de ambiente do seu aplicativo Discord para conectá-lo à sua instância do Pluggy Docs.

Adicione o seguinte à sua configuração de ambiente:

DISCORD_CLIENT_ID=your-application-id
DISCORD_CLIENT_SECRET=your-client-secret
DISCORD_PUBLIC_KEY=your-public-key

Passo 7: Instalar o Bot#

Existem duas maneiras de adicionar o bot do Pluggy Docs ao seu servidor:

Opção A: Instalar via Fluxo OAuth#

Direcione os usuários para a seguinte URL para iniciar o fluxo de instalação OAuth:

https://your-domain/api/discord/install

Isso redirecionará para a tela de consentimento OAuth do Discord, onde o administrador do servidor pode autorizar o bot e selecionar a qual servidor adicioná-lo.

Opção B: Botão Adicionar ao Discord#

Você pode incorporar um botão "Adicionar ao Discord" em sua documentação ou páginas da comunidade:

<a href="https://your-domain/api/discord/install">
  Adicionar Pluggy Docs ao Discord
</a>

Comandos Disponíveis#

Uma vez que o bot é adicionado ao seu servidor, os seguintes comandos slash estão disponíveis:

/pluggy-docs ask [pergunta]#

Faça uma pergunta em linguagem natural sobre a API ou plataforma do Pluggy. O bot usa busca com inteligência artificial para fornecer uma resposta resumida com links para a documentação relevante.

/pluggy-docs ask Como faço para lidar com tentativas de webhook?

/pluggy-docs search [consulta]#

Pesquise na documentação por páginas que correspondam à sua consulta. Retorna uma lista de páginas relevantes com links diretos.

/pluggy-docs search connect widget

/pluggy-docs endpoint [método] [caminho]#

Procure detalhes para um endpoint de API específico, incluindo parâmetros, esquemas de solicitação/resposta e exemplos.

/pluggy-docs endpoint POST /items

Configurando Resumos Diários#

O recurso de resumo diário resume automaticamente perguntas e tópicos comuns de seus canais de ajuda, facilitando a identificação de problemas recorrentes e lacunas na documentação.

Configurando um Canal de Resumo#

1. Convide o bot para os canais que você deseja que ele monitore para perguntas.
2. Use o seguinte comando slash no canal onde você deseja que os resumos sejam postados:

/pluggy-docs digest setup #help-channel

Substitua #help-channel pelo canal que você deseja que o bot monitore.

3. Configure o cronograma do resumo (o padrão é diariamente às 9:00 AM UTC):

/pluggy-docs digest schedule 09:00 UTC

Opções de Configuração do Resumo#

Solução de Problemas#

O bot não responde a comandos slash#

• Verifique se a URL do Ponto de Interações está configurada corretamente como https://your-domain/api/discord/interactions e foi salva com sucesso.
• Verifique se seu servidor está em execução e acessível pela internet pública.
• Certifique-se de que o bot tenha a permissão Usar Comandos Slash no canal.

Erro "Interação falhou"#

• Confirme se a variável de ambiente DISCORD_PUBLIC_KEY corresponde à Chave Pública exibida no Discord Developer Portal em Informações Gerais.
• O Discord requer uma resposta dentro de 3 segundos. Se seu servidor demorar mais, certifique-se de que você está usando respostas adiadas.

O bot está online, mas não lê mensagens#

• Verifique se a intenção privilegiada Conteúdo da Mensagem está ativada no Developer Portal em Bot > Intenções de Gateway Privilegiadas.
• Verifique se o bot recebeu a permissão Ler Histórico de Mensagens nos canais relevantes.

O resumo diário não está postando#

• Confirme se o bot tem permissão Enviar Mensagens no canal de destino.
• Verifique se o resumo está ativado executando /pluggy-docs digest setup novamente.
• Verifique os logs do servidor para quaisquer erros relacionados ao trabalho cron do resumo.

O bot não pode ser adicionado ao servidor#

• Certifique-se de que você tem a permissão Gerenciar Servidor no servidor Discord.
• Verifique se a URL OAuth2 inclui os escopos corretos (bot e applications.commands).
• Verifique se o bot não foi banido do servidor.