Express-msteams-host NPM

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 SHOULD be implemented as a class extending the TeamsBot class and decorated using the BotDeclaration decorator.

import { BotDeclaration, TeamsBot } from 'express-msteams-host';
import * as teamBuilder from 'botbuilder-teams';

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

    public constructor(connector: teamBuilder.TeamsChatConnector) {
        super(connector);
        ...
    }

}

A bot could also be implemented by implementing the IBot interface and the BotDeclaration decorator, which is how it was done in version 1.0.? and earlier. But such an implementation would require manual implementation of message extensions.

Decorators for Message Extensions

Message Extensions MUST be a class implementing the IMessageExtension interface and when declared in the bot implementation decorated with the MessageExtensionDeclarator decorator.

import { IMessageExtension } from 'express-msteams-host';


export default class MyMessageExtension implements IMessageExtension {
    constructor(private bot: builder.UniversalBot) {
    }

    public onQuery(event: builder.IEvent, query: teamBuilder.ComposeExtensionQuery, callback: (err: Error, result: teamBuilder.IComposeExtensionResponse, statusCode: number) => void): void {
       ...
    }

    // this is used when canUpdateConfiguration is set to true 
    public onQuerySettingsUrl(event: builder.IEvent, query: teamBuilder.ComposeExtensionQuery, callback: (err: Error, result: teamBuilder.IComposeExtensionResponse, statusCode: number) => void): void {
        ...
    }

    public onSettingsUpdate(event: builder.IEvent, query: teamBuilder.ComposeExtensionQuery, callback: (err: Error, result: teamBuilder.IComposeExtensionResponse, statusCode: number) => void): void {
       ...
    }

}

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, and then you must invoke the registerMessageExtensions() method.

import { BotDeclaration, TeamsBot, MessageExtensionDeclaration } from 'express-msteams-host';
import * as teamBuilder from 'botbuilder-teams';
import { MyMessageExtension } from './MyMessageExtension';

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

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

    public constructor(connector: teamBuilder.TeamsChatConnector) {
        super(connector);
        ...

        this._myMessageExtension = new MyMessageExtension(this.universalBot);

        super.registerMessageExtensions();
    }

}

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',
    'web/myConnectorConnect.ejs',
    '/myConnectorConnected.html'
)
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 {
        ...
    }
}