Microsoft Teams Bot 的運作方式

適用於： SDK v4

本文是以 Bot 的運作方式和事件驅動對話中所學到的內容為基礎;您應該先熟悉這些文章，再繼續。

專為 Microsoft Teams 所開發的 Bot 主要差異在於活動的處理方式。 Teams 活動處理程式衍生自活動處理程式，並在處理更多一般活動類型之前處理 Teams 特定的活動類型。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Power Virtual Agents ，並閱讀 選擇正確的聊天機器人解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

Teams 活動處理程式

若要建立適用於 Teams 的 Bot，請從 Teams 活動處理程式 類別衍生您的 Bot。 當這類 Bot 收到活動時，它會透過各種 活動處理程式路由傳送活動。 初始基底處理程式是 回合處理程式，它會根據活動的型別，將活動路由傳送至處理程式。 回合處理程式會呼叫處理程式，其設計目的是要處理所接收的特定活動類型。 Teams 活動處理程式類別衍生自活動處理程序類別。 除了活動處理程式可以處理的活動類型之外，Teams 活動處理程式類別還包含 Teams 特定活動的其他處理程式。

衍生自 Teams 活動處理程式的 Bot 類似於直接衍生自活動處理程式類別的 Bot。 不過，Teams 會在活動中包含 conversationUpdate 其他資訊，並傳送 Teams 特定 invoke 和活動 event 。

C#

當 Teams 活動處理程式 - Bot 收到訊息活動時，其回合處理程式會將傳入訊息活動路由傳送至其 OnMessageActivityAsync 處理程式，類似於以活動處理程式為基礎的 Bot。 不過，當 Teams Bot 收到交談更新活動時，Teams 版本的 OnConversationUpdateActivityAsync 處理程式會處理活動。

大部分 Teams 特定活動處理程式都沒有基底實作。 您必須覆寫這些處理程式，併為 Bot 提供適當的邏輯。

JavaScript

當 Teams 活動處理程式 - Bot 收到訊息活動時，其回合處理程式會將傳入訊息活動路由傳送至其 onMessage 處理程式，類似於以活動處理程式為基礎的 Bot。 不過，當 Teams Bot 收到交談更新活動時，Teams 版本的 dispatchConversationUpdateActivity 處理程式會處理活動。

大部分 Teams 特定活動處理程式都沒有基底實作。 您必須覆寫這些處理程式，併為 Bot 提供適當的邏輯。

覆寫這些 Teams 特定的活動處理程式時，請定義 Bot 邏輯，然後請務必在結尾呼叫next()。 藉由呼叫 next()，您可以確定下一個處理程式正在執行。

Java

當 Teams 活動處理程式 - Bot 收到訊息活動時，其回合處理程式會將傳入訊息活動路由傳送至其 onMessageActivity 處理程式，類似於以活動處理程式為基礎的 Bot。 不過，當 Teams Bot 收到交談更新活動時，Teams 版本的 onConversationUpdateActivity 處理程式會處理活動。

大部分 Teams 特定活動處理程式都沒有基底實作。 您必須覆寫這些處理程式，併為 Bot 提供適當的邏輯。

Python

當 Teams 活動處理程式 - Bot 收到訊息活動時，其回合處理程式會將傳入訊息活動路由傳送至其 on_message_activity 處理程式，類似於以活動處理程式為基礎的 Bot。 不過，當 Teams Bot 收到交談更新活動時，Teams 版本的 on_conversation_update_activity 處理程式會處理活動。

大部分 Teams 特定活動處理程式都沒有基底實作。 您必須覆寫這些處理程式，併為 Bot 提供適當的邏輯。

使用活動處理程式之事件驅動對話一節中所述的所有活動處理程式都會繼續像處理非 Teams Bot 一樣運作，除了處理新增和移除活動的成員之外，這些活動在小組的內容中會有所不同，而新成員會新增至小組，而不是訊息線程。 如需詳細資訊，請參閱 Teams交談更新活動。

若要實作這些 Teams 特定活動處理程式的邏輯，您將覆寫 Bot 中的方法。

Teams-Bot 邏輯

Bot 邏輯會處理來自一或多個 Bot 通道的連入活動，併產生傳出活動以回應。 這仍然是衍生自 Teams 活動處理程式類別的 Bot，該類別會先檢查 Teams 活動，然後將所有其他活動傳遞至 Bot Framework 的活動處理程式。

Teams 安裝更新活動

新增安裝更新事件的處理程式，讓您的 Bot：

• 在對話線程上安裝簡介訊息時傳送訊息。
• 從線程卸載時清除用戶和線程數據。

如需詳細資訊，請參閱 Teams 檔中的安裝更新事件 。

Teams 交談更新活動

下表列出在 Bot 中產生 交談更新 活動的 Teams 事件。 Microsoft Teams 交談更新事件 文章說明如何使用這些事件。

C#

以下是從 OnConversationUpdateActivityAsync Teams 活動處理程式的 方法 呼叫的所有 Teams 活動處理程式清單。

EventType	處理常式	Condition	Teams 檔
channelCreated	OnTeamsChannelCreatedAsync	每當在您的 Bot 安裝於小組中建立新頻道時傳送。	已建立通道。
channelDeleted	OnTeamsChannelDeletedAsync	每當您的 Bot 安裝於小組中刪除頻道時傳送。	通道已刪除。
channelRenamed	OnTeamsChannelRenamedAsync	每當您的 Bot 安裝於小組中重新命名頻道時傳送。	通道已重新命名。
channelRestored	OnTeamsChannelRestoredAsync	每當先前刪除的通道在 Bot 已安裝的小組中還原時傳送。	通道已還原。
membersAdded	OnTeamsMembersAddedAsync	根據預設，會呼叫 ActivityHandler.OnMembersAddedAsync 方法。 第一次將 Bot 新增至交談時傳送，而且每次將新使用者新增至 Bot 安裝於小組或群組聊天時。	已新增小組成員。
membersRemoved	OnTeamsMembersRemovedAsync	根據預設，會呼叫 ActivityHandler.OnMembersRemovedAsync 方法。 如果您的 Bot 已從小組中移除，而且每次從 Bot 所屬的小組中移除任何使用者時，都會傳送。	已移除小組成員。
teamArchived	OnTeamsTeamArchivedAsync	當 Bot 安裝於中的小組封存時傳送。	已封存小組。
teamDeleted	OnTeamsTeamDeletedAsync	當 Bot 所屬的小組已刪除時傳送。	小組已刪除。
teamRenamed	OnTeamsTeamRenamedAsync	當 Bot 所屬的小組已重新命名時傳送。	小組已重新命名。
teamRestored	OnTeamsTeamRestoredAsync	還原 Bot 先前刪除的小組時傳送。	小組已還原。
teamUnarchived	OnTeamsTeamUnarchivedAsync	當 Bot 安裝到的小組未封存時傳送。	小組未封存。

JavaScript

開發人員可以透過兩種方法處理從 Microsoft Teams 傳送的交談更新活動：

1. 若要傳入回呼，請使用開頭為 on和 結尾 Event 的方法（例如 onTeamsMembersAddedEvent ，方法）。
2. 建立衍生類別時，請覆寫以 開頭 on 且 不 以 結尾 Event 的方法（例如 onTeamsMembersAdded ，方法）。

開發人員應該只使用下列其中一個選項：1 或 2，而不是 同時 用於相同的活動。 也就是說，開發人員應該將回呼傳遞至 onTeamsMembersAddedEvent 方法，或覆寫onTeamsMembersAdded衍生類別中的方法，而不要同時執行這兩個動作。

註冊回呼的方法

以下是從 dispatchConversationUpdateActivity Teams 活動處理程式的 方法呼叫的所有 Teams 活動發出者清單。

EventType	註冊方法	Condition	Teams 檔
channelCreated	onTeamsChannelCreatedEvent	每當在您的 Bot 安裝於小組中建立新頻道時傳送。	已建立通道。
channelDeleted	onTeamsChannelDeletedEvent	每當您的 Bot 安裝於小組中刪除頻道時傳送。	通道已刪除。
channelRenamed	onTeamsChannelRenamedEvent	每當您的 Bot 安裝於小組中重新命名頻道時傳送。	通道已重新命名。
channelRestored	onTeamsChannelRestoredEvent	每當先前刪除的通道在 Bot 已安裝的小組中還原時傳送。	通道已還原。
membersAdded	onTeamsMembersAddedEvent	第一次將 Bot 新增至交談時傳送，而且每次將新使用者新增至 Bot 安裝於小組或群組聊天時。	已新增小組成員。
membersRemoved	onTeamsMembersRemovedEvent	如果您的 Bot 已從小組中移除，而且每次從 Bot 所屬的小組中移除任何使用者時，都會傳送。	已移除小組成員。
teamArchived	onTeamsTeamArchivedEvent	當 Bot 安裝於中的小組封存時傳送。	已封存小組。
teamDeleted	onTeamsTeamDeletedEvent	當 Bot 所屬的小組已刪除時傳送。	小組已刪除。
teamRenamed	onTeamsTeamRenamedEvent	當 Bot 所屬的小組已重新命名時傳送。	小組已重新命名。
teamRestored	onTeamsTeamrestoredEvent	還原 Bot 先前刪除的小組時傳送。	小組已還原。
teamUnarchived	onTeamsTeamUnarchivedEvent	當 Bot 安裝到的小組未封存時傳送。	小組未封存。

在衍生類別中覆寫的方法

以下是可覆寫以處理Teams交談更新活動的所有Teams活動處理程式清單。

EventType	處理常式	Condition	Teams 檔
channelCreated	onTeamsChannelCreated	每當在您的 Bot 安裝於小組中建立新頻道時傳送。	已建立通道。
channelDeleted	onTeamsChannelDeleted	每當您的 Bot 安裝於小組中刪除頻道時傳送。	通道已刪除。
channelRenamed	onTeamsChannelRenamed	每當您的 Bot 安裝於小組中重新命名頻道時傳送。	通道已重新命名。
channelRestored	onTeamsChannelRestored	每當先前刪除的通道在 Bot 已安裝的小組中還原時傳送。	通道已還原。
membersAdded	onTeamsMembersAdded	根據預設，會呼叫 ActivityHandler.onMembersAdded 方法。 第一次將 Bot 新增至交談時傳送，而且每次將新使用者新增至 Bot 安裝於小組或群組聊天時。	已新增小組成員。
membersRemoved	onTeamsMembersRemoved	根據預設，會呼叫 ActivityHandler.onMembersRemoved 方法。 如果您的 Bot 已從小組中移除，而且每次從 Bot 所屬的小組中移除任何使用者時，都會傳送。	已移除小組成員。
teamArchived	onTeamsTeamArchived	當 Bot 安裝於中的小組封存時傳送。	已封存小組。
teamDeleted	onTeamsTeamDeleted	當 Bot 所屬的小組已刪除時傳送。	小組已刪除。
teamRenamed	onTeamsTeamRenamed	當 Bot 所屬的小組已重新命名時傳送。	小組已重新命名。
teamRestored	onTeamsTeamRestored	還原 Bot 先前刪除的小組時傳送。	小組已還原。
teamUnarchived	onTeamsTeamUnarchived	當 Bot 安裝到的小組未封存時傳送。	小組未封存。

Java

以下是從 onConversationUpdateActivity Teams 活動處理程式的 方法 呼叫的所有 Teams 活動處理程式清單。

EventType	處理常式	Condition	Teams 檔
channelCreated	onTeamsChannelCreated	每當在您的 Bot 安裝於小組中建立新頻道時傳送。	已建立通道。
channelDeleted	onTeamsChannelDeleted	每當您的 Bot 安裝於小組中刪除頻道時傳送。	通道已刪除。
channelRenamed	onTeamsChannelRenamed	每當您的 Bot 安裝於小組中重新命名頻道時傳送。	通道已重新命名。
channelRestored	onTeamsChannelRestored	每當先前刪除的通道在 Bot 已安裝的小組中還原時傳送。	通道已還原。
membersAdded	onTeamsMembersAdded	根據預設，會呼叫 ActivityHandler.onMembersAdded 方法。 第一次將 Bot 新增至交談時傳送，而且每次將新使用者新增至 Bot 安裝於小組或群組聊天時。	已新增小組成員。
membersRemoved	onTeamsMembersRemoved	根據預設，會呼叫 ActivityHandler.onMembersRemoved 方法。 如果您的 Bot 已從小組中移除，而且每次從 Bot 所屬的小組中移除任何使用者時，都會傳送。	已移除小組成員。
teamArchived	onTeamsTeamArchived	當 Bot 安裝於中的小組封存時傳送。	已封存小組。
teamDeleted	onTeamsTeamDeleted	當 Bot 所屬的小組已刪除時傳送。	小組已刪除。
teamRenamed	onTeamsTeamRenamed	當 Bot 所屬的小組已重新命名時傳送。	小組已重新命名。
teamRestored	onTeamsTeamRestored	還原 Bot 先前刪除的小組時傳送。	小組已還原。
teamUnarchived	onTeamsTeamUnarchived	當 Bot 安裝到的小組未封存時傳送。	小組未封存。

Python

以下是從 on_conversation_update_activity Teams 活動處理程式的 方法 呼叫的所有 Teams 活動處理程式清單。

EventType	處理常式	Condition	Teams 檔
channelCreated	on_teams_channel_created	每當在您的 Bot 安裝於小組中建立新頻道時傳送。	已建立通道。
channelDeleted	on_teams_channel_deleted	每當您的 Bot 安裝於小組中刪除頻道時傳送。	通道已刪除。
channelRenamed	on_teams_channel_renamed	每當您的 Bot 安裝於小組中重新命名頻道時傳送。	通道已重新命名。
channelRestored	on_teams_channel_restored	每當先前刪除的通道在 Bot 已安裝的小組中還原時傳送。	通道已還原。
membersAdded	on_teams_members_added	根據預設，呼叫基類 on_members_added_activity 方法。 第一次將 Bot 新增至交談時傳送，而且每次將新使用者新增至 Bot 安裝於小組或群組聊天時。	已新增小組成員。
membersRemoved	on_teams_members_removed	根據預設，呼叫基類 on_members_removed_activity 方法。 如果您的 Bot 已從小組中移除，而且每次從 Bot 所屬的小組中移除任何使用者時，都會傳送。	已移除小組成員。
teamArchived	on_teams_team_archived	當 Bot 安裝於中的小組封存時傳送。	已封存小組。
teamDeleted	on_teams_team_deleted	當 Bot 所屬的小組已刪除時傳送。	小組已刪除。
teamRenamed	on_teams_team_renamed	當 Bot 所屬的小組已重新命名時傳送。	小組已重新命名。
teamRestored	on_teams_team_restored	還原 Bot 先前刪除的小組時傳送。	小組已還原。
teamUnarchived	on_teams_team_unarchived	當 Bot 安裝到的小組未封存時傳送。	小組未封存。

Teams 活動活動

下表列出Teams傳送至 Bot 的 Teams 特定事件活動。 列出的事件活動適用於Teams中的交談式 Bot。

C#

這些是從 Teams 活動處理程式呼叫 OnEventActivityAsync的 Teams 特定事件處理程式。

事件類型	處理常式	描述
application/vnd.microsoft.meetingEnd	OnTeamsMeetingEndAsync	Bot 與剛剛結束的會議相關聯。
application/vnd.microsoft.meetingStart	OnTeamsMeetingStartAsync	Bot 與剛開始的會議相關聯。

JavaScript

這些是從 Teams 活動處理程式呼叫 onEventActivity的 Teams 特定事件處理程式。

事件類型	處理常式	描述
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	Bot 與剛剛結束的會議相關聯。
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	Bot 與剛開始的會議相關聯。

Java

這些是從 Teams 活動處理程式呼叫 onEventActivity的 Teams 特定事件處理程式。

事件類型	處理常式	描述
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	Bot 與剛剛結束的會議相關聯。
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	Bot 與剛開始的會議相關聯。

Python

這些是從 Teams 活動處理程式呼叫 on_event_activity的 Teams 特定事件處理程式。

事件類型	處理常式	描述
application/vnd.microsoft.meetingEnd	on_teams_meeting_end_event	Bot 與剛剛結束的會議相關聯。
application/vnd.microsoft.meetingStart	on_teams_meeting_start_event	Bot 與剛開始的會議相關聯。

Teams 叫用活動

下表列出Teams傳送至 Bot 的 Teams 特定叫用活動。 列出的叫用活動適用於Teams中的交談 Bot。 Bot Framework SDK 也支援呼叫傳訊擴充功能特有的 。 如需詳細資訊，請參閱 Teams 什麼是傳訊擴充 功能一文。

注意

Microsoft Teams 平台檔和 Teams JavaScript 用戶端連結庫 （TeamsJS） 會將工作模組稱為強制回應 對話方塊。 如需詳細資訊，請參閱對話方塊。

C#

以下是從 OnInvokeActivityAsyncTeams 活動處理程式呼叫的所有 Teams 活動處理程式清單：

叫用類型	處理常式	描述
actionableMessage/executeAction	OnTeamsO365ConnectorCardActionAsync	Teams O365 連線 或卡片動作。
CardAction.Invoke	OnTeamsCardActionInvokeAsync	Teams 卡片動作叫用。
fileConsent/invoke	OnTeamsFileConsentAcceptAsync	Teams 檔案同意接受。
fileConsent/invoke	OnTeamsFileConsentAsync	Teams 檔案同意。
fileConsent/invoke	OnTeamsFileConsentDeclineAsync	Teams 檔案同意。
signin/verifyState	OnTeamsSigninVerifyStateAsync	Teams 登入驗證狀態。
task/fetch	OnTeamsTaskModuleFetchAsync	Teams 工作模組擷取。
task/submit	OnTeamsTaskModuleSubmitAsync	Teams 工作模組提交。

JavaScript

以下是從 onInvokeActivityTeams 活動處理程式呼叫的所有 Teams 活動處理程式清單：

叫用類型	處理常式	描述
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 工作模組 （強制回應對話框） 提交。

Java

以下是從 onInvokeActivityTeams 活動處理程式呼叫的所有 Teams 活動處理程式清單：

叫用類型	處理常式	描述
fileConsent/invoke	onTeamsFileConsent	Teams 檔案同意。
actionableMessage/executeAction	onTeamsO365ConnectorCardAction	Teams O365 連線 或卡片動作。
task/fetch	onTeamsTaskModuleFetch	Teams 工作模組擷取。
task/submit	onTeamsTaskModuleSubmit	Teams 工作模組提交。
索引標籤/擷	onTeamsTabFetch	Teams 索引標籤取。
索引標籤/提交	onTeamsTabSubmit	Teams 索引標籤提交。
CardAction.Invoke	onTeamsCardActionInvoke	Teams 卡片動作叫用。
fileConsent/invoke	onTeamsFileConsentAccept	Teams 檔案同意接受。
fileConsent/invoke	onTeamsFileConsentDecline	Teams 檔案同意。
signin/verifyState	onTeamsSigninVerifyState	Teams 登入驗證狀態。

Python

以下是從 on_invoke_activityTeams 活動處理程式呼叫的所有 Teams 活動處理程式清單：

叫用類型	處理常式	描述
actionableMessage/executeAction	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 工作模組擷取。
task/submit	on_teams_task_module_submit	Teams 工作模組提交。

下一步

如需建置Teams Bot，請參閱 Microsoft Teams 開發人員 檔。