botbuilder-core/lib/botAdapter.d.ts

Core components for Microsoft Bot Builder. Components in this library can run either in a browser or on the server.

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { ClaimsIdentity } from 'botframework-connector';
import { Activity, ConversationParameters, ConversationReference, ResourceResponse } from 'botframework-schema';
import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet';
import { TurnContext } from './turnContext';
/**
 * Defines the core behavior of a bot adapter that can connect a bot to a service endpoint.
 *
 * @remarks
 * The bot adapter encapsulates authentication processes and sends activities to and receives
 * activities from the Bot Connector Service. When your bot receives an activity, the adapter
 * creates a turn context object, passes it to your bot application logic, and sends responses
 * back to the user's channel.
 *
 * The adapter processes and directs incoming activities in through the bot middleware pipeline to
 * your bot logic and then back out again. As each activity flows in and out of the bot, each
 * piece of middleware can inspect or act upon the activity, both before and after the bot logic runs.
 * Use the [use](xref:botbuilder-core.BotAdapter.use) method to add [Middleware](xref:botbuilder-core.Middleware)
 * objects to your adapter's middleware collection.
 *
 * For more information, see the articles on
 * [How bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics) and
 * [Middleware](https://docs.microsoft.com/azure/bot-service/bot-builder-concept-middleware).
 */
export declare abstract class BotAdapter {
    protected middleware: MiddlewareSet;
    private turnError;
    readonly BotIdentityKey: symbol;
    readonly ConnectorClientKey: symbol;
    readonly OAuthScopeKey: symbol;
    /**
     * Asynchronously sends a set of outgoing activities to a channel server.
     *
     * This method supports the framework and is not intended to be called directly for your code.
     * Use the turn context's [sendActivity](xref:botbuilder-core.TurnContext.sendActivity) or
     * [sendActivities](xref:botbuilder-core.TurnContext.sendActivities) method from your bot code.
     *
     * @param context The context object for the turn.
     * @param activities The activities to send.
     * @returns An array of [ResourceResponse](xref:)
     * @remarks
     * The activities will be sent one after another in the order in which they're received. A
     * response object will be returned for each sent activity. For `message` activities this will
     * contain the ID of the delivered message.
     */
    abstract sendActivities(context: TurnContext, activities: Partial<Activity>[]): Promise<ResourceResponse[]>;
    /**
     * Asynchronously replaces a previous activity with an updated version.
     *
     * This interface supports the framework and is not intended to be called directly for your code.
     * Use [TurnContext.updateActivity](xref:botbuilder-core.TurnContext.updateActivity) to update
     * an activity from your bot code.
     *
     * @param context The context object for the turn.
     * @param activity The updated version of the activity to replace.
     * @remarks
     * Not all channels support this operation. For channels that don't, this call may throw an exception.
     */
    abstract updateActivity(context: TurnContext, activity: Partial<Activity>): Promise<ResourceResponse | void>;
    /**
     * Asynchronously deletes an existing activity.
     *
     * This interface supports the framework and is not intended to be called directly for your code.
     * Use [TurnContext.deleteActivity](xref:botbuilder-core.TurnContext.deleteActivity) to delete
     * an activity from your bot code.
     *
     * @param context The context object for the turn.
     * @param reference Conversation reference information for the activity to delete.
     * @remarks
     * Not all channels support this operation. For channels that don't, this call may throw an exception.
     */
    abstract deleteActivity(context: TurnContext, reference: Partial<ConversationReference>): Promise<void>;
    /**
     * Asynchronously resumes a conversation with a user, possibly after some time has gone by.
     *
     * @param reference A reference to the conversation to continue.
     * @param logic The asynchronous method to call after the adapter middleware runs.
     * @remarks
     * This is often referred to as a _proactive notification_, the bot can proactively
     * send a message to a conversation or user without waiting for an incoming message.
     * For example, a bot can use this method to send notifications or coupons to a user.
     */
    abstract continueConversation(reference: Partial<ConversationReference>, logic: (revocableContext: TurnContext) => Promise<void>): Promise<void>;
    /**
     * Asynchronously resumes a conversation with a user, possibly after some time has gone by.
     *
     * @param botAppId The application ID of the bot. This parameter is ignored in single tenant the Adapters (Console,Test, etc) but is critical to the BotFrameworkAdapter which is multi-tenant aware.
     * @param reference A partial [ConversationReference](xref:botframework-schema.ConversationReference) to the conversation to continue.
     * @param logic The asynchronous method to call after the adapter middleware runs.
     * @returns a promise representing the async operation
     */
    continueConversationAsync(botAppId: string, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
    /**
     * Asynchronously resumes a conversation with a user, possibly after some time has gone by.
     *
     * @param claimsIdentity A [ClaimsIdentity](xref:botframework-connector) for the conversation.
     * @param reference A partial [ConversationReference](xref:botframework-schema.ConversationReference) to the conversation to continue.
     * @param logic The asynchronous method to call after the adapter middleware runs.
     * @returns a promise representing the async operation
     */
    continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>;
    /**
     * Asynchronously resumes a conversation with a user, possibly after some time has gone by.
     *
     * @param claimsIdentity A [ClaimsIdentity](xref:botframework-connector) for the conversation.
     * @param reference A partial [ConversationReference](xref:botframework-schema.ConversationReference) to the conversation to continue.
     * @param audience A value signifying the recipient of the proactive message.</param>
     * @param logic The asynchronous method to call after the adapter middleware runs.
     * @returns a promise representing the async operation
     */
    continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, audience: string, logic: (context: TurnContext) => Promise<void>): Promise<void>;
    /**
     * Creates a conversation on the specified channel.
     *
     * @param _botAppId The application ID of the bot.
     * @param _channelId The ID for the channel.
     * @param _serviceUrl The ID for the channel.
     * @param _audience The audience for the connector.
     * <param name="conversationParameters">
     * @param _conversationParameters The conversation information to use to create the conversation
     * @param _logic The method to call for the resulting bot turn.
     * @returns A promise that represents the asynchronous operation
     * @remarks
     * To start a conversation, your bot must know its account information and the user's account information on that
     * channel.  Most _channels only support initiating a direct message (non-group) conversation.
     *
     * The adapter attempts to create a new conversation on the channel, and then sends a `conversationUpdate` activity
     * through its middleware pipeline to the logic method.
     *
     * If the conversation is established with the specified users, the ID of the activity's converstion will contain
     * the ID of the new conversation.
     */
    createConversationAsync(_botAppId: string, _channelId: string, _serviceUrl: string, _audience: string, _conversationParameters: ConversationParameters, _logic: (context: TurnContext) => Promise<void>): Promise<void>;
    /**
     * Gets or sets an error handler that can catch exceptions in the middleware or application.
     *
     * @remarks
     * The error handler is called with these parameters:
     *
     * | Name | Type | Description |
     * | :--- | :--- | :--- |
     * | `context` | [TurnContext](xref:botbuilder-core.TurnContext) | The context object for the turn. |
     * | `error` | `Error` | The Node.js error thrown. |
     * @returns {Promise<void>} A promise representing the async operation.
     */
    get onTurnError(): (context: TurnContext, error: Error) => Promise<void>;
    /**
     * Sets an error handler that can catch exceptions in the middleware or application.
     *
     * @remarks
     * The error handler is called with these parameters:
     *
     * | Name | Type | Description |
     * | :--- | :--- | :--- |
     * | `context` | [TurnContext](xref:botbuilder-core.TurnContext) | The context object for the turn. |
     * | `error` | `Error` | The Node.js error thrown. |
     */
    set onTurnError(value: (context: TurnContext, error: Error) => Promise<void>);
    /**
     * Adds middleware to the adapter's pipeline.
     *
     * @param {...any} middlewares The middleware or middleware handlers to add.
     * @returns The updated adapter object.
     * @remarks Middleware is added to the adapter at initialization time.
     * Each turn, the adapter calls its middleware in the order in which you added it.
     */
    use(...middlewares: (MiddlewareHandler | Middleware)[]): this;
    /**
     * Starts activity processing for the current bot turn.
     *
     * @param context The context object for the turn.
     * @param next A callback method to run at the end of the pipeline.
     * @returns A promise that resolves when the middleware chain is finished
     * @remarks
     * The adapter creates a revokable proxy for the turn context and then calls its middleware in
     * the order in which you added it. If the middleware chain completes without short circuiting,
     * the adapter calls the callback method. If any middleware short circuits, the adapter does not
     * call any of the subsequent middleware or the callback method, and the pipeline short circuits.
     *
     * The adapter calls middleware with a `next` parameter, which represents the next step in the
     * pipeline. Middleware should call the `next` method to continue processing without short circuiting.
     *
     * When the turn is initiated by a user activity (reactive messaging), the callback method will
     * be a reference to the bot's turn handler. When the turn is initiated by a call to
     * [continueConversation](xref:botbuilder-core.BotAdapter.continueConversation) (proactive messaging),
     * the callback method is the callback method that was provided in the call.
     */
    protected runMiddleware(context: TurnContext, next: (revocableContext: TurnContext) => Promise<void>): Promise<void>;
}
//# sourceMappingURL=botAdapter.d.ts.map