Integração com Slack

Visão Geral#

A integração do Pluggy Docs com o Slack traz a busca por documentação e perguntas e respostas impulsionadas por IA diretamente para o seu espaço de trabalho do Slack. Sua equipe pode pesquisar documentos, fazer perguntas sobre a API do Pluggy e consultar detalhes de endpoints sem sair do Slack.

Pré-requisitos#

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

• Acesso de administrador ao espaço de trabalho do Slack — Você precisa de permissão para instalar aplicativos em seu espaço de trabalho.
• Uma instância do Pluggy Docs implantada — Sua plataforma de documentação deve ser acessível via uma URL pública com HTTPS.
• Uma conta do Slack em api.slack.com.

Passo 1: Criar um Aplicativo do Slack#

1. Vá para api.slack.com/apps e clique em Criar Novo App.
2. Selecione Do zero.
3. Insira um nome para seu aplicativo (por exemplo, "Pluggy Docs") e selecione o espaço de trabalho onde você deseja instalá-lo.
4. Clique em Criar App.

Você será levado à página de Informações Básicas do aplicativo. Mantenha esta página aberta — você precisará de valores dela em etapas posteriores.

Passo 2: Configurar Escopos OAuth#

Navegue até OAuth & Permissões na barra lateral esquerda. Em Escopos, adicione os seguintes Escopos de Token de Bot:

Passo 3: Configurar a API de Eventos#

A API de Eventos permite que o Slack envie notificações em tempo real para sua instância do Pluggy Docs quando os usuários interagem com o bot.

1. Navegue até Assinaturas de Eventos na barra lateral esquerda.
2. Ative Habilitar Eventos para Ativado.
3. No campo URL de Solicitação, insira:

https://your-domain/api/slack/events

Substitua your-domain pelo seu domínio real de implantação do Pluggy Docs. O Slack enviará um desafio de verificação para esta URL — seu servidor deve responder corretamente para que a URL seja verificada.

4. Em Inscrever-se em eventos de bot, adicione os seguintes eventos:

5. Clique em Salvar Alterações.

Passo 4: Configurar Comandos de Barra#

Os comandos de barra permitem que os usuários interajam com o bot usando o comando /pluggy-docs.

1. Navegue até Comandos de Barra na barra lateral esquerda.
2. Clique em Criar Novo Comando.
3. Preencha os seguintes campos:

4. Clique em Salvar.

Passo 5: Definir Variáveis de Ambiente#

Você precisa de três variáveis de ambiente do seu aplicativo Slack para conectá-lo à sua instância do Pluggy Docs. Encontre esses valores na página de Informações Básicas do seu aplicativo Slack em Credenciais do App.

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

SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_SIGNING_SECRET=your-signing-secret

Passo 6: Instalar o App#

Existem duas maneiras de instalar o bot do Pluggy Docs no Slack:

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/slack/install

Isso redirecionará para a tela de consentimento OAuth do Slack, onde o administrador do espaço de trabalho pode autorizar o bot.

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

Você pode incorporar um botão "Adicionar ao Slack" em sua documentação ou ferramentas internas que linka para o endpoint de instalação:

<a href="https://your-domain/api/slack/install">
  <img
    alt="Adicionar ao Slack"
    height="40"
    width="139"
    src="https://platform.slack-edge.com/img/add_to_slack.png"
  />
</a>

Comandos Disponíveis#

Uma vez que o bot esteja instalado, sua equipe pode usar os seguintes comandos:

/pluggy-docs ask [pergunta]#

Faça uma pergunta em linguagem natural sobre a API ou plataforma do Pluggy. O bot usa busca impulsionada por IA para encontrar a documentação mais relevante e fornecer uma resposta resumida.

/pluggy-docs ask Como configuro webhooks para atualizações de transações?

/pluggy-docs search [consulta]#

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

/pluggy-docs search autenticação

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

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

/pluggy-docs endpoint GET /accounts/{id}

Mensagens Diretas#

Você também pode enviar mensagens diretas para o bot. Basta abrir uma conversa com o bot do Pluggy Docs e digitar sua pergunta — nenhum comando de barra é necessário.

Menções#

Mencione o bot em qualquer canal onde ele esteja convidado para fazer perguntas inline:

@Pluggy Docs Quais escopos são necessários para o Connect Widget?

Solução de Problemas#

O bot não responde a mensagens#

• Verifique se a URL de Solicitação da API de Eventos está corretamente definida como https://your-domain/api/slack/events e mostra uma marca de verificação verde.
• Confirme se os eventos message.im e app_mention estão inscritos em Inscrever-se em eventos de bot.
• Verifique se seu servidor está em execução e acessível a partir da internet pública.

O comando de barra retorna um erro#

• Verifique se a URL de Solicitação do Comando de Barra está definida como https://your-domain/api/slack/commands.
• Certifique-se de que a variável de ambiente SLACK_SIGNING_SECRET corresponda ao valor na página de Informações Básicas do seu aplicativo Slack.
• O Slack requer uma resposta dentro de 3 segundos. Se seu servidor estiver lento, considere implementar respostas diferidas.

Erros "not_authed" ou "invalid_auth"#

• Confirme se SLACK_CLIENT_ID e SLACK_CLIENT_SECRET estão definidos corretamente.
• Reinstale o aplicativo em seu espaço de trabalho para gerar um novo token de bot.

A verificação da URL de solicitação falha#

• Certifique-se de que seu servidor esteja acessível publicamente via HTTPS.
• Verifique se seu servidor lida corretamente com o desafio de url_verification do Slack, respondendo com o valor de challenge do corpo da solicitação.