什么是邮件扩展?What are messaging extensions?

邮件扩展允许用户通过 Microsoft 团队客户端中的按钮和表单与 web 服务进行交互。Messaging extensions allow users to interact with your web service through buttons and forms in the Microsoft Teams client. 他们可以通过撰写邮件区域、命令框或直接从邮件中搜索或启动外部系统中的操作。They can search, or initiate actions, in an external system from the compose message area, the command box, or directly from a message. 然后,您可以将该交互的结果发送回 Microsoft 团队客户端(通常采用格式丰富的卡片的形式)。You can then send the results of that interaction back to the Microsoft Teams client, typically in the form of a richly formatted card.

下面的屏幕截图显示可以从中调用邮件扩展的位置。The screenshot below shows the locations where messaging extensions can be invoked from.


哪些类型的任务适合?What kinds of tasks are they good for?

方案: 我需要一些外部系统执行某些操作,并希望将操作的结果发送回我的对话。Scenario: I need some external system to do something and I want the result of the action to be sent back to my conversation.</span> 示例: 预订资源并让频道知道您为其预留的日期/时间。Example: Reserve a resource and let the channel know what day/time you reserved it for.

方案: 我需要在外部系统中查找内容,我想要与我的对话共享结果。Scenario: I need to find something in an external system, and I want to share the results with my conversation.</span> 示例: 在 Azure DevOps 中搜索工作项,并将其与组共享为自适应卡片。Example: Search for a work item in Azure DevOps, and share it with the group as an adaptive card.

方案: 我需要在外部系统中完成涉及多个步骤 (或大量信息) 的复杂任务,并且应与会话共享结果。Scenario: I need to complete a complex task involving multiple steps (or lots of information) in an external system, and the results should be shared with a conversation.</span> 示例: 在跟踪系统中创建基于团队消息的 bug,将该 bug 分配给 Bob,然后将卡片发送给会话线程,并提供 bug 的详细信息。Example: Create a bug in your tracking system based on a Teams message, assign that bug to Bob, then send a card to the conversation thread with the bug's details.

邮件扩展功能扩展的工作原理是什么?How do messaging extensions work?

邮件扩展由您承载的 web 服务和应用程序清单组成,该服务定义在 Microsoft 团队客户端中可从何处调用 web 服务。A messaging extension consists of a web service you host and your app manifest which defines where your web service can be invoked from in the Microsoft Teams client. 他们利用 Bot 框架的邮件架构和安全通信协议,因此您还需要将 web 服务注册为 Bot 框架中的 bot。They take advantage of the Bot Framework's messaging schema and secure communication protocol, so you'll also need to register your web service as a bot in the Bot Framework. 尽管您可以手动创建 web 服务,但我们建议您充分利用Bot 框架 SDK来更简单地使用协议。Although you can create your web service completely by hand, we recommend you take advantage of the Bot Framework SDK to make working with the protocol simpler.

在 Microsoft 团队应用程序的应用程序清单中,你将定义最大为十个不同命令的单一消息扩展。In the app manifest for your Microsoft Teams app you'll define a single messaging extension with up to ten different commands. 每个命令定义一种类型 (操作或搜索) ,并且客户端中的位置可以从 (撰写邮件区域、命令栏和/或邮件) 中调用。Each command defines a type (action or search), and the locations in the client it can be invoked from (compose message area, command bar, and/or message). 调用后,web 服务将收到具有 JSON 有效负载的 HTTPS 消息,其中包括所有相关信息。Once invoked, your web service will receive an HTTPS message with a JSON payload including all the relevant information. 你将使用 JSON 有效负载进行响应,让团队客户端了解下一步要启用的交互。You'll respond with a JSON payload, letting the Teams client know what interaction to enable next.

邮件扩展命令的类型Types of messaging extension commands

消息扩展命令的类型定义了可用于 web 服务的 UI 元素和交互流。The type of messaging extension command defines the UI elements and interaction flows available to your web service. 某些交互(如身份验证和配置)可用于这两种类型的命令。Some interactions, like authentication and configuration, are available for both types of commands.

操作命令Action commands

操作命令使您可以向用户呈现模式弹出窗口,以收集或显示信息。Action commands allow you to present your users with a modal popup to collect or display information. 当用户提交表单时,您的 web 服务可以通过直接在对话中插入邮件,或在撰写邮件区域中插入邮件并允许用户提交邮件来做出响应。When they submit the form, your web service can respond by inserting a message into the conversation directly, or by inserting a message into the compose message area and allowing the user to submit the message. 甚至可以将多个表单链接在一起,以获取更复杂的工作流。You can even chain multiple forms together for more complex workflows.

它们可以通过撰写邮件区域、命令框或邮件触发。They can be triggered from the compose message area, the command box, or from a message. 从邮件中调用时,发送到你的 bot 的初始 JSON 有效负载将包含从中调用的整个邮件。When invoked from a message, the initial JSON payload sent to your bot will include the entire message it was invoked from.


搜索命令Search commands

搜索命令允许用户在搜索框中手动搜索外部系统,或者通过将指向受监视域的链接粘贴到 "撰写" 邮件区域中来 (的信息) ,然后将搜索结果插入到邮件中。Search commands allow your users to search an external system for information (either manually through a search box, or by pasting a link to a monitored domain into the compose message area), then insert the results of the search into a message. 在最基本的搜索命令流中,初始调用邮件将包含用户提交的搜索字符串。In the most basic search command flow, the initial invoke message will include the search string the user submitted. 你将使用卡片和卡片预览的列表进行响应。You'll respond with a list of cards and card previews. 团队客户端将在列表中呈现卡片预览,以便最终用户可以从中进行选择。The Teams client will render the card previews in a list for the end user to select from. 当用户选择卡片时,完整大小的卡片将插入到撰写邮件区域中。When the user selects a card, the full-size card will be inserted into the compose message area.

它们可以通过撰写消息区域或命令框触发。They can be triggered from the compose message area or the command box. 与 action 命令不同,它们不能从邮件中触发。Unlike action commands, they cannot be triggered from a message.


在将 URL 粘贴到撰写邮件区域中时,您还可以选择调用您的服务。You also have the option to invoke your service when a URL is pasted in the compose message area. 此功能称为链接 unfurling,使您可以在将包含特定域的 url 粘贴到撰写邮件区域时订阅接收调用。This functionality, known as link unfurling, allows you to subscribe to receive an invoke when URLs containing a particular domain are pasted into the compose message area. 您的 web 服务可以将 URL "unfurl" 到详细卡片中,提供的信息比标准网站预览卡更多。Your web service can "unfurl" the URL into a detailed card, providing more information than the standard website preview card. 您甚至可以添加按钮以允许用户立即执行操作,而无需离开 Microsoft 团队客户端。You can even add buttons to allow your users to immediately take action without leaving the Microsoft Teams client.

开始使用Get Started

准备好开始构建了吗?Ready to get started building? 尝试一下我们的快速入门:Try one of our quickstarts:

了解详细信息Learn more

构建消息扩展:Build a messaging extension: