LangBot/docs/en/plugin/dev/api-ref.md

# API Reference

:::info Table of Contents
[[toc]]
:::

## 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](./messages.md), 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](./messages.md), 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](/en/deploy/pipelines/readme.html#conversation-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](./messages.md), 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())
```