https://github.com/wictorwilen/botbuilder-teams-messagingextensions
Microsoft Teams Messaging Extension Middleware for Microsoft Bot Builder
https://github.com/wictorwilen/botbuilder-teams-messagingextensions
botbuilder botbuilder-extension botbuilder-framework microsoft-teams msteams
Last synced: 2 months ago
JSON representation
Microsoft Teams Messaging Extension Middleware for Microsoft Bot Builder
- Host: GitHub
- URL: https://github.com/wictorwilen/botbuilder-teams-messagingextensions
- Owner: wictorwilen
- License: mit
- Created: 2019-03-29T07:51:09.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-02T03:48:41.000Z (over 2 years ago)
- Last Synced: 2024-10-25T22:33:06.599Z (7 months ago)
- Topics: botbuilder, botbuilder-extension, botbuilder-framework, microsoft-teams, msteams
- Language: TypeScript
- Size: 605 KB
- Stars: 14
- Watchers: 2
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Microsoft Teams Messaging Extension Middleware for Microsoft Bot Builder
[](https://badge.fury.io/js/botbuilder-teams-messagingextensions)
This middleware for [Bot Builder Framework](https://www.npmjs.com/package/botbuilder) is targeted for [Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/) based bots.
| @master | @preview |
:--------:|:---------:
[](https://travis-ci.org/wictorwilen/botbuilder-teams-messagingextensions)|[](https://travis-ci.org/wictorwilen/botbuilder-teams-messagingextensions)
## About
The Microsoft Teams [Messaging Extension](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/messaging-extensions-overview?view=msteams-client-js-latest) Middleware for Microsoft Bot Builder makes building bots for Microsoft Teams easier. By separating out the logic for Message Extensions from the implementation of the bot, you will make your code more readable and easier to debug and troubleshoot.
The middleware supports the following Message Extension features
* [Message extension queries](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/search-extensions): `composeExtension/query`
* [Message extension settings url](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/search-extensions#add-event-handlers): `composeExtension/querySettingUrl`
* [Message extension settings](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/search-extensions#add-event-handlers): `composeExtension/setting`
* [Message extension link unfurling](https://developer.microsoft.com/en-us/office/blogs/add-rich-previews-to-messages-using-link-unfurling/): `composeExtension/queryLink`
* [Message extension message actions](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/create-extensions): `composeExtension/submitAction`
* [Fetch task operations for message actions](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/create-extensions): `composeExtension/fetchTask`
* Adaptive Card `Action.Submit` actions: `composeExtension/onCardButtonClicked`
* [Message extension select](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/messaging-extensions/search-extensions): `composeExtension/selectItem`
## Usage
To implement a Messaging Extension handler create a class like this:
> NOTE: When combining this with the `botbuilder-teams` you should avoid using the `invokeActivityHandler.onInvoke`, as it might
> invalidate your messaging extension results.
``` TypeScript
import { TurnContext, CardFactory, MessagingExtensionQuery, MessagingExtensionResult } from "botbuilder";
import { IMessagingExtensionMiddlewareProcessor } from "botbuilder-teams-messagingextensions";
export default class MyMessageExtension implements IMessagingExtensionMiddlewareProcessor {
public async onQuery(query: MessagingExtensionQuery): Promise {
const card = CardFactory.heroCard("Test", "Test", ["https://picsum.photos/200/200"]);
if (query.parameters && query.parameters[0] && query.parameters[0].name === "initialRun") {
return Promise.resolve({
type: "result",
attachmentLayout: "grid",
attachments: [
card
]
});
} else {
return Promise.resolve({
type: "result",
attachmentLayout: "list",
attachments: [
card
]
});
}
}
public async onQuerySettingsUrl(): Promise<{ title: string, value: string }> {
return Promise.resolve({
title: "Configuration",
value: "https://my-service-com/config.html"
});
}
public async onSettingsUpdate(context: TurnContext): Promise {
const setting = context.activity.value.state;
// Save the setting
return Promise.resolve();
}
}
```
To add the processor to the pipeline use code similar to this:
``` TypeScript
import { MessagingExtensionMiddleware } from "botbuilder-teams-messagingextensions";
const adapter = new BotFrameworkAdapter(botSettings);
adapter.user(new MessagingExtensionMiddleware("myCommandId", new MyMessageExtension()));
```
Where you should match the command id with the one in the Teams manifest file:
``` JSON
"composeExtensions": [{
"botId": "12341234-1234-1234-123412341234",
"canUpdateConfiguration": true,
"commands": [{
"id": "myCommandId",
"title": "My Command",
"description": "...",
"initialRun": true,
"parameters": [...]
}]
}],
```
### Use message actions and task modules
To create an message action that shows a task module for your input define your message extension as follows in the manifest. The `fetchTask` property set to `true` indicates that we want to use a task module.
``` JSON
{
"id": "createToDoMessageExtension",
"title": "Create To-Do",
"description": "Create a To-Do item",
"context": ["message", "commandBox", "compose"],
"fetchTask": true,
"type": "action"
}
```
In the processor you need to implement the `onFetchTask` and `onSubmitAction` methods. You can either return a card using the `card` property or
use the `url` parameter to point to a web page.
``` TypeScript
public async onFetchTask(context: TurnContext, value: MessagingExtensionAction): Promise {
return Promise.resolve({
type: "continue",
value: {
title: "Task Module",
card: CardFactory.adaptiveCard({
$schema: "http://adaptivecards.io/schemas/adaptive-card.json",
type: "AdaptiveCard",
version: "1.0",
body: [
{
type: "TextBlock",
text: "Please enter your e-mail"
},
{
type: "Input.Text",
id: "myEmail",
placeholder: "[email protected]",
style: "email"
},
],
actions: [
{
type: "Action.Submit",
title: "OK",
data: { id: "unique-id" }
}
]
})
}
});
}
// handle response in here
public async onSubmitAction(context: TurnContext, value: MessagingExtensionAction): Promise {
const email = value.data.myEmail;
const id = value.data.id;
...
}
```
## Contributors
* [Wictor Wilén](https://github.com/wictorwilen) - Original author and coordinator
* [Thomas White](https://github.com/tdwhite0)
* [Bill Bliss](https://github.com/billbliss)
* [greyseer256](https://github.com/greyseer256)
* [Kavin Singh](https://github.com/kavins14)
## License
Copyright (c) Wictor Wilén. All rights reserved.
Licensed under the MIT license.