Port a Slack Bolt for JavaScript app to Teams

This guide will help you port an existing Slack Bolt for JavaScript application to Teams.

Introduction

Similar to Slack Bolt, the Teams SDK is designed to interface with the Teams backend APIs for building conversational applications. Both SDKs provide abstractions for handling incoming events, messages, and interactions, as well as sending responses back to users. If you already have a Slack bot, the concepts should feel familiar.

However, there are some key differences, such as app installation. In Slack, apps are installed to workspaces via OAuth, whereas in Teams they are installed via the Teams App Store. Additionally, Teams apps can be installed personally by individual users, or to collaborative scopes like group chats, channels, and meetings.

Let's take a look at some similarities and differences between Slack and Teams concepts:

Register a Teams agent

First, complete the quickstart to register a new Teams agent, so you can use it from Teams as soon as you have added the Teams SDK implementation to your existing app.

Install Teams SDK

Install the Teams SDK into your Slack Bolt project:

npm install @microsoft/teams.apps

Copy authentication configuration

Copy the settings from the .env file that the Teams developer CLI created in the quickstart starter application to your Slack Bolt implementation. These settings are credentials for authenticating a Teams SDK app so it can communicate with Teams.

Initialize the runtime

Add or replace code in your implementation to start up the Teams SDK application runtime using the App class. This is equivalent to Slack Bolt's App class.

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();
})();

Add message handlers

In Slack, there are message handlers for events with different subtypes (e.g., undefined subtype is a regular message, event.subtype == 'file_share' is a file share message, etc.). In Teams, there are different Activity handlers for different types of events that are enumerated via the ActivityTypes enum (e.g., app.activity(ActivityTypes.Message)), with some Activity types having tailored APIs within the SDK (e.g., app.message). These concepts are roughly similar, though the naming conventions and syntax differ.

// 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}`);
});

Convert Block Kit usage to Adaptive Cards

To include rich UI in messages sent by your agent, Teams's Adaptive Cards are equivalent to Slack's Block Kit.

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!',
                },
            },
        ],
    });
});

Implement user authentication

There are two primary types of user authentication for Teams and Slack: authentication for Slack & Graph REST APIs, and authentication for external services. Let's take a look at each of these in turn.

User-delegated REST APIs

In Slack, if you want to use Slack REST APIs that require user-delegated scopes, you need to implement an OAuth 2.0 installation flow in your application to obtain and store Slack user tokens, even if the app was already installed by another user. In Teams, you can leverage Teams SSO to obtain user Entra tokens for calling Graph REST APIs. The Teams SDK integrates with Teams SSO and Azure Bot Token Service to handle token acquisition, storage, and refresh automatically for you.

First, follow the instructions in the Teams SSO guide. Then, configure authentication in your code.

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));
});

User authentication for external services

In Slack, you can access external services by implementing an account binding flow using OAuth 2.0 as documented here. In Teams, you can access external services by implementing an OAuth 2.0 flow, with the Azure Bot Token Service handling token acquisition, storage, and refresh for you.

First, setup your OAuth 2.0 connection settings in the Azure Portal for your Azure Bot resource.

Then, add the authentication code to your application to get the relevant user token and call your external service.

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));
});