microsoft/teams.net
Publicmirrored from https://github.com/microsoft/teams.netAvailable
core/src/Microsoft.Teams.Bot.Apps/Api/ActivitiesApi.cs
222lines · modecode
| 1 | // Copyright (c) Microsoft Corporation. |
| 2 | // Licensed under the MIT License. |
| 3 | |
| 4 | using Microsoft.Teams.Bot.Apps.Schema; |
| 5 | using Microsoft.Teams.Bot.Core; |
| 6 | using Microsoft.Teams.Bot.Core.Schema; |
| 7 | |
| 8 | namespace Microsoft.Teams.Bot.Apps.Api; |
| 9 | |
| 10 | using CustomHeaders = Dictionary<string, string>; |
| 11 | |
| 12 | /// <summary> |
| 13 | /// Provides activity operations for sending, updating, and deleting activities in conversations. |
| 14 | /// </summary> |
| 15 | public class ActivitiesApi |
| 16 | { |
| 17 | private readonly ConversationClient _client; |
| 18 | |
| 19 | /// <summary> |
| 20 | /// Initializes a new instance of the <see cref="ActivitiesApi"/> class. |
| 21 | /// </summary> |
| 22 | /// <param name="conversationClient">The conversation client for activity operations.</param> |
| 23 | internal ActivitiesApi(ConversationClient conversationClient) |
| 24 | { |
| 25 | _client = conversationClient; |
| 26 | } |
| 27 | |
| 28 | // TODO: Resolve comment https://github.com/microsoft/teams.net/pull/334/changes#r2824918487 |
| 29 | |
| 30 | /// <summary> |
| 31 | /// Sends an activity to a conversation. |
| 32 | /// </summary> |
| 33 | /// <param name="activity">The activity to send. Must contain valid conversation and service URL information.</param> |
| 34 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 35 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 36 | /// <returns>A task that represents the asynchronous operation. The task result contains the response with the ID of the sent activity, or null if the response has no body.</returns> |
| 37 | public Task<SendActivityResponse?> SendAsync( |
| 38 | CoreActivity activity, |
| 39 | CustomHeaders? customHeaders = null, |
| 40 | CancellationToken cancellationToken = default) |
| 41 | => _client.SendActivityAsync(activity, customHeaders, cancellationToken); |
| 42 | |
| 43 | /// <summary> |
| 44 | /// Updates an existing activity in a conversation. |
| 45 | /// </summary> |
| 46 | /// <param name="conversationId">The ID of the conversation.</param> |
| 47 | /// <param name="activityId">The ID of the activity to update.</param> |
| 48 | /// <param name="activity">The updated activity data.</param> |
| 49 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 50 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 51 | /// <returns>A task that represents the asynchronous operation. The task result contains the response with the ID of the updated activity.</returns> |
| 52 | public Task<UpdateActivityResponse> UpdateAsync( |
| 53 | string conversationId, |
| 54 | string activityId, |
| 55 | CoreActivity activity, |
| 56 | CustomHeaders? customHeaders = null, |
| 57 | CancellationToken cancellationToken = default) |
| 58 | => _client.UpdateActivityAsync(conversationId, activityId, activity, customHeaders, cancellationToken); |
| 59 | |
| 60 | /// <summary> |
| 61 | /// Updates an existing targeted activity in a conversation. |
| 62 | /// </summary> |
| 63 | /// <param name="conversationId">The ID of the conversation.</param> |
| 64 | /// <param name="activityId">The ID of the activity to update.</param> |
| 65 | /// <param name="activity">The updated activity data.</param> |
| 66 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 67 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 68 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 69 | /// <returns>A task that represents the asynchronous operation. The task result contains the response with the ID of the updated activity.</returns> |
| 70 | public Task<UpdateActivityResponse> UpdateTargetedAsync( |
| 71 | string conversationId, |
| 72 | string activityId, |
| 73 | CoreActivity activity, |
| 74 | AgenticIdentity? agenticIdentity = null, |
| 75 | CustomHeaders? customHeaders = null, |
| 76 | CancellationToken cancellationToken = default) |
| 77 | => _client.UpdateTargetedActivityAsync(conversationId, activityId, activity, agenticIdentity, customHeaders, cancellationToken); |
| 78 | |
| 79 | /// <summary> |
| 80 | /// Deletes an existing targeted activity from a conversation. |
| 81 | /// </summary> |
| 82 | /// <param name="conversationId">The ID of the conversation.</param> |
| 83 | /// <param name="activityId">The ID of the activity to delete.</param> |
| 84 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 85 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 86 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 87 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 88 | /// <returns>A task that represents the asynchronous operation.</returns> |
| 89 | public Task DeleteTargetedAsync( |
| 90 | string conversationId, |
| 91 | string activityId, |
| 92 | Uri serviceUrl, |
| 93 | AgenticIdentity? agenticIdentity = null, |
| 94 | CustomHeaders? customHeaders = null, |
| 95 | CancellationToken cancellationToken = default) |
| 96 | => _client.DeleteTargetedActivityAsync(conversationId, activityId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 97 | |
| 98 | /// <summary> |
| 99 | /// Deletes an existing activity from a conversation. |
| 100 | /// </summary> |
| 101 | /// <param name="conversationId">The ID of the conversation.</param> |
| 102 | /// <param name="activityId">The ID of the activity to delete.</param> |
| 103 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 104 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 105 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 106 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 107 | /// <returns>A task that represents the asynchronous operation.</returns> |
| 108 | public Task DeleteAsync( |
| 109 | string conversationId, |
| 110 | string activityId, |
| 111 | Uri serviceUrl, |
| 112 | AgenticIdentity? agenticIdentity = null, |
| 113 | CustomHeaders? customHeaders = null, |
| 114 | CancellationToken cancellationToken = default) |
| 115 | => _client.DeleteActivityAsync(conversationId, activityId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 116 | |
| 117 | /// <summary> |
| 118 | /// Deletes an existing activity from a conversation using activity context. |
| 119 | /// </summary> |
| 120 | /// <param name="activity">The activity to delete. Must contain valid Id, Conversation.Id, and ServiceUrl.</param> |
| 121 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 122 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 123 | /// <returns>A task that represents the asynchronous operation.</returns> |
| 124 | public Task DeleteAsync( |
| 125 | CoreActivity activity, |
| 126 | CustomHeaders? customHeaders = null, |
| 127 | CancellationToken cancellationToken = default) |
| 128 | => _client.DeleteActivityAsync(activity, customHeaders, cancellationToken); |
| 129 | |
| 130 | /// <summary> |
| 131 | /// Uploads and sends historic activities to a conversation. |
| 132 | /// </summary> |
| 133 | /// <param name="conversationId">The ID of the conversation.</param> |
| 134 | /// <param name="transcript">The transcript containing the historic activities.</param> |
| 135 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 136 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 137 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 138 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 139 | /// <returns>A task that represents the asynchronous operation. The task result contains the response with a resource ID.</returns> |
| 140 | public Task<SendConversationHistoryResponse> SendHistoryAsync( |
| 141 | string conversationId, |
| 142 | Transcript transcript, |
| 143 | Uri serviceUrl, |
| 144 | AgenticIdentity? agenticIdentity = null, |
| 145 | CustomHeaders? customHeaders = null, |
| 146 | CancellationToken cancellationToken = default) |
| 147 | => _client.SendConversationHistoryAsync(conversationId, transcript, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 148 | |
| 149 | /// <summary> |
| 150 | /// Uploads and sends historic activities to a conversation using activity context. |
| 151 | /// </summary> |
| 152 | /// <param name="activity">The activity providing conversation context. Must contain valid Conversation.Id and ServiceUrl.</param> |
| 153 | /// <param name="transcript">The transcript containing the historic activities.</param> |
| 154 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 155 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 156 | /// <returns>A task that represents the asynchronous operation. The task result contains the response with a resource ID.</returns> |
| 157 | public Task<SendConversationHistoryResponse> SendHistoryAsync( |
| 158 | TeamsActivity activity, |
| 159 | Transcript transcript, |
| 160 | CustomHeaders? customHeaders = null, |
| 161 | CancellationToken cancellationToken = default) |
| 162 | { |
| 163 | ArgumentNullException.ThrowIfNull(activity); |
| 164 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 165 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Conversation.Id); |
| 166 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 167 | |
| 168 | return _client.SendConversationHistoryAsync( |
| 169 | activity.Conversation.Id, |
| 170 | transcript, |
| 171 | activity.ServiceUrl, |
| 172 | activity.From?.GetAgenticIdentity(), |
| 173 | customHeaders, |
| 174 | cancellationToken); |
| 175 | } |
| 176 | |
| 177 | /// <summary> |
| 178 | /// Gets the members of a specific activity. |
| 179 | /// </summary> |
| 180 | /// <param name="conversationId">The ID of the conversation.</param> |
| 181 | /// <param name="activityId">The ID of the activity.</param> |
| 182 | /// <param name="serviceUrl">The service URL for the conversation.</param> |
| 183 | /// <param name="agenticIdentity">Optional agentic identity for authentication.</param> |
| 184 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 185 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 186 | /// <returns>A task that represents the asynchronous operation. The task result contains a list of conversation members.</returns> |
| 187 | public Task<IList<ConversationAccount>> GetMembersAsync( |
| 188 | string conversationId, |
| 189 | string activityId, |
| 190 | Uri serviceUrl, |
| 191 | AgenticIdentity? agenticIdentity = null, |
| 192 | CustomHeaders? customHeaders = null, |
| 193 | CancellationToken cancellationToken = default) |
| 194 | => _client.GetActivityMembersAsync(conversationId, activityId, serviceUrl, agenticIdentity, customHeaders, cancellationToken); |
| 195 | |
| 196 | /// <summary> |
| 197 | /// Gets the members of a specific activity using activity context. |
| 198 | /// </summary> |
| 199 | /// <param name="activity">The activity to get members for. Must contain valid Id, Conversation.Id, and ServiceUrl.</param> |
| 200 | /// <param name="customHeaders">Optional custom headers to include in the request.</param> |
| 201 | /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param> |
| 202 | /// <returns>A task that represents the asynchronous operation. The task result contains a list of members for the activity.</returns> |
| 203 | public Task<IList<ConversationAccount>> GetMembersAsync( |
| 204 | TeamsActivity activity, |
| 205 | CustomHeaders? customHeaders = null, |
| 206 | CancellationToken cancellationToken = default) |
| 207 | { |
| 208 | ArgumentNullException.ThrowIfNull(activity); |
| 209 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Id); |
| 210 | ArgumentNullException.ThrowIfNull(activity.Conversation); |
| 211 | ArgumentException.ThrowIfNullOrWhiteSpace(activity.Conversation.Id); |
| 212 | ArgumentNullException.ThrowIfNull(activity.ServiceUrl); |
| 213 | |
| 214 | return _client.GetActivityMembersAsync( |
| 215 | activity.Conversation.Id, |
| 216 | activity.Id, |
| 217 | activity.ServiceUrl, |
| 218 | activity.From?.GetAgenticIdentity(), |
| 219 | customHeaders, |
| 220 | cancellationToken); |
| 221 | } |
| 222 | } |
| 223 | |