Porta um Slack Bolt para aplicativo JavaScript para o Teams

Este guia ajudará você a portar um aplicativo Slack Bolt para JavaScript existente no Teams.

Introdução

Semelhante ao Slack Bolt, o SDK do Teams foi projetado para fazer interface com as APIs de back-end do Teams para criar aplicativos de conversa. Ambos os SDKs fornecem abstrações para lidar com eventos, mensagens e interações de entrada, bem como enviar respostas de volta aos usuários. Se você já tem um bot do Slack, os conceitos devem parecer familiares.

No entanto, há algumas diferenças importantes, como a instalação do aplicativo. No Slack, os aplicativos são instalados nos espaços de trabalho por meio do OAuth, enquanto que no Teams eles são instalados por meio da Teams App App Store. Além disso, os aplicativos do Teams podem ser instalados pessoalmente por usuários individuais ou em escopos colaborativos, como chats em grupo, canais e reuniões.

Vamos dar uma olhada em algumas semelhanças e diferenças entre os conceitos do Slack e do Teams:

Registrar um agente do Teams

Primeiro, conclua o início rápido para registrar um novo agente do Teams, para que você possa usá-lo no Teams assim que tiver adicionado a implementação do SDK do Teams ao seu aplicativo existente.

Instalar o SDK do Teams

Instale o SDK do Teams em seu projeto do Slack Bolt:

npm install @microsoft/teams.apps

Copiar configuração de autenticação

Copie as configurações do arquivo que a CLI do desenvolvedor do .env Teams criou no aplicativo de início rápido para a implementação do Slack Bolt. Essas configurações são credenciais para autenticar um aplicativo SDK do Teams para que ele possa se comunicar com o Teams.

Inicializar o tempo de execução

Adicione ou substitua o código em sua implementação para iniciar o tempo de execução do aplicativo SDK do Teams usando a App classe. Isso é equivalente à classe de App Slack Bolt.

import { App } from '@microsoft/teams.apps';

const app = new App();

app.start(process.env.PORT || 3978).catch(console.error);

const app = new App({
    signingSecret: process.env.SLACK_SIGNING_SECRET,
    clientId: process.env.SLACK_CLIENT_ID,
    clientSecret: process.env.SLACK_CLIENT_SECRET,
    scopes: [
        "channels:manage",
        "channels:read",
        "chat:write",
        "groups:read",
        "incoming-webhook",
    ],
    installerOptions: {
        authVersion: "v2",
        directInstall: false,
        installPath: "/slack/install",
        metadata: "",
        redirectUriPath: "/slack/oauth_redirect",
        stateVerification: "true",
        /**
        * Example pages to navigate to on certain callbacks.
        */
        callbackOptions: {
            success: (installation, installUrlOptions, req, res) => {
                res.send("The installation succeeded!");
            },
            failure: (error, installUrlOptions, req, res) => {
                res.send("Something strange happened...");
            },
        },
        /**
        * Example validation of installation options using a random state and an
        * expiration time between requests.
        */
        stateStore: {
            generateStateParam: async (installUrlOptions, now) => {
                const state = randomStringGenerator();
                const value = { options: installUrlOptions, now: now.toJSON() };
                await database.set(state, value);
                return state;
            },
            verifyStateParam: async (now, state) => {
                const value = await database.get(state);
                const generated = new Date(value.now);
                const seconds = Math.floor(
                    (now.getTime() - generated.getTime()) / 1000,
                );
                if (seconds > 600) {
                    throw new Error("The state expired after 10 minutes!");
                }
                return value.options;
            },
        },
    },
});

// App starts local server with route for /slack/events
(async () => {
    await app.start();
})();

Adicionar manipuladores de mensagens

No Slack, existem manipuladores de mensagens para eventos com diferentes subtipos (por exemplo, subtipo indefinido é uma mensagem normal, event.subtype == 'file_share' é uma mensagem de compartilhamento de arquivos etc.). No Teams, há diferentes Activity manipuladores para diferentes tipos de eventos que são enumerados por meio da enumeração (por ActivityTypes exemplo, app.activity(ActivityTypes.Message)), com alguns Activity tipos tendo APIs personalizadas no SDK (por exemplo, app.message). Esses conceitos são aproximadamente semelhantes, embora as convenções de nomenclatura e a sintaxe sejam diferentes.

// triggers when user sends "hi" or "@bot hi"
app.message("hi", async ({ send, activity }) => {
    await send(`Hello, ${activity.from.name}!`);
});
// listen for ANY message to be received
app.on('message', async ({ send, activity }) => {
    // echo back users request
    await send(`you said: ${activity.text}`);
});

// triggers when user sends a message containing "hi"
app.message("hi", async ({ message, say }) => {
    // Handle only newly posted messages here
    if (message.subtype) return;
    await say(`Hello, <@${message.user}>`);
});
// listen for ANY message
app.message(async ({ message, say }) => {
    // Handle only newly posted messages here
    if (message.subtype) return;
    // echo back users request
    await say(`you said: ${message.text}`);
});

Converter uso do Kit de Blocos em Cartões Adaptáveis

Para incluir uma interface do usuário avançada nas mensagens enviadas pelo seu agente, os Cartões Adaptáveis do Teams são equivalentes ao Kit de Bloqueio do Slack.

import { Card, TextBlock } from '@microsoft/teams.cards';

app.message('/card', async ({ send }) => {
    await send(
        new Card(new TextBlock('Hello, world!', { wrap: true, isSubtle: false }))
            .withOptions({
                width: 'Full',
            })
    );
});

app.message('card', async (client) => {
    await say({
        blocks: [
            {
                type: 'section',
                text: {
                    type: 'plain_text',
                    text: 'Hello, world!',
                },
            },
        ],
    });
});

Implementar autenticação de usuário

Há dois tipos principais de autenticação de usuário para o Teams e o Slack: autenticação para APIs REST do Slack & Graph e autenticação para serviços externos. Vamos dar uma olhada em cada um deles.

APIs REST delegadas pelo usuário

No Slack, se você quiser usar as APIs REST do Slack que exigem escopos delegados pelo usuário, será necessário implementar um fluxo de instalação do OAuth 2.0 em seu aplicativo para obter e armazenar tokens de usuário do Slack, mesmo que o aplicativo já tenha sido instalado por outro usuário. No Teams, você pode aproveitar o SSO do Teams para obter tokens do Entra do usuário para chamar APIs REST do Graph. O SDK do Teams integra-se ao SSO do Teams e ao Serviço de Token de Bot do Azure para lidar com a aquisição, o armazenamento e a atualização de token automaticamente para você.

Primeiro, siga as instruções no guia de SSO do Teams. Em seguida, configure a autenticação em seu código.

const app = new App({
    // ... rest of App config
    oauth: {
        // The key here should match the OAuth Connection setting
        // defined in your Azure Bot resource.
        defaultConnectionName: 'graph',
    },
});

app.message('me', async ({ signin, userGraph, send }) => {
    if (!await signin()) {
        return;
    }
    const me = await userGraph.call(endpoints.me.get);
    await send(JSON.stringify(me));
});

// TODO: Configure App class with user OAuth permissions and install app for user

app.message('me', async ({ client, message }) => {
    const me = await client.users.info({ user: message.user });
    await client.send(JSON.stringify(me));
});

Autenticação de usuário para serviços externos

No Slack, você pode acessar serviços externos implementando um fluxo de associação de conta usando o OAuth 2.0, conforme documentado aqui. No Teams, você pode acessar serviços externos implementando um fluxo OAuth 2.0, com o Serviço de Token de Bot do Azure lidando com a aquisição, o armazenamento e a atualização de tokens para você.

Primeiro, defina as configurações de conexão OAuth 2.0 no Portal do Azure para seu recurso de Bot do Azure.

Em seguida, adicione o código de autenticação ao seu aplicativo para obter o token de usuário relevante e chame seu serviço externo.

import
{ App } from '@microsoft/teams.apps';

const app = new App({
    // ... rest of App config
    oauth: {
        // The key here should match the OAuth Connection setting
        // defined in your Azure Bot resource.
        defaultConnectionName: 'custom',
    },
});

app.message('me', async ({ activity, signin, token, send }) => {
    // In production, it is probably better to implement a local cache.
    // (e.g. \`activity.from.id\` <-> token).
    // Otherwise this triggers an API call to Azure Token Service on every inbound message.
    if (!await signin()) {
        return;
    }

    // Call external API
    const response = await fetch('https://example.com/api/helloworld', {
        method: 'POST',
        headers: {
            "Authorization": token,
        },
    });
    const result = await response.json();
    await send(JSON.stringify(result));
});