Criar um aplicativo Bolt

Objetivos de aprendizagem 

Após concluir esta unidade, você estará apto a:

• Habilitar seu aplicativo Bolt para acessar o Slack.
• Explicar as funções de ouvinte.
• Adicionar ouvintes de eventos ao seu aplicativo.
• Adicionar interatividade ao aplicativo.

Remixar o modelo de aplicativo Bolt para Javascript no Glitch

Com o aplicativo configurado e instalado, é hora de configurar um novo aplicativo Bolt com as credenciais do seu aplicativo.

Para simplificar o desenvolvimento, este módulo usa o Glitch, uma ferramenta que simplifica a criação e a hospedagem de aplicativos. Embora uma conta do Glitch gratuita seja ótima para o desenvolvimento, seu servidor não permanecerá em execução enquanto o aplicativo estiver ocioso. Isso significa que você precisa manter o Glitch aberto no seu navegador enquanto desenvolve e testa o aplicativo.

Quando seu aplicativo estiver pronto para a produção, talvez seja melhor hospedá-lo em outro lugar ou fazer upgrade da sua conta do Glitch. Há uma lista completa de provedores de hospedagem recomendados no site da API.

Se você preferir executar seu aplicativo localmente, poderá usar uma ferramenta como ngrok. Há um exemplo de uso de ngrok no guia de introdução da documentação.

1. Abra seu ambiente do Glitch.
2. Clique neste link para remixar (ou clonar) o projeto inicial do Bolt.
3. Quando o remix for concluído, o projeto aparecerá na sua lista de projetos. No exemplo, ele tem o nome de actually-triangular-pigeon.
4. Clique no seu projeto para carregá-lo.
5. Em seguida, clique em app.js.

No arquivo app.js, você pode ver o pacote @slack/bolt importado e instanciado. Abaixo disso, o servidor do aplicativo está configurado e executado para poder receber eventos recebidos do Slack.

Você adicionará outros depois. Primeiro, adicione as credenciais da configuração do aplicativo Slack. Lembre-se de manter o Glitch aberto durante todo esse processo. 

Volte para a página do aplicativo no site da API do Slack.

Adicionar as credenciais do aplicativo

Recupere seu segredo de assinatura e o token de acesso OAuth do usuário bot. 

1. Vá para a página de configuração do aplicativo Slack no site da API do Slack.
2. Clique em Basic Information (Informações básicas) na barra lateral.
3. Role para baixo até a seção Credenciais do aplicativo.
4. Copie seu segredo de assinatura e guarde-o para o próximo passo no editor de texto.
5. Clique em OAuth & Permissions (OAuth e permissões) na barra lateral.
6. Clique em Copy (Copiar) a fim de copiar o token de acesso OAuth do usuário bot e salvá-lo para o próximo passo.

Com seu segredo e token salvos, volte para o Glitch.

1. Em seu projeto do Glitch, navegue até o arquivo .env localizado na barra lateral esquerda.
2. Cole o token de acesso OAuth do usuário bot no campo Valor de variável logo após SLACK_BOT_TOKEN (1).
3. Cole o segredo de assinatura no campo Valor de variável logo após SLACK_SIGNING_SECRET (2). O aplicativo usa o segredo de assinatura para verificar se as solicitações recebidas estão vindo do Slack. O Bolt lida com a verificação automaticamente quando o segredo de assinatura é transmitido ao construtor do aplicativo.

Se você clicar em Logs (Registros) na parte inferior do navegador de arquivos do Glitch, deverá ver o aplicativo Bolt em execução.

Conheça as funções de ouvinte

Os aplicativos Slack normalmente recebem e respondem de uma a muitas solicitações do Slack. Para cada tipo de solicitação recebida do Slack, há uma função de ouvinte correspondente para tratar e responder. 

Aqui está um subconjunto dos ouvintes aos quais os aplicativos Bolt podem transmitir uma função.

A lista completa pode ser encontrada na documentação de referência do Bolt. É hora de configurar seu aplicativo para escutar e responder a eventos, interações e interatividades! 

Inscrever-se em eventos

Para escutar eventos da API de eventos, seu aplicativo precisará habilitar assinaturas de eventos.

1. Vá até a página do aplicativo Slack no site da API do Slack, se ainda não estiver lá.
2. Clique em Event Subscriptions (Assinaturas de evento) na barra lateral.
3. As assinaturas de evento devem ser ativadas automaticamente. Você também pode ativá-las no botão, se necessário.
4. Você verá uma caixa de entrada para inserir uma URL de solicitação. Uma URL de solicitação é onde as solicitações HTTP são enviadas para eventos nos quais seu aplicativo está inscrito. Se você criou seu aplicativo com o modelo, sua URL de solicitação atualmente é https://project-name.glitch.me/slack/events.
5. Em vez de project-name, adicione o nome do seu próprio projeto do Glitch.
   1. Clique em Settings (Configurações) e em Go to project page (Ir para a página do projeto). A URL do site ativo contém o nome do projeto, que é tudo depois https:// e antes de .glitch.me.
6. Volte para a página de assinaturas de eventos no site da API do Slack e insira a URL de solicitação. Ele deve ser mais ou menos assim, https://actually-triangular-pigeon.glitch.me/slack/events
   O Bolt para JavaScript escuta todas as solicitações recebidas na rota /slack/events por padrão e é por isso que ele é anexado à URL de solicitação.
7. Clique em Save Changes (Salvar alterações) para salvar seu trabalho.
8. Em seguida, clique em Subscribe to bot events (Assinar eventos de bot) para abrir a seção. Aqui você vê message.channels em Nome do evento. Esse evento escuta todas as mensagens publicadas nos canais públicos em que seu aplicativo está. Com a URL de solicitação ativada, seu aplicativo deve começar a receber esses eventos.

Adicionar um ouvinte de eventos

As assinaturas do evento utilizam o ouvinte event(), cujos exemplos você pode encontrar na documentação do Bolt. Por enquanto, use o ouvinte message() para ouvir e responder às mensagens.

1. Vá para o projeto do Glitch.
2. Adicione o que segue ao seu arquivo app.js, pouco abaixo de // Espaço para seu código

app.message('hello', async ({ message, say }) => {
    await say(`Hey there <@${message.user}>`);
});

O Glitch salva seu trabalho automaticamente.

Nos bastidores, o ouvinte message() é o mesmo que usar app.event("message", fn) além do parâmetro adicional say() transmitido à função de ouvinte. O parâmetro say() expõe a URL de resposta do evento que, ao contrário de chamar chat.postMessage(), não requer escopos adicionais para responder aos eventos message.

Enquanto o Glitch estiver funcionando em uma guia separada, seu aplicativo deverá ser reiniciado automaticamente. Agora você pode enviar uma mensagem que contém "olá" dentro do canal ao que o aplicativo foi adicionado. O aplicativo deve responder.

Esse exemplo básico é um lugar para começar a personalizar seu aplicativo com base no seu caso de uso. Vamos tentar algo um pouco mais interativo enviando um elemento de botão em vez de texto simples.

Configurar interatividade

Para usar recursos como botões, menus de seleção, seletores de data, modais e atalhos, você precisará habilitar a interatividade. Semelhante às assinaturas de eventos, você precisa especificar uma URL de solicitação para o Slack enviar a solicitação de ação (por exemplo, um usuário clicou no botão).

1. De volta à página de configuração do aplicativo do Slack, clique em Interactivity & Shortcuts (Interatividade e atalhos) na barra lateral.
2. Alterne a Interatividade para On (Ativa). Você verá que há outra caixa de URL de solicitação.
3. Por padrão, o Bolt está configurado para usar o mesmo ponto de extremidade para componentes interativos que ele usa em eventos, ou seja, use a mesma URL de solicitação acima.
4. Clique em Save Changes (Salvar alterações) no canto inferior direito da página e pronto! Seu aplicativo está configurado para lidar com interatividade.

Adicionar um ouvinte de ação para responder à mensagem

Ao ouvir a interatividade, use o ouvinte action(). Antes de configurar o ouvinte action(), modifique o ouvinte message() para enviar um elemento de botão.

1. Vá para o projeto do Glitch.
2. No app.js, substitua o trecho de código anterior para incluir uma nova seção.

// Message listener function called for messages containing "hello"
app.message('hello', async ({ message, say }) => {
    await say({
        "blocks": [
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": `👋 Hey there <@${message.user}>`
                },
                "accessory": {
                    "type": "button",
                    "text": {
                        "type": "plain_text",
                        "text": "Click Me",
                        "emoji": true
                    },
                    "action_id": "click_me_button"
                }
            }
        ]
    });
});

O valor de say() é agora um objeto que contém uma matriz de blocos. Blocos são componentes de uma mensagem do Slack e podem variar de texto e imagens a seletores de datas. Nesse caso, ele contém um bloco de seção que inclui um botão como acessório.

Para criar mensagens e outras superfícies do Kit de blocos, você pode usar o Block Kit Builder (Criador do kit de blocos). Ele tem um conjunto de modelos internos para casos de uso comuns e uma interface conveniente de arrastar e soltar com a carga JSON correspondente à direita.

O Kit de blocos não pode preencher notificações ou pesquisar por padrão, ou seja, o campo text deve ser usado para tornar suas mensagens mais acessíveis. Para saber mais sobre o campo de texto, há informações na página de referência chat.postMessage.

No objeto acessório de botão, há uma action_id. Isso funciona como um identificador único que você pode transmitir à função de ouvinte para escutar apenas eventos interativos correspondentes àquele elemento de bloco.

Seu aplicativo deve ser reiniciado; você, então, poderá enviar outra mensagem contendo Olá que seu aplicativo responderá com uma mensagem contendo o elemento de botão. Mas se você clicar no botão, nada acontecerá (ainda!).

Adicionar um ouvinte de ação para responder a uma interação de botão

Vamos adicionar uma função de ouvinte action() para responder ao clique do botão com uma mensagem de acompanhamento.

1. Volte para seu projeto do Glitch.
2. Adicione o ouvinte de ação a seguir ao app.js

// Action listener function called when an interactive component with action_id of “click_me_button” is triggered
app.action('click_me_button', async ({ ack, body, client, say }) => {
    // Acknowledge action request before anything else
    await ack();
    let channelID = body.channel.id
    let userID = body.user.id
    // Respond to action with an ephemeral message
    await client.chat.postEphemeral({
    channel: channelID,
    user: userID,
    text: `<@${userID}> clicked the button! 🎉 `
  });
});

Observe ack() sendo chamado dentro da função de ouvinte. ack() é usado para reconhecer que seu aplicativo recebeu o evento do Slack. Depois que o aplicativo for reiniciado, você poderá clicar no botão novamente e seu aplicativo responderá com a nova mensagem.

Se você está tendo problemas em executar o aplicativo, dê uma olhada no código pronto em actions.js dentro da pasta de exemplos do projeto. 

Para onde vamos daqui?

Agora você tem seu primeiro aplicativo Bolt para JavaScript que usa conceitos centrais do Bolt para ouvir e responder a diferentes eventos vindos do Slack! 

Com o básico, você pode começar a explorar mais recursos do Bolt e da plataforma. Aqui estão alguns caminhos que você pode pensar em trilhar.

• Percorra a pasta de exemplos dentro do seu projeto do Glitch. Existem alguns arquivos com diferentes amostras de código que você pode copiar e colar no projeto.
• Leia a documentação do Bolt para JavaScript para saber mais sobre funcionalidade avançada e encontre trechos de código que demonstram o que é possível.
• Aumente o nível do design do seu aplicativo usando o Criador de kit de blocos.

Explore outras superfícies às quais seu aplicativo tenha acesso, como a guia Início e os modais de pop-up.