TurnContext class

Creates an new instance of the TurnContext class.

new TurnContext(adapterOrContext: BotAdapter, request: Partial<Activity>)

Parameters

Creates an new instance of the TurnContext class.

new TurnContext(adapterOrContext: TurnContext)

Parameters

Gets the activity associated with this turn.

Activity activity

Property Value

The activity associated with this turn.

Remarks

This example shows how to get the users trimmed utterance from the activity:

const utterance = (context.activity.text || '').trim();

Gets the bot adapter that created this context object.

BotAdapter adapter

Property Value

The bot adapter that created this context object.

List of activities to send when context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Property Value

Gets the locale stored in the turnState. Sets the locale stored in the turnState.

string | undefined locale

Property Value

The locale stored in the turnState.

Indicates whether the bot has replied to the user this turn. Sets the response flag on the current turn context.

boolean responded

Property Value

True if at least one response was sent for the current turn; otherwise, false.

Remarks

true if at least one response was sent for the current turn; otherwise, false. Use this to determine if your bot needs to run fallback logic after other normal processing.

Trace activities do not set this flag.

for example:

await routeActivity(context);
if (!context.responded) {
   await context.sendActivity(`I'm sorry. I didn't understand.`);
}

Gets the services registered on this context object.

TurnContextStateCollection turnState

Property Value

The services registered on this context object.

Remarks

Middleware, other components, and services will typically use this to cache information that could be asked for by a bot multiple times during a turn. You can use this cache to pass information between components of your bot.

For example:

const cartKey = Symbol();
const cart = await loadUsersShoppingCart(context);
context.turnState.set(cartKey, cart);

Updates an activity with the delivery information from an existing conversation reference.

static function applyConversationReference(activity: Partial<Activity>, reference: Partial<ConversationReference>, isIncoming?: boolean): Partial<Activity>

Parameters

Returns

This activity, updated with the delivery information.

Remarks

Call the getConversationReference method on an incoming activity to get a conversation reference that you can then use to update an outgoing activity with the correct delivery information.

Asynchronously deletes a previously sent activity.

function deleteActivity(idOrReference: string | Partial<ConversationReference>): Promise<void>

Parameters

Returns

A promise representing the async operation.

Remarks

If an ID is specified, the conversation reference for the current request is used to get the rest of the information needed.

For example:

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const savedId = await approveExpenseReport(matched[1]);
   await context.deleteActivity(savedId);
}

See also

• sendActivity
• updateActivity
• getReplyConversationReference

Copies conversation reference information from an activity.

static function getConversationReference(activity: Partial<Activity>): Partial<ConversationReference>

Parameters

Returns

A conversation reference for the conversation that contains this activity.

Remarks

You can save the conversation reference as a JSON object and use it later to proactively message the user.

For example:

const reference = TurnContext.getConversationReference(context.request);

See also

• BotAdapter.continueConversation

Gets all at-mention entities included in an activity.

static function getMentions(activity: Partial<Activity>): Mention[]

Parameters

Returns

All the at-mention entities included in an activity.

Remarks

The activity's entities property contains a flat list of metadata objects pertaining to this activity and can contain mention entities. This method returns all such entities for a given activity.

For example:

const mentions = TurnContext.getMentions(turnContext.request);

Copies conversation reference information from a resource response for a sent activity.

static function getReplyConversationReference(activity: Partial<Activity>, reply: ResourceResponse): Partial<ConversationReference>

Parameters

Returns

A ConversationReference that can be stored and used later to delete or update the activity.

Remarks

You can save the conversation reference as a JSON object and use it later to update or delete the message.

For example:

var reply = await context.sendActivity('Hi');
var reference = TurnContext.getReplyConversationReference(context.activity, reply);

See also

• deleteActivity
• updateActivity

Adds a response handler for delete activity operations.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parameters

Returns

The updated context object.

Remarks

This method returns a reference to the turn context object.

When the deleteActivity method is called, the registered handlers are called in the order in which they were added to the context object before the activity is deleted.

This example shows how to listen for and log activity deletions.

context.onDeleteActivity(async (ctx, reference, next) => {
   // Delete activity
   await next();

   // Log delete
   logDelete(activity);
});

Adds a response handler for send activity operations.

function onSendActivities(handler: SendActivitiesHandler): this

Parameters

Returns

The updated context object.

Remarks

This method returns a reference to the turn context object.

When the sendActivity or sendActivities method is called, the registered handlers are called in the order in which they were added to the context object before the activities are sent.

This example shows how to listen for and log outgoing message activities.

context.onSendActivities(async (ctx, activities, next) => {
   // Log activities before sending them.
   activities.filter(a => a.type === 'message').forEach(a => logSend(a));

   // Allow the send process to continue.
   next();
});

Adds a response handler for update activity operations.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parameters

Returns

The updated context object.

Remarks

This method returns a reference to the turn context object.

When the updateActivity method is called, the registered handlers are called in the order in which they were added to the context object before the activity is updated.

This example shows how to listen for and log activity updates.

context.onUpdateActivity(async (ctx, activity, next) => {
   // Replace activity
   await next();

   // Log update
   logUpdate(activity);
});

Removes at mentions for a given ID from the text of an activity and returns the updated text. Use with caution; this function alters the activity's text property.

static function removeMentionText(activity: Partial<Activity>, id: string): string

Parameters

Returns

The updated activity's text.

Remarks

Some channels, for example Microsoft Teams, add at mentions to the text of a message activity.

Use this helper method to modify the activity's text property. It removes all at mentions for the given bot or user ID and then returns the updated property value.

For example, when you remove mentions of echoBot from an activity containing the text "@echoBot Hi Bot", the activity text is updated, and the method returns "Hi Bot".

The format of a mention entity is channel-dependent. However, the mention's text property should contain the exact text for the user as it appears in the activity text.

For example, whether the channel uses "username" or "@username", this string is in the activity's text, and this method will remove all occurrences of that string from the text.

For example:

const updatedText = TurnContext.removeMentionText(activity, activity.recipient.id);

See also

• removeRecipientMention

Removes at mentions for the activity's recipient from the text of an activity and returns the updated text. Use with caution; this function alters the activity's text property.

static function removeRecipientMention(activity: Partial<Activity>): string

Parameters

Returns

The updated activity's text.

Remarks

Some channels, for example Microsoft Teams, add at-mention details to the text of a message activity.

Use this helper method to modify the activity's text property. It removes all at mentions of the activity's recipient and then returns the updated property value.

For example:

const updatedText = TurnContext.removeRecipientMention(turnContext.request);

See also

• removeMentionText

Asynchronously sends a set of activities to the sender of the incoming activity.

function sendActivities(activities: Partial<Activity>[]): Promise<ResourceResponse[]>

Parameters

Returns

A promise with a ResourceResponse.

Remarks

If the activities are successfully sent, results in an array of ResourceResponse objects containing the IDs that the receiving channel assigned to the activities.

Before they are sent, the delivery information of each outbound activity is updated based on the delivery information of the inbound inbound activity.

For example:

await context.sendActivities([
   { type: 'typing' },
   { type: 'delay', value: 2000 },
   { type: 'message', text: 'Hello... How are you?' }
]);

See also

• sendActivity
• updateActivity
• deleteActivity

Asynchronously sends an activity to the sender of the incoming activity.

function sendActivity(activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined>

Parameters

Returns

A promise with a ResourceResponse.

Remarks

If the activity is successfully sent, results in a ResourceResponse object containing the ID that the receiving channel assigned to the activity.

See the channel's documentation for limits imposed upon the contents of the activityOrText parameter.

To control various characteristics of your bot's speech such as voice, rate, volume, pronunciation, and pitch, specify speak in Speech Synthesis Markup Language (SSML) format.

For example:

await context.sendActivity(`Hello World`);

See also

• sendActivities
• updateActivity
• deleteActivity

Asynchronously sends an activity to the sender of the incoming activity.

function sendTraceActivity(name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined>

Parameters

Returns

A promise with a ResourceResponse.

Remarks

Creates and sends a Trace activity. Trace activities are only sent when the channel is the emulator.

For example:

await context.sendTraceActivity(`The following exception was thrown ${msg}`);

See also

• sendActivities

Asynchronously updates a previously sent activity.

function updateActivity(activity: Partial<Activity>): Promise<ResourceResponse | void>

Parameters

Returns

A promise with a ResourceResponse.

Remarks

The id of the replacement activity indicates the activity in the conversation to replace.

For example:

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const update = await approveExpenseReport(matched[1]);
   await context.updateActivity(update);
}

See also

• sendActivity
• deleteActivity
• getReplyConversationReference