> ## Documentation Index
> Fetch the complete documentation index at: https://rasa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom integrations

> Write a Python class that replaces a built-in Mantle component for storage, timers, events, knowledge, channels, or speech, and name it in integrations.yml.

A custom integration is a Python class you write to replace a built-in part of
the Mantle runtime. Mantle calls your class where it would otherwise call the
built-in one.

Write one when a built-in does not fit your setup. Examples: conversations must
be stored in your own database, every event must reach your messaging system, or
a channel's webhook format differs from the built-in connectors.

Every custom integration has the same three parts:

1. **A base class** you subclass. You import it from `rasa.api.<stage>.<version>`.
   The import names the version, for example `rasa.api.locks.v1`.
2. **A Python module** in a Python package next to `agent.yml`.
3. **A YAML key** in `integrations.yml` that names your class by its module path.

You can also subclass a built-in class from the same package, when you only want
to change one method of it.

## Stages

| Stage | Subclass | Import | YAML key | How-to |
| - | - | - | - | - |
| Lock store | `BaseLockStore` | `rasa.api.locks.<version>` | [`lock_store.type`](https://rasa.com/docs/mantle/reference/integrations-yml#lock_store) | [Write a custom lock store](https://rasa.com/docs/mantle/reference/custom-lock-store.md) |
| Timer store | `SessionTimerStore` | `rasa.api.timers.<version>` | [`timer_store.type`](https://rasa.com/docs/mantle/reference/integrations-yml#timer_store) | [Write a custom timer store](https://rasa.com/docs/mantle/reference/custom-timer-store.md) |
| Tracker store | `BaseTrackerStore` | `rasa.api.tracker.<version>` | [`tracker_store.type`](https://rasa.com/docs/mantle/reference/integrations-yml#tracker_store) | [Write a custom tracker store](https://rasa.com/docs/mantle/reference/custom-tracker-store.md) |
| Event broker | `EventBroker` | `rasa.api.brokers.<version>` | [`event_broker.type`](https://rasa.com/docs/mantle/reference/integrations-yml#event_broker) | [Write a custom event broker](https://rasa.com/docs/mantle/reference/custom-event-broker.md) |
| Knowledge store | `KnowledgeStore` | `rasa.api.knowledge.<version>` | [`knowledge_stores[].type`](https://rasa.com/docs/mantle/reference/integrations-yml#knowledge_stores) | [Write a custom knowledge store](https://rasa.com/docs/mantle/reference/custom-knowledge-store.md) |
| Channel | `InputChannel` | `rasa.api.channels.<version>` | [`channels`](https://rasa.com/docs/mantle/reference/integrations-yml#channels) | [Write a custom channel](https://rasa.com/docs/mantle/reference/custom-channels.md) |
| Speech recognition | `ASREngine` | `rasa.api.voice.asr.<version>` | [`asr.provider`](https://rasa.com/docs/mantle/reference/integrations-yml#voice-channels) | [Write a custom speech recognition engine](https://rasa.com/docs/mantle/reference/custom-speech-providers.md#custom-speech-recognition) |
| Speech synthesis | `TTSEngine` | `rasa.api.voice.tts.<version>` | [`tts.provider`](https://rasa.com/docs/mantle/reference/integrations-yml#voice-channels) | [Write a custom speech synthesis engine](https://rasa.com/docs/mantle/reference/custom-speech-providers.md#custom-speech-synthesis) |

`<version>` is the published version of that stage. In this release it is `v1`
for every stage. Shared audio types for speech are in `rasa.api.voice.<version>`.
See [Versioning](#versioning).

## Get started

1. Find your integration in the table and open its how-to.
2. Write the class in a package next to `agent.yml`, for example `addons/`.
   Add an empty `__init__.py` file in that folder so Python can import it.
3. Name the class in `integrations.yml` with the YAML key for its stage.
4. Run `rasa train` from the project root. For every integration except knowledge
   stores, train imports your class and fails if it is not a subclass of the
   base. Knowledge stores are different because Mantle does not load them at
   train or at runtime yet, so train only checks that each entry has `id`,
   `type`, and `embeddings`. See
   [Custom knowledge store](https://rasa.com/docs/mantle/reference/custom-knowledge-store.md).

YAML names the class only. It has no version field.

## Versioning

The version is part of the import. `rasa.api.locks.v1` names version 1 of the
lock store API. YAML does not name a version, so the `lock_store.type` value
stays the same when a new version ships.

Rasa supports the current version of each stage and one previous version. A
version stays supported until the version after it ships:

* While `v1` is current, write `from rasa.api.locks.v1 import BaseLockStore`.
* When `v2` ships, `v1` is deprecated. `v2` becomes current and `v1` becomes
  the previous version. Your class keeps loading through an adapter that Rasa
  owns, and you do not change `integrations.yml`. New classes import `v2`.
* When `v3` ships, `v1` is no longer supported. Startup fails and names the
  import that is no longer supported. Move your import to a supported version
  before you upgrade.

Here is what moving looks like. `v2` does not exist yet, so this example is
hypothetical:

```python theme={null}
# Written against v1, the current version today
from rasa.api.locks.v1 import BaseLockStore

# After you move to v2, once it is published
from rasa.api.locks.v2 import BaseLockStore
```

## See also

* [`integrations.yml`](https://rasa.com/docs/mantle/reference/integrations-yml) for the field tables of each key above


## Related topics

- [Custom channel](https://rasa.com/docs/mantle/reference/custom-channels.md)
- [Custom event broker](https://rasa.com/docs/mantle/reference/custom-event-broker.md)
- [Custom knowledge store](https://rasa.com/docs/mantle/reference/custom-knowledge-store.md)
- [Custom timer store](https://rasa.com/docs/mantle/reference/custom-timer-store.md)
- [Custom tracker store](https://rasa.com/docs/mantle/reference/custom-tracker-store.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.