> ## 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 event broker

> Write an event broker that sends conversation events to your own messaging system, or change a built-in broker.

An event broker receives every conversation event as it happens and publishes it
to a messaging system, so other systems can react to it. Mantle ships `pika`,
`sql`, `file`, `kafka`, `concurrent_kafka`, and `http` brokers. Write your own
when your messaging system is none of those, or subclass a built-in to change
what it sends.

## Before you start

Put your code in a package next to `agent.yml`: a folder named `addons/` with an
empty `__init__.py` file. Start `rasa` from the project root so the package can
be imported.

## Subclass `EventBroker`

Import `EventBroker` from `rasa.api.brokers.v1` and implement `connect` and
`publish`. `close` is optional. The base class does nothing, so override it only
when your broker holds a connection it needs to release.

```python addons/custom_event_broker.py theme={null}
from typing import Any

import requests

from rasa.api.brokers.v1 import EventBroker, EventBrokerSettings


class MyEventBroker(EventBroker):
    def __init__(self) -> None:
        super().__init__()
        self.endpoint = ""

    async def connect(self, settings: EventBrokerSettings) -> None:
        """Read settings from integrations.yml. Mantle awaits this once at startup."""
        self.endpoint = settings.params["endpoint"]

    def publish(self, event: dict[str, Any]) -> None:
        """Send one event to your system. Mantle calls this for each new event, in order."""
        response = requests.post(self.endpoint, json=event, timeout=5)
        response.raise_for_status()
```

`publish` receives each event as a dictionary. The dictionary has envelope
fields, such as `conversation_id`, `timestamp`, and `sequence`, and one payload
key, such as `user`, `bot`, or `memory_set`. See
[Conversation events](https://rasa.com/docs/mantle/reference/events.md) for the full shape. `publish` is
synchronous, so keep it fast. Hand slow work to a queue or a background worker.

Register the class under `event_broker`:

```yaml integrations.yml theme={null}
event_broker:
  type: addons.custom_event_broker.MyEventBroker
  endpoint: ${EVENT_WEBHOOK_URL}
```

| Method | Required | Purpose |
| - | - | - |
| `connect(settings)` | yes | Async. Set up your client, using `settings.params`. Mantle awaits it at startup |
| `publish(event)` | yes | Send one event, given as a dictionary |
| `close()` | no | Async. Release the connection when the agent shuts down. The default does nothing |
| `publish_batch(events)` | no | Send several events in one call. The default publishes them one at a time |

## Subclass a built-in broker

To change what a built-in broker sends and keep the rest, subclass it from
`rasa.api.brokers.v1` and override `publish`. Mantle sends events through
`publish_batch`, which calls `publish` once per event unless you override
`publish_batch` too.

This example uses `KafkaEventBroker` and drops agent replies, so the topic
receives only user messages:

```python addons/custom_kafka_broker.py theme={null}
from typing import Any

from rasa.api.brokers.v1 import KafkaEventBroker


class MyKafkaEventBroker(KafkaEventBroker):
    def publish(self, event: dict[str, Any], *args: Any, **kwargs: Any) -> None:
        """Drop agent replies, and pass every other event to the built-in publish."""
        if "bot" in event:
            return
        super().publish(event, *args, **kwargs)
```

```yaml integrations.yml theme={null}
event_broker:
  type: addons.custom_kafka_broker.MyKafkaEventBroker
  url: ${KAFKA_URL}
  topic: rasa_events
```

The keys in [`event_broker`](https://rasa.com/docs/mantle/reference/integrations-yml#event_broker) apply to
your subclass. Keep `type` set to the class path, because the built-in name
`kafka` selects the built-in class.

## Versioning

The import `rasa.api.brokers.v1` is the version. YAML names only the class. See
[Custom integrations: Versioning](https://rasa.com/docs/mantle/reference/custom-integrations.md#versioning).


## Related topics

- [Event Brokers](https://rasa.com/docs/reference/integrations/event-brokers.md)
- [Custom integrations](https://rasa.com/docs/mantle/reference/custom-integrations.md)
- [integrations.yml](https://rasa.com/docs/mantle/reference/integrations-yml.md)
- [Lock Stores](https://rasa.com/docs/reference/integrations/lock-stores.md)
- [Mantle Changelog](https://rasa.com/docs/mantle/changelog.md)


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