express-msteams-host
Version:
Express utility for Microsoft Teams solutions
173 lines (123 loc) • 6.91 kB
Markdown
# Express utility for Microsoft Teams Apps
[](https://www.npmjs.com/package/express-msteams-host)
[](https://www.npmjs.com/package/express-msteams-host)
[](https://github.com/wictorwilen/express-msteams-host/blob/master/LICENSE.md)
[](https://github.com/wictorwilen/express-msteams-host/issues)
[](https://github.com/wictorwilen/express-msteams-host/issues?q=is%3Aissue+is%3Aclosed)
This utility for [Express](https://expressjs.com/) is targeted for [Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/) applications built generated by the [Microsoft Teams Yeoman generator](https://aka.ms/yoteams) hosted on Express.
| @master | @preview |
:--------:|:---------:
[](https://travis-ci.org/wictorwilen/express-msteams-host)|[](https://travis-ci.org/wictorwilen/express-msteams-host)
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.
``` TypeScript
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
> **NOTE:** This method is deprecated and might be deleted in the future. For now it will remain available for usage.
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](http://expressjs.com/en/4x/api.html#middleware-callback-function-examples). 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.
``` TypeScript
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](https://github.com/wictorwilen/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.
``` TypeScript
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.
``` TypeScript
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 `IOutgoingWebhook` interface and decorated using the `OutgoingWebhookDeclaration` decorator.
``` TypeScript
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.
``` TypeScript
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](https://www.npmjs.com/package/debug) 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.