Interface IChannelApiHandler

Namespace

Microsoft.Agents.Builder

Assembly

Microsoft.Agents.Builder.dll

Handles requests received via the ChannelAPI endpoints exposed by a ChannelApi Controller.

public interface IChannelApiHandler

Remarks

These endpoints are defined by Azure Bot Service. The client for this API is in RestConnectorClient. This is primarily used for communicating with Azure Bot Service, Teams, and Agent-to-Agent.

Methods

OnCreateConversationAsync(ClaimsIdentity, ConversationParameters, CancellationToken)

CreateConversation() API.

Task<ConversationResourceResponse> OnCreateConversationAsync(ClaimsIdentity claimsIdentity, ConversationParameters parameters, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

parameters ConversationParameters

Parameters to create the conversation from.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ConversationResourceResponse>

task for a conversation resource response.

Remarks

POST to this method with a

• Agent being the Agent creating the conversation
• IsGroup set to true if this is not a direct message (default is false)
• Array containing the members to include in the conversation

The return value is a ResourceResponse which contains a conversation ID which is suitable for use in the message payload and REST API URIs.

Most channels only support the semantics of Agents initiating a direct message conversation. An example of how to do that would be:

var resource = await connector.conversations.CreateConversation(new ConversationParameters(){ Agent = "agent", members = new ChannelAccount[] { new ChannelAccount("user1") } ); await connect.Conversations.OnSendToConversationAsync(resource.Id, new Activity() ... ) ;

end.

OnDeleteActivityAsync(ClaimsIdentity, string, string, CancellationToken)

OnDeleteActivityAsync() API.

Task OnDeleteActivityAsync(ClaimsIdentity claimsIdentity, string conversationId, string activityId, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

activityId string

activityId to delete.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

Remarks

Some channels allow you to delete an existing activity, and if successful this method will remove the specified activity.

OnDeleteConversationMemberAsync(ClaimsIdentity, string, string, CancellationToken)

DeleteConversationMember() API.

Task OnDeleteConversationMemberAsync(ClaimsIdentity claimsIdentity, string conversationId, string memberId, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

memberId string

ID of the member to delete from this conversation.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

task.

Remarks

This REST API takes a ConversationId and a memberId (of type string) and removes that member from the conversation. If that member was the last member of the conversation, the conversation will also be deleted.

OnGetActivityMembersAsync(ClaimsIdentity, string, string, CancellationToken)

OnGetActivityMembersAsync() API.

Task<IList<ChannelAccount>> OnGetActivityMembersAsync(ClaimsIdentity claimsIdentity, string conversationId, string activityId, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

activityId string

Activity ID.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IList<ChannelAccount>>

task with result.

Remarks

This REST API takes a ConversationId and a ActivityId, returning an array of ChannelAccount objects representing the members of the particular activity in the conversation.

OnGetConversationMemberAsync(ClaimsIdentity, string, string, CancellationToken)

GetConversationMember() API.

Task<ChannelAccount> OnGetConversationMemberAsync(ClaimsIdentity claimsIdentity, string userId, string conversationId, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

userId string

User ID.

conversationId string

Conversation ID.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ChannelAccount>

task for a response.

Remarks

This REST API takes a ConversationId and UserId and returns the ChannelAccount objects representing the member of the conversation.

OnGetConversationMembersAsync(ClaimsIdentity, string, CancellationToken)

GetConversationMembers() API.

Task<IList<ChannelAccount>> OnGetConversationMembersAsync(ClaimsIdentity claimsIdentity, string conversationId, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IList<ChannelAccount>>

task for a response.

Remarks

This REST API takes a ConversationId and returns an array of ChannelAccount objects representing the members of the conversation.

OnGetConversationPagedMembersAsync(ClaimsIdentity, string, int?, string, CancellationToken)

GetConversationPagedMembers() API.

Task<PagedMembersResult> OnGetConversationPagedMembersAsync(ClaimsIdentity claimsIdentity, string conversationId, int? pageSize = null, string continuationToken = null, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

pageSize int?

Suggested page size.

continuationToken string

Continuation Token.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<PagedMembersResult>

task for a response.

Remarks

This REST API takes a ConversationId. Optionally a pageSize and/or continuationToken can be provided. It returns a PagedMembersResult, which contains an array of ChannelAccounts representing the members of the conversation and a continuation token that can be used to get more values.

One page of ChannelAccounts records are returned with each call. The number of records in a page may vary between channels and calls. The pageSize parameter can be used as a suggestion. If there are no additional results the response will not contain a continuation token. If there are no members in the conversation the Members will be empty or not present in the response.

A response to a request that has a continuation token from a prior request may rarely return members from a previous request.

OnGetConversationsAsync(ClaimsIdentity, string, string, CancellationToken)

OnGetConversationsAsync() API.

Task<ConversationsResult> OnGetConversationsAsync(ClaimsIdentity claimsIdentity, string conversationId, string continuationToken = null, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

conversationId.

continuationToken string

skip or continuation token.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ConversationsResult>

task for ConversationsResult.

Remarks

GET from this method with a skip token

The return value is a ConversationsResult, which contains an array of ConversationMembers and a skip token. If the skip token is not empty, then there are further values to be returned. Call this method again with the returned token to get more values.

Each ConversationMembers object contains the ID of the conversation and an array of ChannelAccounts that describe the members of the conversation.

OnReplyToActivityAsync(ClaimsIdentity, string, string, IActivity, CancellationToken)

OnReplyToActivityAsync() API.

Task<ResourceResponse> OnReplyToActivityAsync(ClaimsIdentity claimsIdentity, string conversationId, string activityId, IActivity activity, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

activityId string

activityId the reply is to (OPTIONAL).

activity IActivity

Activity to send.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ResourceResponse>

task for a resource response.

Remarks

This is slightly different from SendToConversation().

• SendToConversation(conversationId) - will append the activity to the end of the conversation according to the timestamp or semantics of the channel.
• ReplyToActivity(conversationId,ActivityId) - adds the activity as a reply to another activity, if the channel supports it. If the channel does not support nested replies, ReplyToActivity falls back to SendToConversation.

Use ReplyToActivity when replying to a specific activity in the conversation.

OnSendConversationHistoryAsync(ClaimsIdentity, string, Transcript, CancellationToken)

SendConversationHistory() API.

Task<ResourceResponse> OnSendConversationHistoryAsync(ClaimsIdentity claimsIdentity, string conversationId, Transcript transcript, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

transcript Transcript

Transcript of activities.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ResourceResponse>

task for a resource response.

Remarks

Sender must ensure that the historic activities have unique ids and appropriate timestamps. The ids are used by the client to deal with duplicate activities and the timestamps are used by the client to render the activities in the right order.

OnSendToConversationAsync(ClaimsIdentity, string, IActivity, CancellationToken)

SendToConversation() API.

Task<ResourceResponse> OnSendToConversationAsync(ClaimsIdentity claimsIdentity, string conversationId, IActivity activity, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

conversationId.

activity IActivity

Activity to send.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ResourceResponse>

task for a resource response.

Remarks

This method allows you to send an activity to the end of a conversation.

This is slightly different from ReplyToActivity().

• SendToConversation(conversationId) - will append the activity to the end of the conversation according to the timestamp or semantics of the channel.
• ReplyToActivity(conversationId,ActivityId) - adds the activity as a reply to another activity, if the channel supports it. If the channel does not support nested replies, ReplyToActivity falls back to SendToConversation.

Use ReplyToActivity when replying to a specific activity in the conversation.

OnUpdateActivityAsync(ClaimsIdentity, string, string, IActivity, CancellationToken)

OnUpdateActivityAsync() API.

Task<ResourceResponse> OnUpdateActivityAsync(ClaimsIdentity claimsIdentity, string conversationId, string activityId, IActivity activity, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

activityId string

activityId to update.

activity IActivity

replacement Activity.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ResourceResponse>

task for a resource response.

Remarks

Some channels allow you to edit an existing activity to reflect the new state of a Agent conversation.

For example, you can remove buttons after someone has clicked "Approve" button.

OnUploadAttachmentAsync(ClaimsIdentity, string, AttachmentData, CancellationToken)

UploadAttachment() API.

Task<ResourceResponse> OnUploadAttachmentAsync(ClaimsIdentity claimsIdentity, string conversationId, AttachmentData attachmentUpload, CancellationToken cancellationToken = default)

Parameters

claimsIdentity ClaimsIdentity

claimsIdentity for the Agent, should have AudienceClaim, AppIdClaim and ServiceUrlClaim.

conversationId string

Conversation ID.

attachmentUpload AttachmentData

Attachment data.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<ResourceResponse>

task with result.

Remarks

The response is a ResourceResponse which contains an AttachmentId which is suitable for using with the attachments API.