Easy access to BotkitConversation actions and state management within conversation handlers. The BotkitDialogWrapper provides a simplified interface for controlling conversation flow and managing variables during dialog execution.
Creates a wrapper instance for convenient access to conversation state and actions. Typically created automatically by Botkit during conversation execution.
/**
* Create a new BotkitDialogWrapper instance
* @param dc DialogContext from the BotBuilder framework
* @param step Current conversation step information
*/
constructor(dc: DialogContext, step: BotkitConversationStep);Control conversation flow by navigating between different conversation threads.
/**
* Jump immediately to the named thread in the current conversation
* @param thread Name of the thread to jump to
*/
gotoThread(thread: string): Promise<void>;
/**
* Repeat the last message on the next turn of the conversation
*/
repeat(): Promise<void>;
/**
* End the current dialog and return control to the parent dialog or bot
*/
stop(): Promise<void>;Usage Examples:
// Jump to different thread based on user response
const convo = new BotkitConversation("survey", controller);
convo.ask("Are you satisfied with our service?", [
{
pattern: "yes",
handler: async (response, convo, bot) => {
await convo.gotoThread("positive_feedback");
}
},
{
pattern: "no",
handler: async (response, convo, bot) => {
await convo.gotoThread("negative_feedback");
}
},
{
default: true,
handler: async (response, convo, bot) => {
await bot.say("I didn't understand. Let me repeat the question.");
await convo.repeat();
}
}
], { key: "satisfaction" });
// Add messages to different threads
convo.addMessage("Thanks for the positive feedback!", "positive_feedback");
convo.addMessage("Sorry to hear that. How can we improve?", "negative_feedback");Manage conversation state and user responses through variable storage and retrieval.
/**
* Set a variable value in the conversation state
* @param key Variable name
* @param val Variable value
*/
setVar(key: string, val: any): void;
/**
* Access to all conversation variables and user responses
*/
vars: { [key: string]: any };Usage Examples:
const convo = new BotkitConversation("user_profile", controller);
convo.ask("What's your name?", async (response, convo, bot) => {
// Set variables manually
convo.setVar("user_name", response);
convo.setVar("timestamp", new Date().toISOString());
// Access all variables
console.log("Current variables:", convo.vars);
await bot.say(`Nice to meet you, ${convo.vars.user_name}!`);
}, { key: "name" });
convo.ask("What's your email?", async (response, convo, bot) => {
// Variables persist across conversation steps
const name = convo.vars.user_name;
await bot.say(`Thanks ${name}, I've recorded your email as ${response}`);
}, { key: "email" });Use conversation variables to create dynamic conversation flows:
const convo = new BotkitConversation("dynamic_flow", controller);
convo.ask("Are you a new or returning customer?", [
{
pattern: "new",
handler: async (response, convo, bot) => {
convo.setVar("customer_type", "new");
await convo.gotoThread("new_customer_flow");
}
},
{
pattern: "returning",
handler: async (response, convo, bot) => {
convo.setVar("customer_type", "returning");
await convo.gotoThread("returning_customer_flow");
}
}
], { key: "customer_type" });
// Thread for new customers
convo.addMessage("Welcome! Let me help you get started.", "new_customer_flow");
convo.addQuestion("What's your email address?", async (response, convo, bot) => {
await bot.say(`I've registered you with email: ${response}`);
}, { key: "email" }, "new_customer_flow");
// Thread for returning customers
convo.addMessage("Welcome back!", "returning_customer_flow");
convo.addQuestion("What can I help you with today?", async (response, convo, bot) => {
await bot.say("Let me look into that for you.");
}, { key: "request" }, "returning_customer_flow");Handle errors gracefully and provide recovery options:
const convo = new BotkitConversation("error_handling", controller);
convo.ask("Please enter a valid email address:", [
{
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
handler: async (response, convo, bot) => {
await bot.say("Great! Email address validated successfully.");
}
},
{
default: true,
handler: async (response, convo, bot) => {
convo.setVar("retry_count", (convo.vars.retry_count || 0) + 1);
if (convo.vars.retry_count >= 3) {
await bot.say("Too many invalid attempts. Let's skip this for now.");
await convo.gotoThread("skip_email");
} else {
await bot.say("That doesn't look like a valid email. Please try again.");
await convo.repeat();
}
}
}
], { key: "email" });
convo.addMessage("No problem, we can collect your email later.", "skip_email");The dialog wrapper is automatically created and passed to conversation handlers:
interface BotkitConvoHandler {
(answer: string, convo: BotkitDialogWrapper, bot: BotWorker, message: BotkitMessage): Promise<any>;
}
interface BotkitConversationStep {
index: number;
thread: string;
threadLength: number;
state: any;
options: any;
reason: DialogReason;
result: any;
values: any;
next: (stepResult) => Promise<any>;
}Usage Examples:
// The wrapper is automatically provided in conversation handlers
const convo = new BotkitConversation("example", controller);
convo.ask("What's your favorite color?", async (answer, convo, bot, message) => {
// `convo` parameter is a BotkitDialogWrapper instance
console.log("User answered:", answer);
console.log("All variables:", convo.vars);
// Use wrapper methods to control flow
if (answer === "blue") {
await convo.gotoThread("blue_thread");
} else {
convo.setVar("color_choice", answer);
await bot.say(`${answer} is a great choice!`);
}
}, { key: "color" });