适用于：SDK v4
本文基于机器人工作原理和事件驱动对话中学到的内容；在继续之前，应熟悉这些文章。
Microsoft Teams 上开发的机器人的主要的不同是处理活动的方式。 “Teams 活动处理程序”派生自“活动处理程序”，并在处理更多常规活动类型之前处理特定于 Teams 的活动类型。
重要
Bot Framework SDK 和 Bot Framework Emulator 已在 GitHub 上存档。 项目不再更新或维护。 自 2025 年 12 月 31 日起，Bot Framework SDK 的支持票证将不再提供服务。
若要使用所选的 AI 服务、业务流程和知识生成代理，请考虑使用 Microsoft 365 代理 SDK。 代理 SDK 对 C#、JavaScript 或 Python 具有语言支持。 可以在 aka.ms/agents 了解有关代理 SDK 的详细信息。
如果现有的机器人是使用 Bot Framework SDK 生成的，则可以将机器人更新到代理 SDK。 查看 Bot Framework SDK 到代理 SDK 迁移指南的核心更改和更新。
如果要构建设计为在 Microsoft Teams 中工作的协作代理，请考虑使用 Teams SDK。 它为在 Teams 环境中运行的代理提供 Teams 特定的 API、自适应卡支持和内置 AI 协同调度功能。 可以在 Teams SDK（Teams AI 库）中了解详细信息。
如果要查找基于 SaaS 的代理平台，请考虑 Microsoft Copilot Studio。
Teams 活动处理程序
若要为 Teams 创建机器人，请从 “Teams 活动处理程序”类派生机器人。 当此类机器人收到活动时，它会通过各种“活动处理程序”路由活动。 初始基处理程序是“轮次处理程序”，它根据活动的类型将活动路由到处理程序。
轮次处理程序调用专门用于处理所接收到的特定活动类型的处理程序。 “Teams 活动处理程序”类派生自“活动处理程序”类。 除了“活动处理程序”可以处理的活动类型外，Teams 活动处理程序类还包括 Teams 特定活动的其他处理程序。
从 Teams 活动处理程序派生的机器人类似于直接从活动处理程序类派生的机器人。
不过，Teams 会在 conversationUpdate 活动中包含其他信息，并发送 Teams 特有的 invoke 和 event 活动。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 OnMessageActivityAsync 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 OnConversationUpdateActivityAsync 处理程序将处理该活动。
大多数特定于 Teams 的活动处理程序都没有基础实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessage 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 dispatchConversationUpdateActivity 处理程序将处理该活动。
大多数 Teams 特定的活动处理程序都没有基础实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
在替代这些特定于 Teams 的活动处理程序时，请定义机器人逻辑，并“务必在最后调用 next()”。 调用 next() 可确保运行下一个处理程序。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 onMessageActivity 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 onConversationUpdateActivity 处理程序将处理该活动。
对于大多数特定于 Teams 的活动处理程序，都没有提供基础实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
当 Teams 活动处理程序机器人收到消息活动时，其轮次处理程序会将传入消息活动路由到其 on_message_activity 处理程序，类似于基于活动处理程序的机器人的行事方式。 但是，当 Teams 机器人收到对话更新活动时，Teams 版本的 on_conversation_update_activity 处理程序将处理该活动。
大多数特定于 Teams 的活动处理程序都没有基础实现。 需要替代这些处理程序并为机器人提供适当的逻辑。
活动处理部分中在使用活动处理程序的事件驱动型对话一文里介绍的所有活动处理程序，都将继续像在非 Teams 机器人中一样工作；但处理成员添加和删除活动的情况除外，因为在团队上下文中，这些活动有所不同：新成员是被添加到团队中，而不是消息线程中。 有关详细信息，请参阅 Teams 会话更新活动。
若要为这些特定于 Teams 的活动处理程序实现逻辑，需要替代机器人中的方法。
Teams 机器人逻辑
机器人逻辑处理来自一个或多个机器人通道的传入活动，并在响应中生成传出活动。 对于派生自 Teams 活动处理程序类的机器人也仍是如此，该处理程序首先检查 Teams 活动，然后将所有其他活动传递给 Bot Framework 的活动处理程序。
Teams 安装和更新活动
为 安装更新 事件添加处理函数，使您的机器人能够：
- 在对话线程上安装时发送介绍性消息。
- 从线程卸载时清理用户和线程数据。
有关详细信息，请参阅 Teams 文档中的安装更新事件。
Teams 聊天更新活动
下表列出了可在机器人中生成 对话更新 活动的 Teams 事件。
Microsoft Teams 对话更新事件一文介绍了如何使用每个事件。
下面列出了从 Teams 活动处理程序的 OnConversationUpdateActivityAsync 方法中调用的所有 Teams 活动处理程序。
| 事件类型 |
处理程序 |
条件 |
Teams 文档 |
| 频道已创建 |
OnTeamsChannelCreatedAsync |
每当在已安装此机器人的团队中创建新通道时，都会发送。 |
创建通道。 |
| 频道已删除 |
OnTeamsChannelDeletedAsync |
每当在已安装你的机器人的团队中删除某个通道时，都会发送此事件。 |
通道已删除。 |
| channelRenamed |
OnTeamsChannelRenamedAsync |
每当已安装你的机器人的团队中有频道被重命名时，都会发送。 |
已重命名通道。 |
| 通道已恢复 |
OnTeamsChannelRestoredAsync |
每当已安装你的机器人的团队中恢复先前已删除的频道时，都会发送此事件。 |
通道已还原。 |
| 已添加成员 |
OnTeamsMembersAddedAsync |
默认情况下，调用 ActivityHandler.OnMembersAddedAsync 方法。 首次将你的机器人添加到某个对话中时，以及每次将新用户添加到已安装你的机器人的团队或群聊中时，都会发送。 |
已添加团队成员。 |
| 已移除成员 |
OnTeamsMembersRemovedAsync |
默认情况下，调用 ActivityHandler.OnMembersRemovedAsync 方法。 如果您的机器人被从团队中移除，或者每当有用户被从您的机器人所属的团队中移除时，系统都会发送此通知。 |
已移除团队成员。 |
| 团队已归档 |
OnTeamsTeamArchivedAsync |
当安装了你的机器人的团队被存档时发送。 |
团队已存档。 |
| teamDeleted |
OnTeamsTeamDeletedAsync |
当你的机器人所在的团队被删除时发送。 |
团队已删除。 |
| teamRenamed |
OnTeamsTeamRenamedAsync |
当你的机器人所在的团队被重命名时发送。 |
团队已重命名。 |
| 团队已恢复 |
OnTeamsTeamRestoredAsync |
当你的机器人所在的之前已删除团队被恢复时发送。 |
团队已恢复。 |
| 团队已取消存档 |
OnTeamsTeamUnarchivedAsync |
当已安装你的机器人的团队被取消存档时发送。 |
团队未存档。 |
开发人员可以通过两种方法处理从 Microsoft Teams 发送的对话更新活动：
若要传入回调，请使用以 onand 开头并以 Event 结尾的方法（例如，onTeamsMembersAddedEvent 方法）。
在创建派生类时，重写以 on 开头且 不 以 Event 结尾的方法（例如，onTeamsMembersAdded 方法）。
开发人员对于同一活动应只使用这些选项中的一种：1 或 2，不应同时使用 两者。 这意味着，开发人员应当向 onTeamsMembersAddedEvent 方法传递回调函数或在派生类中重写 onTeamsMembersAdded 方法，而不是两者都做。
注册回调的方法
下面列出了由 Teams 活动处理程序的 dispatchConversationUpdateActivity 方法调用的所有 Teams 活动发出器。
| 事件类型 |
注册方法 |
条件 |
Teams 文档 |
| 频道已创建 |
onTeamsChannelCreatedEvent |
每当在已安装你的机器人的团队中创建新频道时，都会发送此事件。 |
创建通道。 |
| channelDeleted |
onTeamsChannelDeletedEvent |
每当已安装你的机器人的团队中有频道被删除时，都会发送。 |
通道已删除。 |
| 频道已重命名 |
onTeamsChannelRenamedEvent |
每当在已安装你的机器人的团队中有频道被重命名时，都会发送。 |
已重命名通道。 |
| 频道已恢复 |
onTeamsChannelRestoredEvent |
每当在已安装你的机器人的团队中恢复之前已删除的频道时，都会发送。 |
通道已还原。 |
| 已添加成员 |
onTeamsMembersAddedEvent |
在首次将机器人添加到对话中时发送；此后，每当有新用户被添加到已安装该机器人的团队或群聊中时，都会发送。 |
已添加团队成员。 |
| 已移除成员 |
onTeamsMembersRemovedEvent |
如果您的机器人被从团队中移除，或者每当有任何用户被从您的机器人所属的团队中移除时，都会发送此事件。 |
团队成员已移除。 |
| 团队已归档 |
onTeamsTeamArchivedEvent |
当已安装该机器人的团队被存档时发送。 |
团队已存档。 |
| 团队已删除 |
onTeamsTeamDeletedEvent |
当你的机器人所在的团队被删除时发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamedEvent |
当你的机器人所在的团队被重命名时发送。 |
团队已重命名。 |
| 团队已恢复 |
onTeamsTeamrestoredEvent |
当你的机器人所在的之前已删除团队被恢复时发送。 |
团队已恢复。 |
| 团队已取消存档 |
onTeamsTeamUnarchivedEvent |
当已安装你的机器人的团队被取消存档时发送。 |
团队未存档。 |
在派生类中替代的方法
下面列出了可以重载的所有 Teams 活动处理程序，以处理 Teams 对话更新活动。
| 事件类型 |
处理程序 |
条件 |
Teams 文档 |
| 频道已创建 |
onTeamsChannelCreated |
每当在已安装你的机器人的团队中创建了新通道时，都会发送。 |
创建通道。 |
| channelDeleted |
onTeamsChannelDeleted |
每当在已安装你的机器人的团队中删除频道时，都会发送。 |
通道已删除。 |
| 频道已重命名 |
onTeamsChannelRenamed |
每当在已安装你的机器人的团队中有频道被重命名时，都会发送此事件。 |
已重命名通道。 |
| 通道已恢复 |
onTeamsChannelRestored |
每当在已安装您的机器人的团队中恢复先前已删除的频道时，都会发送。 |
通道已还原。 |
| 已添加成员 |
onTeamsMembersAdded |
默认情况下，调用 ActivityHandler.onMembersAdded 方法。 在首次将该机器人添加到某个对话时，以及每次有新用户加入已安装该机器人的团队或群聊时发送。 |
已添加团队成员。 |
| 已移除成员 |
onTeamsMembersRemoved |
默认情况下，调用 ActivityHandler.onMembersRemoved 方法。 如果你的机器人被从某个团队中移除，或者每当任何用户被从你的机器人所属的团队中移除时，都会发送此通知。 |
已移除团队成员。 |
| 团队已归档 |
onTeamsTeamArchived |
当已安装此机器人的团队被存档时发送。 |
团队已存档。 |
| 团队已删除 |
onTeamsTeamDeleted |
当你的机器人所在的团队被删除时发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamed |
当你的机器人所在的团队被重命名时发送。 |
团队已重命名。 |
| 团队已恢复 |
onTeamsTeamRestored |
当你的机器人所在的之前已删除团队被恢复时发送。 |
团队已恢复。 |
| 团队已取消存档 |
onTeamsTeamUnarchived |
当已安装你的机器人的团队被取消存档时发送。 |
团队未存档。 |
下面列出了由 Teams 活动处理程序的 onConversationUpdateActivity 方法调用的所有 Teams 活动处理程序。
| 事件类型 |
处理程序 |
条件 |
Teams 文档 |
| 频道已创建 |
onTeamsChannelCreated |
每当已安装此机器人的团队中创建了新频道时，都会发送此事件。 |
创建通道。 |
| 频道已删除 |
onTeamsChannelDeleted |
每当已安装你的机器人的团队中有频道被删除时，都会发送。 |
通道已删除。 |
| 频道已重命名 |
onTeamsChannelRenamed |
每当已安装你的机器人的团队中的频道被重命名时发送。 |
已重命名通道。 |
| 通道已恢复 |
onTeamsChannelRestored |
每当在已安装你的机器人的团队中恢复先前已删除的频道时发送。 |
通道已还原。 |
| 已添加成员 |
onTeamsMembersAdded |
默认情况下，调用 ActivityHandler.onMembersAdded 方法。 首次将你的机器人添加到某个对话时，以及每次将新用户添加到已安装该机器人的团队或群聊时，都会发送。 |
已添加团队成员。 |
| 已移除成员 |
onTeamsMembersRemoved |
默认情况下，调用 ActivityHandler.onMembersRemoved 方法。 当你的机器人被从团队中移除时，以及每当有任何用户从你的机器人所属的团队中被移除时，都会发送此事件。 |
团队成员已移除。 |
| 团队已归档 |
onTeamsTeamArchived |
当已安装此机器人的团队被存档时发送。 |
团队已存档。 |
| 团队已删除 |
onTeamsTeamDeleted |
当你的机器人所在的团队被删除时发送。 |
团队已删除。 |
| teamRenamed |
onTeamsTeamRenamed |
当你的机器人所在的团队被重命名时发送。 |
团队已重命名。 |
| 团队已恢复 |
onTeamsTeamRestored |
当你的机器人所在的之前已删除团队被恢复时发送。 |
团队已恢复。 |
| 团队已取消存档 |
onTeamsTeamUnarchived |
当已安装你的机器人的团队被取消存档时发送。 |
团队未存档。 |
下面列出了从 Teams 活动处理程序的 on_conversation_update_activity 方法调用的所有 Teams 活动处理程序。
| 事件类型 |
处理程序 |
条件 |
Teams 文档 |
| 频道已创建 |
on_teams_channel_created |
每当在已安装你的机器人的团队中创建新通道时，都会发送。 |
创建通道。 |
| 频道已删除 |
on_teams_channel_deleted |
每当已安装你的机器人的团队中有频道被删除时，都会发送。 |
通道已删除。 |
| channelRenamed |
on_teams_channel_renamed |
当已安装你的机器人的团队中有频道被重命名时发送。 |
已重命名通道。 |
| 通道已恢复 |
on_teams_channel_restored |
每当在已安装你的机器人的团队中恢复此前已删除的频道时，都会发送此事件。 |
通道已还原。 |
| membersAdded |
on_teams_members_added |
默认情况下，调用基类 on_members_added_activity 方法。 在首次将你的机器人添加到会话中时，以及每次将新用户添加到已安装你的机器人的团队或群聊中时发送。 |
已添加团队成员。 |
| 已移除成员 |
on_teams_members_removed |
默认情况下，调用基类 on_members_removed_activity 方法。 如果你的机器人已从某个团队中移除，以及每当有用户从你的机器人所属的团队中被移除时，都会发送此事件。 |
团队成员已删除。 |
| 团队已归档 |
on_teams_team_archived |
当安装了该机器人的团队被存档时发送。 |
团队已存档。 |
| 团队已删除 |
on_teams_team_deleted |
当你的机器人所在的团队被删除时发送。 |
团队已删除。 |
| teamRenamed |
on_teams_team_renamed |
当你的机器人所在的团队被重命名时发送。 |
团队已重命名。 |
| 团队已恢复 |
on_teams_team_restored |
当你的机器人所在的之前已删除团队被恢复时发送。 |
团队已恢复。 |
| 团队已取消存档 |
on_teams_team_unarchived |
当已安装你的机器人的团队被取消存档时发送。 |
团队未存档。 |
Teams 事件活动
下表列出了 Teams 发送给机器人的 Teams 特有事件活动。
列出的事件活动适用于 Teams 中的对话机器人。
这些是由 OnEventActivityAsyncTeams 活动处理程序调用的 Teams 特有事件活动处理程序。
| 事件类型 |
处理程序 |
说明 |
| application/vnd.microsoft.meetingEnd |
OnTeamsMeetingEndAsync |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
OnTeamsMeetingStartAsync |
机器人与刚刚启动的会议相关联。 |
这些是由 onEventActivityTeams 活动处理程序调用的 Teams 特定事件活动处理程序。
| 事件类型 |
处理程序 |
说明 |
| application/vnd.microsoft.meetingEnd |
onTeamsMeetingEnd |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
onTeamsMeetingStart |
机器人与刚刚启动的会议相关联。 |
这些是由 onEventActivityTeams 活动处理程序调用的特定于 onEventActivityTeams 的事件活动处理程序。
| 事件类型 |
处理程序 |
说明 |
| application/vnd.microsoft.meetingEnd |
onTeamsMeetingEnd |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
onTeamsMeetingStart |
机器人与刚刚启动的会议相关联。 |
这些是由 on_event_activityTeams 活动处理程序调用的 Teams 特有事件活动处理程序。
| 事件类型 |
处理程序 |
说明 |
| application/vnd.microsoft.meetingEnd |
on_teams_meeting_end_event |
机器人与刚刚结束的会议相关联。 |
| application/vnd.microsoft.meetingStart |
on_teams_meeting_start_event |
机器人与刚刚启动的会议相关联。 |
Teams 调用活动
下表列出了 Teams 发送给机器人的 Teams 特有调用活动。
列出的调用活动适用于 Teams 中的对话机器人。 Bot Framework SDK 还支持特定于消息传送扩展的调用。 有关详细信息，请参阅 Teams 什么是消息传递扩展一文。
注意
Microsoft Teams 平台文档和 Teams JavaScript 客户端库 (TeamsJS) 将任务模块称为模式“对话”。 有关详细信息，请参阅对话。
下面列出了从 Teams 活动处理程序调用的所有 OnInvokeActivityAsyncTeams 活动处理程序：
| 调用类型 |
处理程序 |
说明 |
| 可操作消息/执行操作 |
OnTeamsO365ConnectorCardActionAsync |
Teams O365 连接器卡操作。 |
| CardAction.Invoke |
OnTeamsCardActionInvokeAsync |
Teams 卡片操作调用。 |
| fileConsent/invoke |
OnTeamsFileConsentAcceptAsync |
Teams 文件许可接受。 |
| fileConsent/invoke |
OnTeamsFileConsentAsync |
Teams 文件许可。 |
| fileConsent/invoke |
OnTeamsFileConsentDeclineAsync |
Teams 文件许可。 |
| signin/verifyState |
OnTeamsSigninVerifyStateAsync |
Teams 登录状态验证 |
| 任务/获取 |
OnTeamsTaskModuleFetchAsync |
Teams 任务模块获取。 |
| 任务/提交 |
OnTeamsTaskModuleSubmitAsync |
Teams 任务模块提交。 |
下面列出了从 Teams 活动处理程序调用的所有 onInvokeActivityTeams 活动处理程序：
| 调用类型 |
处理程序 |
说明 |
| actionableMessage/executeAction |
handleTeamsO365ConnectorCardAction |
Teams O365 连接器卡片操作。 |
| CardAction.Invoke |
handleTeamsCardActionInvoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
handleTeamsFileConsentAccept |
Teams 文件许可接受。 |
| fileConsent/invoke |
handleTeamsFileConsent |
Teams 文件许可。 |
| fileConsent/invoke |
handleTeamsFileConsentDecline |
Teams 文件许可。 |
| signin/verifyState |
handleTeamsSigninVerifyState |
Teams 登录状态验证 |
| task/fetch |
handleTeamsTaskModuleFetch |
Teams 任务模块（模式对话框）获取。 |
| task/submit |
handleTeamsTaskModuleSubmit |
Teams 任务模块（模态对话框）提交。 |
下面列出了从 Teams 活动处理程序调用的所有 onInvokeActivityTeams 活动处理程序：
| 调用类型 |
处理程序 |
说明 |
| fileConsent/invoke |
onTeamsFileConsent |
Teams 文件许可。 |
| 可操作消息/执行操作 |
onTeamsO365ConnectorCardAction |
Teams O365 连接器卡操作 |
| 任务/获取 |
onTeamsTaskModuleFetch |
Teams 任务模块获取。 |
| 任务/提交 |
onTeamsTaskModuleSubmit |
Teams 任务模块提交。 |
| tab/fetch |
onTeamsTabFetch |
Teams 选项卡提取。 |
| Tab/提交 |
onTeamsTabSubmit |
Teams 选项卡提交。 |
| CardAction.Invoke |
onTeamsCardActionInvoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
onTeamsFileConsentAccept |
接受 Teams 文件同意请求 |
| fileConsent/invoke |
onTeamsFileConsentDecline |
Teams 文件许可。 |
| signin/verifyState |
onTeamsSigninVerifyState |
Teams 登录验证状态。 |
下面列出了从 Teams 活动处理程序调用的所有 on_invoke_activityTeams 活动处理程序：
| 调用类型 |
处理程序 |
说明 |
| 可操作消息/执行操作 |
on_teams_o365_connector_card_action |
Teams O365 连接器卡片操作。 |
| CardAction.Invoke |
on_teams_card_action_invoke |
Teams 卡片操作调用。 |
| fileConsent/invoke |
on_teams_file_consent_accept |
Teams 文件许可接受。 |
| fileConsent/invoke |
on_teams_file_consent |
Teams 文件许可。 |
| fileConsent/invoke |
on_teams_file_consent_decline |
Teams 文件同意被拒绝。 |
| signin/verifyState |
on_teams_signin_verify_state |
Teams 登录验证状态 |
| task/fetch |
on_teams_task_module_fetch |
Teams 任务模块获取。 |
| 任务/提交 |
on_teams_task_module_submit |
Teams 任务模块提交。 |
后续步骤
有关构建 Teams 机器人的信息，请参阅 Microsoft Teams 开发人员文档。