Documentation - v1.2.0-alpha.3
    Preparing search index...

    Interface TurnContext

    Represents the context for a single turn in a conversation between a user and an agent.

    TurnContext is a central concept in the Agents framework - it contains:

    • The incoming activity that started the turn
    • Access to the adapter that can be used to send responses
    • A state collection for storing information during the turn
    • Methods for sending, updating, and deleting activities
    • Middleware hooks for intercepting activity operations

    The TurnContext object is created by the adapter when an activity is received and is passed to the agent's logic to process the turn. It maintains information about the conversation and provides methods to send responses.

    This class follows the builder pattern for registering middleware handlers.

    interface TurnContext {
        bufferedReplyActivities: Activity[];
        get activity(): Activity;
        get adapter(): BaseAdapter;
        get identity(): JwtPayload;
        get locale(): string;
        set locale(value: string): void;
        get responded(): boolean;
        set responded(value: boolean): void;
        get streamingResponse(): StreamingResponse;
        get turnState(): TurnContextStateCollection;
        copyTo(context: TurnContext): void;
        deleteActivity(
            idOrReference: string | ConversationReference,
        ): Promise<void>;
        getAttachment(
            attachmentId: string,
            viewId: string,
        ): Promise<ReadableStream>;
        getAttachmentInfo(attachmentId: string): Promise<AttachmentInfo>;
        onDeleteActivity(handler: DeleteActivityHandler): this;
        onSendActivities(handler: SendActivitiesHandler): this;
        onUpdateActivity(handler: UpdateActivityHandler): this;
        sendActivities(activities: Activity[]): Promise<ResourceResponse[]>;
        sendActivity(
            activityOrText: string | Activity,
            speak?: string,
            inputHint?: string,
        ): Promise<ResourceResponse>;
        sendTraceActivity(
            name: string,
            value?: any,
            valueType?: string,
            label?: string,
        ): Promise<ResourceResponse>;
        updateActivity(activity: Activity): Promise<void>;
        uploadAttachment(
            conversationId: string,
            attachmentData: AttachmentData,
        ): Promise<ResourceResponse>;
    }
    Index

    Properties

    bufferedReplyActivities

    Accessors

    activity adapter identity locale responded streamingResponse turnState

    Methods

    copyTo deleteActivity getAttachment getAttachmentInfo onDeleteActivity onSendActivities onUpdateActivity sendActivities sendActivity sendTraceActivity updateActivity uploadAttachment

    Properties

    bufferedReplyActivities: Activity[]

    A list of reply activities that are buffered until the end of the turn.

    This is primarily used with the 'expectReplies' delivery mode where all activities during a turn are collected and returned as a single response.

    Accessors

    • get activity(): Activity

      Gets the incoming activity that started this turn.

      Returns Activity

      This is the activity that was received from the user or channel and triggered the creation of this context.

    • get adapter(): BaseAdapter

      Gets the adapter that created this context.

      Returns BaseAdapter

      The adapter is responsible for sending and receiving activities to and from the user's channel.

    • get identity(): JwtPayload

      Returns JwtPayload

    • get locale(): string

      Gets or sets the locale for the turn.

      Returns string

      The locale affects language-dependent operations like formatting dates or numbers.

    • set locale(value: string): void

      Parameters

      • value: string

      Returns void

    • get responded(): boolean

      Gets or sets whether the turn has sent a response to the user.

      Returns boolean

      This is used to track whether the agent has responded to the user's activity. Once set to true, it cannot be set back to false.

    • set responded(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get streamingResponse(): StreamingResponse

      Returns StreamingResponse

    • get turnState(): TurnContextStateCollection

      Gets the turn state collection for storing data during the turn.

      Returns TurnContextStateCollection

      The turn state collection provides a dictionary-like interface for storing arbitrary data that needs to be accessible during the processing of the current turn.

    Methods

    • Protected

      Copies the properties of this TurnContext to another TurnContext.

      Used internally when cloning contexts.

      Parameters

      Returns void

    • Deletes an activity from the conversation.

      Parameters

      • idOrReference: string | ConversationReference

        The ID of the activity to delete or a conversation reference

      Returns Promise<void>

      A promise that resolves when the activity has been deleted

    • Parameters

      • attachmentId: string

        The ID of the attachment

      • viewId: string

        The view to get

      Returns Promise<ReadableStream>

      A promise that resolves to a readable stream of the attachment content

      This function will not be supported in future versions. Use TurnContext.turnState.get(CloudAdapter.ConnectorClientKey). Gets the content of an attachment.

    • Parameters

      • attachmentId: string

        The ID of the attachment

      Returns Promise<AttachmentInfo>

      A promise that resolves to the attachment information

      This function will not be supported in future versions. Use TurnContext.turnState.get(CloudAdapter.ConnectorClientKey). Gets information about an attachment.

    • Registers a handler for intercepting activity deletions.

      Parameters

      • handler: DeleteActivityHandler

        The handler to register

      Returns this

      The current TurnContext instance for chaining

    • Registers a handler for intercepting and processing activities being sent.

      Parameters

      • handler: SendActivitiesHandler

        The handler to register

      Returns this

      The current TurnContext instance for chaining

      This method follows a middleware pattern, allowing multiple handlers to be chained together. Handlers can modify activities or inject new ones.

    • Registers a handler for intercepting activity updates.

      Parameters

      • handler: UpdateActivityHandler

        The handler to register

      Returns this

      The current TurnContext instance for chaining

    • Sends multiple activities to the sender of the incoming activity.

      Parameters

      • activities: Activity[]

        The array of activities to send

      Returns Promise<ResourceResponse[]>

      A promise that resolves to an array of resource responses

      This method applies conversation references to each activity and emits them through the middleware chain before sending them to the adapter.

    • Sends an activity to the sender of the incoming activity.

      Parameters

      • activityOrText: string | Activity

        The activity to send or a string for a simple message

      • Optionalspeak: string

        Optional text to be spoken by the agent

      • OptionalinputHint: string

        Optional input hint to indicate if the agent is expecting input

      Returns Promise<ResourceResponse>

      A promise that resolves to the resource response or undefined

      This is the primary method used to respond to the user. It automatically addresses the response to the correct conversation and recipient using information from the incoming activity.

    • Sends a trace activity for debugging purposes.

      Parameters

      • name: string

        The name/category of the trace

      • Optionalvalue: any

        The value/data to include in the trace

      • OptionalvalueType: string

        Optional type name for the value

      • Optionallabel: string

        Optional descriptive label for the trace

      Returns Promise<ResourceResponse>

      A promise that resolves to the resource response or undefined

      Trace activities are typically used for debugging and are only visible in channels that support them, like the Bot Framework Emulator.

    • Updates an existing activity in the conversation.

      Parameters

      • activity: Activity

        The activity to update with its ID specified

      Returns Promise<void>

      A promise that resolves when the activity has been updated

      This can be used to edit previously sent activities, for example to update the content of an adaptive card or change a message.

    • Parameters

      • conversationId: string

        The ID of the conversation

      • attachmentData: AttachmentData

        The attachment data to upload

      Returns Promise<ResourceResponse>

      A promise that resolves to the resource response

      This function will not be supported in future versions. Use TurnContext.turnState.get(CloudAdapter.ConnectorClientKey). Uploads an attachment to the conversation.

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods