LangBot Docs

English

简体中文

English

简体中文

Appearance

Component: Event Listener ​

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://docs.langbot.app/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.

What's Next ​

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