stephanbisser / express-msteams-host

Express utility for Microsoft Teams solutions

Express utility for Microsoft Teams Apps

This utility for Express is targeted for Microsoft Teams applications built generated by the Microsoft Teams Yeoman generator hosted on Express.

@master	@preview

The Middleware serves two major purposes:

• Automatic routing of web services for Bots, Connectors and Outgoing Webhooks based on TypeScript decorators
• Automatic routing of static pages for Tabs and Connectors

The middleware is automatically added to projects generated by the Microsoft Teams Yeoman generator.

Usage

For the automatic routing to work the following usage MUST be followed.

Creating a bot

Implementation and decorator usage for Bots

Bots MUST be implemented as a class extending the TeamsActivityHandler class and decorated using the BotDeclaration decorator.

import { BotDeclaration } from 'express-msteams-host';
import { MemoryStorage, ConversationState, TurnContext, TeamsActivityHandler, BotFrameworkAdapter } from 'botbuilder';

@BotDeclaration(
    '/api/messages',
    new MemoryStorage(),
    process.env.MICROSOFT_APP_ID,
    process.env.MICROSOFT_APP_PASSWORD)
export class myBot extends TeamsActivityHandler {

    public constructor(conversationState: ConversationState, private adapter: BotFrameworkAdapter) {
        super();
        ...
        this.onMessage(async (context: TurnContext): Promise<void> => {
           ...
        });
        ...
    }

}

Adding support for Calling in bots

When adding calling support to bots you need to create an incoming webhook method of your bot implementation. This method should be decorated with the BotCallingWebhook decorator and must follow the Express middleware signature. The endpoint you specify in the decorator, has to represent the calling endpoint you specify when registering the Teams Channel to your Bot in the Azure portal.

import { BotDeclaration, BotCallingWebhook } from 'express-msteams-host';
import express = require("express");

@BotDeclaration(...)
export class myBot extends TeamsActivityHandler {

    @BotCallingWebhook("/api/calling")
    public async onIcomingCall(req: express.Request, res: express.Response, next: express.NextFunction) {
        ...
    }
}

Decorators for Message Extensions

Message Extensions is implemented using the Bot Builder middleware botbuilder-teams-messagingextensions and when referenced in the bot implementation decorated with the MessageExtensionDeclarator decorator. The express-msteams-host will automatically hook up the correct messaging extensions with the correct bot.

In the implementation of the bot, define the message extensions as below. You are responsible for instantiating the object, you might want to add additional parameters or configuration.

import { BotDeclaration } from 'express-msteams-host';
import { MemoryStorage, ConversationState, TurnContext, TeamsActivityHandler, BotFrameworkAdapter } from 'botbuilder';
import { MyMessageExtension } from './MyMessageExtension';
import { TeamsAdapter } from "botbuilder-teams";

@BotDeclaration(
    '/api/messages',
    new MemoryStorage()
    process.env.MICROSOFT_APP_ID,
    process.env.MICROSOFT_APP_PASSWORD)
export class myBot extends TeamsActivityHandler {

    @MessageExtensionDeclaration('myMessageExtension')
    private _myMessageExtension: MyMessageExtension;

    public constructor(private conversationState: ConversationState, private adapter: BotFrameworkAdapter) {
        super();
        ...
        this._myMessageExtension = new MyMessageExtension();
        ...
    }

}

Decorator for Connectors

Connectors MUST be implemented as a class implementing the IConnector interface and decorated using the ConnectorDeclaration decorator.

import { ConnectorDeclaration, IConnector } from 'express-msteams-host';
import { Request } from "express";

@ConnectorDeclaration(
    '/api/connector/connect',
    '/api/connector/ping',
)
export class myConnector implements IConnector {
    Connect(req: Request): void {
        ...
    }

    Ping(req: Request): Promise<void>[] {
        ...
    }
}

Decorator for Outgoing Webhooks

Outgoing Webhooks MUST be implemented as a class implementing the IOutdegoingWebhook interface and decorated using the OutgoingWebhookDeclaration decorator.

import { OutgoingWebhookDeclaration, IOutgoingWebhook } from 'express-msteams-host';
import * as express from 'express';

@OutgoingWebhookDeclaration('/api/webhook')
export class myOutgoingWebhook implements IOutgoingWebhook {
    public requestHandler(req: Express.Request, res: Express.Response, next: Express.NextFunction): any {
        ...
    }
}

Preventing pages to be iframed in other applications than Microsoft Teams

By using the PreventIframe decorator on server side classes pages can be declared to include a CSP that prohibts the pages from being iframed into other applications than Microsoft Teams.

import { PreventIframe } from "express-msteams-host";

@PreventIframe("/page/index.html")
export class MyPage {
    ...
}

Logging

To enable logging from this module you need to add msteams to the DEBUG environment variable. See the debug package for more information.

Example for Windows command line:

SET DEBUG=msteams

License

Copyright (c) Wictor Wilén. All rights reserved.

Licensed under the MIT license.