<commit_before>## Understanding the Middlewares

Middleware is a critical component of botpress. Simply put, it is a collection of functions that process messages. Think of it this way: everything that enters or leaves your bot is coming in to (or out of) the middleware.

If you have used [Express](http://expressjs.com/) before, botpress middleware is very similar to express's middleware.

Botpress has two middleware chains: [incoming](understading-the-middlewares.md#sendincomingmiddlewareevent---void) and [outgoing](understading-the-middlewares.md#sendoutgoingmiddlewareevent---void)

**To receive messages**: An installed module must send messages into the incoming middleware chain

**To send messages**: You (or a module) must send messages into the outgoing middleware chain and have a module able to send it to the right platform

### Example

**Incoming**: [botpress-messenger](https://github.com/botpress/botpress-messenger) connects to Facebook and receives messages from its built-in Webhook. It then sends messages into the incoming middleware, which your bot can process.

**Outgoing**: [botpress-messenger](https://github.com/botpress/botpress-messenger) listens (through a middleware function) for messages it can process on the outgoing middleware and sends them to Facebook through the Messenger Send API.

## Middleware Chain

A middleware chain is simply a collection of middleware functions that are called in a predertermined order. Each middleware function in the chain has the freedom to:
- execute arbitrary code
- mutate the event
- call the next middleware
- interrupt the chain by never calling the next middleware (what we call swallowing the event)
- interrupt the chain by throwing an error

## A simple middleware function

A middleware function is simply a function that takes an event as the first parameter and a `next` function as the second parameter.

Here's an example of the 5 possible cases:

```js
var middleware = function(event, next) {
    // chain interruption (error)
    if (internetDisconnected())
        return next(new Error('Not connected'))

    if (isUserBanned(event.user.id))
        return // swallow the event

    // arbitraty code execution
    var translation = Translator.translate(event.text)

    // event mutation
    event.text = translation

    // call next middleware function
    next()
}
```

The return value of the middleware function isn't used by Botpress.

## Registering middlewares

You need to register a middleware function for botpress to know about it and use it. You may do so with the [`bp.middlewares.register`](understading-the-middlewares.md#registermiddlewaredefinition---void) method:

```js
// ** code taken from botpress-messenger **
bp.middlewares.register({
    name: 'messenger.sendMessages', // friendly name
    type: 'outgoing', // either incoming or outgoing
    order: 100, // arbitrary number
    handler: outgoingMiddleware, // the middleware function
    module: 'botpress-messenger', // the name of the module, if any
    description: 'Sends out messages that targets platform = '
    + 'messenger. This middleware should be placed at the end as it swallows events once sent.'
})
```

Once all middleware functions have been registered (usually modules should register middleware functions immediately in their initialization), **you must load them** using [`bp.middlewares.load()`](core-reference.md#load---void), which will create the incoming and outgoing chains automatically.

Once middleware functions are loaded, you'll see them displayed in your bot's interface:

![](https://raw.githubusercontent.com/botpress/botpress/master/assets/screenshot-middlewares.png)

## Ordering middleware functions

By default, middleware functions are ordered by **ascending order** according to their `order` property set on registration. The order can then be manually overwritten:

![](https://raw.githubusercontent.com/botpress/botpress/master/assets/screenshot-middlewares-order.png)
<commit_msg>[Docs] Fixing anchor links at page: Understanding the middleware<commit_after>## Understanding the Middlewares

Middleware is a critical component of botpress. Simply put, it is a collection of functions that process messages. Think of it this way: everything that enters or leaves your bot is coming in to (or out of) the middleware.

If you have used [Express](http://expressjs.com/) before, botpress middleware is very similar to express's middleware.

Botpress has two middleware chains: [incoming](understading-the-middlewares.md#sendincomingmiddlewareevent---void) and [outgoing](understading-the-middlewares.md#sendoutgoingmiddlewareevent---void)

**To receive messages**: An installed module must send messages into the incoming middleware chain

**To send messages**: You (or a module) must send messages into the outgoing middleware chain and have a module able to send it to the right platform

### Example

**Incoming**: [botpress-messenger](https://github.com/botpress/botpress-messenger) connects to Facebook and receives messages from its built-in Webhook. It then sends messages into the incoming middleware, which your bot can process.

**Outgoing**: [botpress-messenger](https://github.com/botpress/botpress-messenger) listens (through a middleware function) for messages it can process on the outgoing middleware and sends them to Facebook through the Messenger Send API.

## Middleware Chain

A middleware chain is simply a collection of middleware functions that are called in a predertermined order. Each middleware function in the chain has the freedom to:
- execute arbitrary code
- mutate the event
- call the next middleware
- interrupt the chain by never calling the next middleware (what we call swallowing the event)
- interrupt the chain by throwing an error

## A simple middleware function

A middleware function is simply a function that takes an event as the first parameter and a `next` function as the second parameter.

Here's an example of the 5 possible cases:

```js
var middleware = function(event, next) {
    // chain interruption (error)
    if (internetDisconnected())
        return next(new Error('Not connected'))

    if (isUserBanned(event.user.id))
        return // swallow the event

    // arbitraty code execution
    var translation = Translator.translate(event.text)

    // event mutation
    event.text = translation

    // call next middleware function
    next()
}
```

The return value of the middleware function isn't used by Botpress.

## Registering middlewares

You need to register a middleware function for botpress to know about it and use it. You may do so with the [`bp.middlewares.register`](understading-the-middlewares.md#registermiddlewaredefinition-void) method:

```js
// ** code taken from botpress-messenger **
bp.middlewares.register({
    name: 'messenger.sendMessages', // friendly name
    type: 'outgoing', // either incoming or outgoing
    order: 100, // arbitrary number
    handler: outgoingMiddleware, // the middleware function
    module: 'botpress-messenger', // the name of the module, if any
    description: 'Sends out messages that targets platform = '
    + 'messenger. This middleware should be placed at the end as it swallows events once sent.'
})
```

Once all middleware functions have been registered (usually modules should register middleware functions immediately in their initialization), **you must load them** using [`bp.middlewares.load()`](understading-the-middlewares.md#load-void), which will create the incoming and outgoing chains automatically.

Once middleware functions are loaded, you'll see them displayed in your bot's interface:

![](https://raw.githubusercontent.com/botpress/botpress/master/assets/screenshot-middlewares.png)

## Ordering middleware functions

By default, middleware functions are ordered by **ascending order** according to their `order` property set on registration. The order can then be manually overwritten:

![](https://raw.githubusercontent.com/botpress/botpress/master/assets/screenshot-middlewares-order.png)

{'fraction_non_alphanumeric': 0.08015882863878893, 'fraction_numerical': 0.0009926789924308227, 'mean_word_length': 4.581717451523546, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3398113', 'n_tokens_mistral': 2102, 'n_tokens_neox': 2015, 'n_words': 920}