botkit
Version:
Building Blocks for Building Bots
430 lines (429 loc) • 18.3 kB
TypeScript
/**
* @module botkit
*/
/**
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
*/
import { Botkit, BotkitMessage } from './core';
import { BotWorker } from './botworker';
import { BotkitDialogWrapper } from './dialogWrapper';
import { Dialog, DialogContext, DialogReason, DialogTurnStatus } from 'botbuilder-dialogs';
/**
* Definition of the handler functions used to handle .ask and .addQuestion conditions
*/
interface BotkitConvoHandler {
(answer: string, convo: BotkitDialogWrapper, bot: BotWorker, message: BotkitMessage): Promise<any>;
}
/**
* Definition of the trigger pattern passed into .ask or .addQuestion
*/
interface BotkitConvoTrigger {
type?: string;
pattern?: string | RegExp;
handler: BotkitConvoHandler;
default?: boolean;
}
/**
* Template for definiting a BotkitConversation template
*/
interface BotkitMessageTemplate {
text: ((template: any, vars: any) => string) | string[];
action?: string;
execute?: {
script: string;
thread?: string;
};
quick_replies?: ((template: any, vars: any) => any[]) | any[];
attachments?: ((template: any, vars: any) => any[]) | any[];
blocks?: ((template: any, vars: any) => any[]) | any[];
attachment?: ((template: any, vars: any) => any) | any;
attachmentLayout?: string;
channelData?: any;
collect: {
key?: string;
options?: BotkitConvoTrigger[];
};
}
export interface BotkitConversationStep {
/**
* The number pointing to the current message in the current thread in this dialog's script
*/
index: number;
/**
* The name of the current thread
*/
thread: string;
/**
* The length of the current thread
*/
threadLength: number;
/**
* A pointer to the current dialog state
*/
state: any;
/**
* A pointer to any options passed into the dialog when it began
*/
options: any;
/**
* The reason for this step being called
*/
reason: DialogReason;
/**
* The results of the previous turn
*/
result: any;
/**
* A pointer directly to state.values
*/
values: any;
/**
* A function to call when the step is completed.
*/
next: (stepResult: any) => Promise<any>;
}
/**
* An extension on the [BotBuilder Dialog Class](https://docs.microsoft.com/en-us/javascript/api/botbuilder-dialogs/dialog?view=botbuilder-ts-latest) that provides a Botkit-friendly interface for
* defining and interacting with multi-message dialogs. Dialogs can be constructed using `say()`, `ask()` and other helper methods.
*
* ```javascript
* // define the structure of your dialog...
* const convo = new BotkitConversation('foo', controller);
* convo.say('Hello!');
* convo.ask('What is your name?', async(answer, convo, bot) => {
* await bot.say('Your name is ' + answer);
* });
* controller.dialogSet.add(convo);
*
* // later on, trigger this dialog by its id
* controller.on('event', async(bot, message) => {
* await bot.beginDialog('foo');
* })
* ```
*/
export declare class BotkitConversation<O extends object = {}> extends Dialog<O> {
/**
* A map of every message in the dialog, broken into threads
*/
script: any;
private _prompt;
private _beforeHooks;
private _afterHooks;
private _changeHooks;
private _controller;
/**
* Create a new BotkitConversation object
* @param dialogId A unique identifier for this dialog, used to later trigger this dialog
* @param controller A pointer to the main Botkit controller
*/
constructor(dialogId: string, controller: Botkit);
/**
* Add a non-interactive message to the default thread.
* Messages added with `say()` and `addMessage()` will _not_ wait for a response, will be sent one after another without a pause.
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
*
* ```javascript
* let conversation = new BotkitConversation('welcome', controller);
* conversation.say('Hello! Welcome to my app.');
* conversation.say('Let us get started...');
* ```
*
* @param message Message template to be sent
*/
say(message: Partial<BotkitMessageTemplate> | string): BotkitConversation;
/**
* An an action to the conversation timeline. This can be used to go to switch threads or end the dialog.
*
* When provided the name of another thread in the conversation, this will cause the bot to go immediately
* to that thread.
*
* Otherwise, use one of the following keywords:
* * `stop`
* * `repeat`
* * `complete`
* * `timeout`
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
*
* ```javascript
*
* // go to a thread called "next_thread"
* convo.addAction('next_thread');
*
* // end the conversation and mark as successful
* convo.addAction('complete');
* ```
* @param action An action or thread name
* @param thread_name The name of the thread to which this action is added. Defaults to `default`
*/
addAction(action: string, thread_name?: string): BotkitConversation;
/**
* Cause the dialog to call a child dialog, wait for it to complete,
* then store the results in a variable and resume the parent dialog.
* Use this to [combine multiple dialogs into bigger interactions.](../conversations.md#composing-dialogs)
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
* ```javascript
* // define a profile collection dialog
* let profileDialog = new BotkitConversation('PROFILE_DIALOG', controller);
* profileDialog.ask('What is your name?', async(res, convo, bot) => {}, {key: 'name'});
* profileDialog.ask('What is your age?', async(res, convo, bot) => {}, {key: 'age'});
* profileDialog.ask('What is your location?', async(res, convo, bot) => {}, {key: 'location'});
* controller.addDialog(profileDialog);
*
* let onboard = new BotkitConversation('ONBOARDING', controller);
* onboard.say('Hello! It is time to collect your profile data.');
* onboard.addChildDialog('PROFILE_DIALOG', 'profile');
* onboard.say('Hello, {{vars.profile.name}}! Onboarding is complete.');
* ```
*
* @param dialog_id the id of another dialog
* @param key_name the variable name in which to store the results of the child dialog. if not provided, defaults to dialog_id.
* @param thread_name the name of a thread to which this call should be added. defaults to 'default'
*/
addChildDialog(dialog_id: string, key_name?: string, thread_name?: string): BotkitConversation;
/**
* Cause the current dialog to handoff to another dialog.
* The parent dialog will not resume when the child dialog completes. However, the afterDialog event will not fire for the parent dialog until all child dialogs complete.
* Use this to [combine multiple dialogs into bigger interactions.](../conversations.md#composing-dialogs)
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
* ```javascript
* let parent = new BotkitConversation('parent', controller);
* let child = new BotkitConversation('child', controller);
* parent.say('Moving on....');
* parent.addGotoDialog('child');
* ```
*
* @param dialog_id the id of another dialog
* @param thread_name the name of a thread to which this call should be added. defaults to 'default'
*/
addGotoDialog(dialog_id: string, thread_name?: string): BotkitConversation;
/**
* Add a message template to a specific thread.
* Messages added with `say()` and `addMessage()` will be sent one after another without a pause.
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
* ```javascript
* let conversation = new BotkitConversation('welcome', controller);
* conversation.say('Hello! Welcome to my app.');
* conversation.say('Let us get started...');
* // pass in a message with an action that will cause gotoThread to be called...
* conversation.addAction('continuation');
*
* conversation.addMessage('This is a different thread completely', 'continuation');
* ```
*
* @param message Message template to be sent
* @param thread_name Name of thread to which message will be added
*/
addMessage(message: Partial<BotkitMessageTemplate> | string, thread_name: string): BotkitConversation;
/**
* Add a question to the default thread.
* In addition to a message template, receives either a single handler function to call when an answer is provided,
* or an array of handlers paired with trigger patterns. When providing multiple conditions to test, developers may also provide a
* handler marked as the default choice.
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
* ```javascript
* // ask a question, handle the response with a function
* convo.ask('What is your name?', async(response, convo, bot, full_message) => {
* await bot.say('Oh your name is ' + response);
* }, {key: 'name'});
*
* // ask a question, evaluate answer, take conditional action based on response
* convo.ask('Do you want to eat a taco?', [
* {
* pattern: 'yes',
* type: 'string',
* handler: async(response_text, convo, bot, full_message) => {
* return await convo.gotoThread('yes_taco');
* }
* },
* {
* pattern: 'no',
* type: 'string',
* handler: async(response_text, convo, bot, full_message) => {
* return await convo.gotoThread('no_taco');
* }
* },
* {
* default: true,
* handler: async(response_text, convo, bot, full_message) => {
* await bot.say('I do not understand your response!');
* // start over!
* return await convo.repeat();
* }
* }
* ], {key: 'tacos'});
* ```
*
* @param message a message that will be used as the prompt
* @param handlers one or more handler functions defining possible conditional actions based on the response to the question.
* @param key name of variable to store response in.
*/
ask(message: Partial<BotkitMessageTemplate> | string, handlers: BotkitConvoHandler | BotkitConvoTrigger[], key: {
key: string;
} | string | null): BotkitConversation;
/**
* Identical to [ask()](#ask), but accepts the name of a thread to which the question is added.
*
* [Learn more about building conversations →](../conversations.md#build-a-conversation)
* @param message A message that will be used as the prompt
* @param handlers One or more handler functions defining possible conditional actions based on the response to the question
* @param key Name of variable to store response in.
* @param thread_name Name of thread to which message will be added
*/
addQuestion(message: Partial<BotkitMessageTemplate> | string, handlers: BotkitConvoHandler | BotkitConvoTrigger[], key: {
key: string;
} | string | null, thread_name: string): BotkitConversation;
/**
* Register a handler function that will fire before a given thread begins.
* Use this hook to set variables, call APIs, or change the flow of the conversation using `convo.gotoThread`
*
* ```javascript
* convo.addMessage('This is the foo thread: var == {{vars.foo}}', 'foo');
* convo.before('foo', async(convo, bot) => {
* // set a variable here that can be used in the message template
* convo.setVar('foo','THIS IS FOO');
*
* });
* ```
*
* @param thread_name A valid thread defined in this conversation
* @param handler A handler function in the form async(convo, bot) => { ... }
*/
before(thread_name: string, handler: (convo: BotkitDialogWrapper, bot: BotWorker) => Promise<any>): void;
/**
* This private method is called before a thread begins, and causes any bound handler functions to be executed.
* @param thread_name the thread about to begin
* @param dc the current DialogContext
* @param step the current step object
*/
private runBefore;
/**
* Bind a function to run after the dialog has completed.
* The first parameter to the handler will include a hash of all variables set and values collected from the user during the conversation.
* The second parameter to the handler is a BotWorker object that can be used to start new dialogs or take other actions.
*
* [Learn more about handling end of conversation](../conversations.md#handling-end-of-conversation)
* ```javascript
* let convo = new BotkitConversation(MY_CONVO, controller);
* convo.ask('What is your name?', [], 'name');
* convo.ask('What is your age?', [], 'age');
* convo.ask('What is your favorite color?', [], 'color');
* convo.after(async(results, bot) => {
*
* // handle results.name, results.age, results.color
*
* });
* controller.addDialog(convo);
* ```
*
* @param handler in the form async(results, bot) { ... }
*/
after(handler: (results: any, bot: BotWorker) => void): void;
/**
* This private method is called at the end of the conversation, and causes any bound handler functions to be executed.
* @param context the current dialog context
* @param results an object containing the final results of the dialog
*/
private runAfter;
/**
* Bind a function to run whenever a user answers a specific question. Can be used to validate input and take conditional actions.
*
* ```javascript
* convo.ask('What is your name?', [], 'name');
* convo.onChange('name', async(response, convo, bot) => {
*
* // user changed their name!
* // do something...
*
* });
* ```
* @param variable name of the variable to watch for changes
* @param handler a handler function that will fire whenever a user's response is used to change the value of the watched variable
*/
onChange(variable: string, handler: (response: any, convo: any, bot: any) => Promise<any>): void;
/**
* This private method is responsible for firing any bound onChange handlers when a variable changes
* @param variable the name of the variable that is changing
* @param value the new value of the variable
* @param dc the current DialogContext
* @param step the current step object
*/
private runOnChange;
/**
* Called automatically when a dialog begins. Do not call this directly!
* @ignore
* @param dc the current DialogContext
* @param options an object containing initialization parameters passed to the dialog. may include `thread` which will cause the dialog to begin with that thread instead of the `default` thread.
*/
beginDialog(dc: DialogContext, options: any): Promise<any>;
/**
* Called automatically when an already active dialog is continued. Do not call this directly!
* @ignore
* @param dc the current DialogContext
*/
continueDialog(dc: DialogContext): Promise<any>;
/**
* Called automatically when a dialog moves forward a step. Do not call this directly!
* @ignore
* @param dc The current DialogContext
* @param reason Reason for resuming the dialog
* @param result Result of previous step
*/
resumeDialog(dc: any, reason: any, result: any): Promise<any>;
/**
* Called automatically to process the turn, interpret the script, and take any necessary actions based on that script. Do not call this directly!
* @ignore
* @param dc The current dialog context
* @param step The current step object
*/
private onStep;
/**
* Run a dialog step, based on the index and thread_name passed in.
* @param dc The current DialogContext
* @param index The index of the current step
* @param thread_name The name of the current thread
* @param reason The reason given for running this step
* @param result The result of the previous turn if any
*/
private runStep;
/**
* Automatically called when the the dialog ends and causes any handlers bound using `after()` to fire. Do not call this directly!
* @ignore
* @param dc The current DialogContext
* @param value The final value collected by the dialog.
*/
end(dc: DialogContext): Promise<DialogTurnStatus>;
/**
* Translates a line from the dialog script into an Activity. Responsible for doing token replacement.
* @param line a message template from the script
* @param vars an object containing key/value pairs used to do token replacement on fields in the message template
*/
private makeOutgoing;
/**
* Responsible for doing token replacements recursively in attachments and other multi-field properties of the message.
* @param attachments some object or array containing values for which token replacements should be made.
* @param vars an object defining key/value pairs used for the token replacements
*/
private parseTemplatesRecursive;
/**
* Handle the scripted "gotothread" action - requires an additional call to runStep.
* @param thread The name of the thread to jump to
* @param dc The current DialogContext
* @param step The current step object
*/
private gotoThreadAction;
/**
* Accepts a Botkit script action, and performs that action
* @param path A conditional path in the form {action: 'some action', handler?: some handler function, maybe_other_fields}
* @param dc The current DialogContext
* @param step The current stpe object
*/
private handleAction;
}
export {};