# Component: Event Listener

Source: https://langbot.app/docs/en/plugin/dev/components/event-listener

> info:
>
> This component extends Pipeline processing steps. To handle Bot events such as incoming messages and new group members, see [Event Processor](https://langbot.app/docs/en/plugin/dev/components/runner.md).

LangBot's pipeline generates events during runtime for plugins to hook into and process. Each plugin can only have one event listener (components/event\_listener/default.yaml), but can register any number of events within it.

## Adding Event Listener Component

Execute the command `lbp comp EventListener` in the plugin directory. Creating an event listener component doesn't require any configuration.

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。
```

This will generate `default.yaml` and `default.py` files in the `components/event_listener/` directory. The `.yaml` file defines the basic information for the event listener, and the `.py` file is the event listener handler:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── event_listener
│       ├── __init__.py
│       ├── default.py
│       └── default.yaml
...
```

## Manifest File: Event Listener

Since each plugin can only have one event listener, no modifications are needed in the manifest file.

## Plugin Processing

The following code is generated by default (components/event\_listener/default.py). You need to register and implement event processing logic in the `initialize` method of the `DefaultEventListener` class.

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities import events, context


class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"
```

Adding listeners for specific events:

```python
...
class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()
        
        @self.handler(events.PersonMessageReceived)
        async def handler(event_context: context.EventContext):
            print("Hello LangBot Plugin!")
            print(event_context)
            
            await event_context.reply(
                platform_message.MessageChain([
                    platform_message.Plain(text=f"Hello from Nahida Plugin!"),
                ])
            )
```

This code registers a listener for the `PersonMessageReceived` (receiving any message from private chat) event, prints the event context (EventContext) information when the event is triggered, and calls the event context API to reply with a message.

EventContext stores common context information for this event trigger, while EventContext.event is an object of PersonMessageReceived (or other corresponding event types), storing detailed information about the event.

```python
# Summary of EventContext definition
class EventContext(pydantic.BaseModel):
    """Event context, stores information for this event execution"""
    ...

    event: pydantic.SerializeAsAny[BaseEventModel]
    """Event object, specific type is the type specified when registering the handler, can be found in events.py"""
    
    ...
```

## Event Registration

Event registration is implemented through the `@self.handler` decorator, with the decorator parameter being the event type. All monitorable events are defined in `langbot_plugin.api.entities.builtin.events`.

## One installation, many usages

The same event listener is called **concurrently by several Workspaces and several events**:

- Never accumulate state per event on the instance (counters, last event, conversation maps); concurrent callbacks will overwrite each other.
- A callback takes its data only from the current `EventContext`; never reuse a context or its fields across calls.
- Data that must survive calls belongs in Host storage, keyed with the installation identity and the event-related identity (Workspace, conversation, and so on).
- If you keep per-installation process-local state, release it in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## What's Next

You have learned the basic information about event listeners. Next, you can:

- See [Pipeline Events](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md) for event types and fields.
- See the complete [`EventContext` API reference](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#eventlistener).
- Check out [Plugin Common APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md)