<commit_before># Botkit Conversations

Botkit's core SDK ships with a Botkit-friendly dialog class called [BotkitConversation](reference/core.md#botkitconversation). This class offers developers a familiar syntax for creating scripted dialogs,
and injecting dynamic behaviors. 

Dialogs are created using functions like [convo.ask()](reference/core.md#ask) and [convo.say()](reference/core.md#say-1), and dynamic actions can be implemented using a hook system ([convo.before()](reference/core.md#before), [convo.after()](reference/core.md#after) and [convo.onChange()](reference/core.md#onchange)) that provides conversation context and a `bot` worker object at key points in the dialog's execution.

## Import the class

To use BotkitConversations, make sure to import the class along with Botkit:

```javascript
const { Botkit, BotkitConversation } = require('botkit';
```

## Anatomy of a Botkit Conversation

The `BotkitConversation` class is an implementation of the generic [BotBuilder Dialog Class](https://npmjs.com/package/botbuilder-dialogs) that provides a fluent interface for defining the structure and content of an interactive dialog. Note that the following information is specific to BotkitConversations, and does not apply to other dialog types like `WaterfallDialog` that, while compatible with Botkit, do not have all of the same features.

BotkitConversations are constructed from one or more sequences of messages known as "[threads](#conversation-threads)." The threads are linked to one another through special conditional actions that can be part of an `ask()` prompt, or defined directly in the thread using `addAction()`. Each item in a thread is actually a message template - they can include variable tokens that will be replaced with live values automatically before being sent.

All dialogs must be defined and added to the Botkit controller _at start time._ It is bad practice to create new dialogs from within handler functions or in response to user actions - this may cause your bot to lose its place in the conversation, or become confused. Think about it this way: your bot has to know every possible dialog and action it might take at start time so that it can consistently respond across multiple instances of the application, or between restarts.

### Beginning

Before a BotkitConveration begins, it will first fire any functions bound to it using the [before()](reference/core.md#before) hook. These functions can create or change variables, and take other necessary actions - for example, looking up values in a database or external API for use in the conversation.

BotkitConversations start on the first message of the "default" thread, and proceed through the chain of messages.  When a prompt is encountered, the bot will pause and wait for the user to respond, then evaluate any associated handler functions and conditional tests. The bot will continue to process messages in the thread until it reaches a prompt, an action, or the end of the thread.

### Middle

As each message is read from the dialog script and sent to the user, it is evaluated for template variables. Variables may be used in almost any field in the message object. [Learn more about using variables &rarr;](#using-variable-tokens-and-templates-in-conversation-threads)

When a prompt is encountered, the message will first be sent to the user. The bot will then wait for the next message to arrive.  When it does, the value of the incoming message will automatically be captured into a variable, and any [onChange()](reference/core.md#onchange) functions that have been bound to that variable will fire. These handler functions can be used to validate the incoming value, or take other conditional actions based on the user input.

After any `onChange` hooks fire, Botkit will proceed to evaluate the handler function or conditional tests that were initially passed in to `ask()` or `addQuestion()`. These functions may set variables, or modify the flow of the dialog by calling [repeat()](reference/core.md#repeat) or [gotoThread()](reference/core.md#gotothread).

Hook functions can be bound to the beginning of _each thread_ using [before()](reference/core.md#before). Each thread will fire it's own `before` hooks _before_ sending the first message. This can be used for a variety of purposes, including conditionally skipping a thread (by calling `gotoThread()` from inside a `before()` hook).

### End

When the dialog reaches its end (no messages remaining to be sent, or one of the end actions called), it will fire its last set of hooks, and then finally come to an end.  The end of a conversation can be thought of in the same light as a web form "submit" -- all of the user responses and any other information collected during the course of the conversation will be sent to the final hook for processing.  Commonly, these hooks are used to store/submit that information, and then possibly to begin the next dialog.
<commit_msg>flesh out docs for conversations<commit_after># Botkit Conversations

Botkit's core SDK ships with a Botkit-friendly dialog class called [BotkitConversation](reference/core.md#botkitconversation). This class offers developers a familiar syntax for creating scripted dialogs,
and injecting dynamic behaviors. 

Dialogs are created using functions like [convo.ask()](reference/core.md#ask) and [convo.say()](reference/core.md#say-1), and dynamic actions can be implemented using a hook system ([convo.before()](reference/core.md#before), [convo.after()](reference/core.md#after) and [convo.onChange()](reference/core.md#onchange)) that provides conversation context and a `bot` worker object at key points in the dialog's execution.

## Import the class

To use BotkitConversations, make sure to import the class along with Botkit:

```javascript
const { Botkit, BotkitConversation } = require('botkit';
```

## Anatomy of a Botkit Conversation

The `BotkitConversation` class is an implementation of the [BotBuilder Dialog base class](https://npmjs.com/package/botbuilder-dialogs) that provides a fluent interface for defining the structure and content of an interactive dialog. Note that the following information is specific to BotkitConversations, and does not apply to other dialog types like `WaterfallDialog` that, while compatible with Botkit, do not have all of the same features.

BotkitConversations are constructed from one or more sequences of messages known as "[threads](#conversation-threads)." The threads are linked to one another through special conditional actions that can be part of an `ask()` prompt, or defined directly in the thread using `addAction()`. Each item in a thread is actually a message template - they can include variable tokens that will be replaced with live values automatically before being sent. [Read about constructing a dialog here &rarr;](#build-a-conversation)

All dialogs must be defined and added to the Botkit controller _at start time._ It is bad practice to create new dialogs from within handler functions or in response to user actions - this may cause your bot to lose its place in the conversation, or become confused. Think about it this way: your bot has to know every possible dialog and action it might take at start time so that it can consistently respond across multiple instances of the application, or between restarts.

### Beginning

Before a BotkitConveration begins, it will first fire any functions bound to it using the [before()](reference/core.md#before) hook. These functions can create or change variables, and take other necessary actions - for example, looking up values in a database or external API for use in the conversation.

BotkitConversations start on the first message of the "default" thread, and proceed through the chain of messages.  When a prompt is encountered, the bot will pause and wait for the user to respond, then evaluate any associated handler functions and conditional tests. The bot will continue to process messages in the thread until it reaches a prompt, an action, or the end of the thread.

### Middle

As each message is read from the dialog script and sent to the user, it is evaluated for template variables. Variables may be used in almost any field in the message object. [Learn more about using variables &rarr;](#using-variable-tokens-and-templates-in-conversation-threads)

When a prompt is encountered, the message will first be sent to the user. The bot will then wait for the next message to arrive.  When it does, the value of the incoming message will automatically be captured into a variable, and any [onChange()](reference/core.md#onchange) functions that have been bound to that variable will fire. These handler functions can be used to validate the incoming value, or take other conditional actions based on the user input.

After any `onChange` hooks fire, Botkit will proceed to evaluate the handler function or conditional tests that were initially passed in to `ask()` or `addQuestion()`. These functions may set variables, or modify the flow of the dialog by calling [repeat()](reference/core.md#repeat) or [gotoThread()](reference/core.md#gotothread).

Hook functions can be bound to the beginning of _each thread_ using [before()](reference/core.md#before). Each thread will fire it's own `before` hooks _before_ sending the first message. This can be used for a variety of purposes, including conditionally skipping a thread (by calling `gotoThread()` from inside a `before()` hook).

### End

When the dialog reaches its end (no messages remaining to be sent, or one of the end actions called), it will fire its last set of hooks, and then finally come to an end.  The end of a conversation can be thought of in the same light as a web form "submit" -- all of the user responses and any other information collected during the course of the conversation will be sent to the final hook for processing.  Commonly, these hooks are used to store/submit that information, and then possibly to begin the next dialog.

{'fraction_non_alphanumeric': 0.05767692922830868, 'fraction_numerical': 0.00019992003198720512, 'mean_word_length': 4.998201438848921, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1338747', 'n_tokens_mistral': 2346, 'n_tokens_neox': 2286, 'n_words': 1433}