Skip to main content
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

<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.

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.
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:

See also