TurnContext Interface

Package:
com.microsoft.bot.builder
Maven Artifact:
com.microsoft.bot:bot-builder:4.14.3

public interface TurnContext

Provides context for a turn of a bot.

Context provides information needed to process an incoming activity. The context object is created by a BotAdapter and persists for the length of the turn.

Bot Middleware

Field Summary

Modifier and Type Field and Description
static final java.lang.String STATE_TURN_LOCALE

Method Summary

Modifier and Type Method and Description
abstract java.util.concurrent.CompletableFuture<java.lang.Void> deleteActivity(ConversationReference conversationReference)

Deletes an existing activity.
abstract java.util.concurrent.CompletableFuture<java.lang.Void> deleteActivity(String activityId)

Deletes an existing activity.
abstract Activity getActivity()

Gets the activity for this turn of the bot.
abstract BotAdapter getAdapter()

Gets the bot adapter that created this context object.
abstract java.lang.String getLocale()

Gets the locale on this context object.
abstract boolean getResponded()

Gets a value indicating whether at least one response was sent for the current turn.
abstract TurnContextStateCollection getTurnState()

Gets the collection of values cached with the context object for the lifetime of the turn.
abstract TurnContext onDeleteActivity(DeleteActivityHandler handler)

Adds a response handler for delete activity operations.
abstract TurnContext onSendActivities(SendActivitiesHandler handler)

Adds a response handler for send activity operations.
abstract TurnContext onUpdateActivity(UpdateActivityHandler handler)

Adds a response handler for update activity operations.
default java.util.concurrent.CompletableFuture<ResourceResponse[]> sendActivities(Activity[] activities)

Helper method to send an array of Activities.
abstract java.util.concurrent.CompletableFuture<ResourceResponse[]> sendActivities(List<Activity> activities)

Sends a list of activities to the sender of the incoming activity.
abstract java.util.concurrent.CompletableFuture<ResourceResponse> sendActivity(Activity activity)

Sends an activity to the sender of the incoming activity.
abstract java.util.concurrent.CompletableFuture<ResourceResponse> sendActivity(String textReplyToSend)

Sends a message activity to the sender of the incoming activity.
abstract java.util.concurrent.CompletableFuture<ResourceResponse> sendActivity(String textReplyToSend, String speak)

Sends a message activity to the sender of the incoming activity.
abstract java.util.concurrent.CompletableFuture<ResourceResponse> sendActivity(String textReplyToSend, String speak, InputHints inputHint)

Sends a message activity to the sender of the incoming activity.
default java.util.concurrent.CompletableFuture<java.lang.Void> sendActivityBlind(Activity activity)

Sends an Activity to the sender of the incoming Activity without returning a ResourceResponse.
abstract void setLocale(String withLocale)

Set the locale on this context object.
static java.util.concurrent.CompletableFuture<ResourceResponse> traceActivity(TurnContext turnContext, String name)
static java.util.concurrent.CompletableFuture<ResourceResponse> traceActivity(TurnContext turnContext, String name, Object value, String valueType, String label)

Sends a trace activity to the BotAdapter for logging purposes.
abstract java.util.concurrent.CompletableFuture<ResourceResponse> updateActivity(Activity withActivity)

Replaces an existing activity.

Field Details

STATE_TURN_LOCALE

public static final String STATE_TURN_LOCALE

Method Details

deleteActivity

public abstract CompletableFuture deleteActivity(ConversationReference conversationReference)

Deletes an existing activity.

Parameters:

conversationReference - The conversation containing the activity to delete.

Returns:

A task that represents the work queued to execute. The conversation reference's ConversationReference#getActivityId indicates the activity in the conversation to delete.

deleteActivity

public abstract CompletableFuture deleteActivity(String activityId)

Deletes an existing activity.

Parameters:

activityId - The ID of the activity to delete.

Returns:

A task that represents the work queued to execute.

getActivity

public abstract Activity getActivity()

Gets the activity for this turn of the bot.

Returns:

The activity for this turn of the bot.

getAdapter

public abstract BotAdapter getAdapter()

Gets the bot adapter that created this context object.

Returns:

The bot adapter that created this context object.

getLocale

public abstract String getLocale()

Gets the locale on this context object.

Returns:

The string of locale on this context object.

getResponded

public abstract boolean getResponded()

Gets a value indicating whether at least one response was sent for the current turn.

Returns:

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

getTurnState

public abstract TurnContextStateCollection getTurnState()

Gets the collection of values cached with the context object for the lifetime of the turn.

Returns:

The collection of services registered on this context object.

onDeleteActivity

public abstract TurnContext onDeleteActivity(DeleteActivityHandler handler)

Adds a response handler for delete activity operations.

When the context's deleteActivity(String activityId) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

Parameters:

handler - The handler to add to the context object.

Returns:

The updated context object.

onSendActivities

public abstract TurnContext onSendActivities(SendActivitiesHandler handler)

Adds a response handler for send activity operations.

When the context's sendActivity(Activity activity) or sendActivities(List<Activity> activities) methods are called, the adapter calls the registered handlers in the order in which they were added to the context object.

Parameters:

handler - The handler to add to the context object.

Returns:

The updated context object.

onUpdateActivity

public abstract TurnContext onUpdateActivity(UpdateActivityHandler handler)

Adds a response handler for update activity operations.

When the context's updateActivity(Activity withActivity) is called, the adapter calls the registered handlers in the order in which they were added to the context object.

Parameters:

handler - The handler to add to the context object.

Returns:

The updated context object.

sendActivities

public default CompletableFuture sendActivities(Activity[] activities)

Helper method to send an array of Activities. This calls sendActivities(List<Activity> activities).

Parameters:

activities - The array of activities.

Returns:

A task that represents the work queued to execute.

sendActivities

public abstract CompletableFuture sendActivities(List activities)

Sends a list of activities to the sender of the incoming activity.

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

Parameters:

activities - The activities to send.

Returns:

A task that represents the work queued to execute.

sendActivity

public abstract CompletableFuture sendActivity(Activity activity)

Sends an activity to the sender of the incoming activity.

Parameters:

activity - The activity to send.

Returns:

A task that represents the work queued to execute. If the activity is successfully sent, the task result contains a ResourceResponse object containing the ID that the receiving channel assigned to the activity.

sendActivity

public abstract CompletableFuture sendActivity(String textReplyToSend)

Sends a message activity to the sender of the incoming activity.

If the activity is successfully sent, the task result contains 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 textReplyToSend.

Parameters:

textReplyToSend - The text of the message to send.

Returns:

A task that represents the work queued to execute.

sendActivity

public abstract CompletableFuture sendActivity(String textReplyToSend, String speak)

Sends a message activity to the sender of the incoming activity.

If the activity is successfully sent, the task result contains 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 textReplyToSend.

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.

Parameters:

textReplyToSend - The text of the message to send.
speak - Optional, text to be spoken by your bot on a speech-enabled channel.

Returns:

A task that represents the work queued to execute.

sendActivity

public abstract CompletableFuture sendActivity(String textReplyToSend, String speak, InputHints inputHint)

Sends a message activity to the sender of the incoming activity.

If the activity is successfully sent, the task result contains 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 textReplyToSend.

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.

Parameters:

textReplyToSend - The text of the message to send.
speak - Optional, text to be spoken by your bot on a speech-enabled channel.
inputHint - Optional, indicates whether your bot is accepting, expecting, or ignoring user input after the message is delivered to the client. One of: "acceptingInput", "ignoringInput", or "expectingInput". Default is "acceptingInput".

Returns:

A task that represents the work queued to execute.

sendActivityBlind

public default CompletableFuture sendActivityBlind(Activity activity)

Sends an Activity to the sender of the incoming Activity without returning a ResourceResponse.

Parameters:

activity - The activity to send.

Returns:

A task that represents the work queued to execute.

setLocale

public abstract void setLocale(String withLocale)

Set the locale on this context object.

Parameters:

withLocale - The string of locale on this context object.

traceActivity

public static CompletableFuture traceActivity(TurnContext turnContext, String name)

Parameters:

turnContext - The turnContext.
name - The name of the activity.

Returns:

A future with the ResourceReponse.

traceActivity

public static CompletableFuture traceActivity(TurnContext turnContext, String name, Object value, String valueType, String label)

Sends a trace activity to the BotAdapter for logging purposes.

Parameters:

turnContext - The context for the current turn.
name - The value to assign to the activity's Activity#getName property.
value - The value to assign to the activity's Activity#getValue property.
valueType - The value to assign to the activity's Activity#getValueType property.
label - The value to assign to the activity's Activity#getLabel property.

Returns:

A task that represents the work queued to execute. If the adapter is being hosted in the Emulator, the task result contains a ResourceResponse object with the original trace activity's ID; otherwise, it contains a ResourceResponse object containing the ID that the receiving channel assigned to the activity.

updateActivity

public abstract CompletableFuture updateActivity(Activity withActivity)

Replaces an existing activity.

If the activity is successfully sent, the task result contains a ResourceResponse object containing the ID that the receiving channel assigned to the activity.

Before calling this, set the ID of the replacement activity to the ID of the activity to replace.

Parameters:

withActivity - New replacement activity.

Returns:

A task that represents the work queued to execute.

Applies to