LangBot Docs

English

简体中文

English

简体中文

Appearance

API Reference ​

Table of Contents

Event API ​

The following APIs are only available in event handler functions.

Reply to Message ​

python
await ctx.reply(message_chain: MessageChain)

Reply to the conversation that initiated this event.

  • message_chain: Message Chain object, the program can automatically convert it to the target message platform's message chain

Send Active Message ​

Due to poor support for active messages in QQ Official API, if users are using QQ Official API, sending active messages may fail

python
await ctx.send_message(target_type: str, target_id: str, message_chain: MessageChain)

Send an active message to the target.

  • target_type: Target type, possible values: "person", "group"
  • target_id: Target ID (QQ number or group number)
  • message_chain: Message Chain object, the program can automatically convert it to the target message platform's message chain

Prevent Default Event Behavior ​

python
ctx.prevent_default()

Prevent the default behavior of this event, i.e., stop the subsequent behaviors in the processing flow (such as getting a reply from the interface when receiving a private chat message, getting a reply from the interface when receiving a group message, etc.).

Prevent Subsequent Plugin Execution ​

python
ctx.prevent_postorder()

Prevent the execution of subsequent plugins for this event. To modify the execution order of plugins, please change the priority through the methods described in the "Plugin Management" section of the "Plugin Introduction".

Add Return Value ​

python
ctx.add_return(name: str, value: Any)

Add a return value. Event return values are all optional. For return values supported by each event, please check the comments of each event in pkg.plugin.events.

Request API ​

A Request (Query) refers to the program context when a user sends a question to LangBot and LangBot processes that question. The APIs in this section are used to interact with these contexts.

  • In event handler functions, the Query object is usually located at ctx.event.query

Set Request Variable ​

python
ctx.event.query.set_variable(key: str, value: typing.Any)

Request variables are a dict bound to this Query, which contains some program context information. If you are using Dify or Alibaba Cloud Bailian or other LLMOps runners, these variables will be passed to the corresponding platform's API as variables.
If you need to set variables using plugins, it is recommended to handle them during the PromptPreProcessing event.

  • key: The name of the variable
  • value: The value of the variable

Get Request Variable ​

python
ctx.event.query.get_variable(key: str)

Get a request variable.

  • key: Variable name
  • Return value: typing.Any

Get All Request Variables ​

python
ctx.event.query.get_variables()

Get all variable values set for this Query object.

  • Return value: dict[str, typing.Any]

LangBot API ​

The following APIs are provided directly by LangBot for plugins to call and can be called outside of event handler functions.

  • host represents an object of the pkg.plugin.context.APIHost class, which is included in each plugin class.

Get Enabled Message Platform Adapters List ​

python
host.get_platform_adapters()

Get a list of enabled message platform adapters.

  • Return value: list[pkg.platform.adapter.MessageSourceAdapter]

Send Active Message ​

python
await host.send_active_message(adapter: pkg.platform.adapter.MessageSourceAdapter, target_type: str, target_id: str, message_chain: MessageChain)

Send an active message to the target.

  • adapter: Message platform adapter, obtained through host.get_platform_adapters() and selecting one of them
  • target_type: Target type, possible values: "person", "group"
  • target_id: Target ID (QQ number or group number)
  • message_chain: Message Chain object, the program can automatically convert it to the target message platform's message chain

INFO

  • Some message platforms may not support active messages or have strict limitations
  • Some message platform adapters (such as aiocqhttp) act as servers waiting for message platforms to connect and push messages. Before a successful connection, sending active messages will fail

Example:

python
import asyncio
import pkg.platform.types as platform_types

...

    # initialize function of a plugin
    # This code will attempt to send a message "hello, world!" to QQ number 1010553892 10 seconds after LangBot starts
    async def initialize(self):
        print(self.host.get_platform_adapters())
        
        async def send_message():
            print("send message start waiting")
            await asyncio.sleep(10)

            try:
                await self.host.send_active_message(
                    adapter=self.host.get_platform_adapters()[0],
                    target_type="person",
                    target_id="1010553892",
                    message=platform_types.MessageChain([
                        platform_types.Plain("hello, world!")
                    ])
                )
            except Exception as e:
                traceback.print_exc()
            print("send message end")

        asyncio.get_running_loop().create_task(send_message())