> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Feishu Channel

`agentscope-extensions-channel-feishu` connects your Agent to Feishu / Lark (飞书) via the **Event Subscription v2** callback mechanism. A Spring `@RestController` receives webhook callbacks, optionally decrypts encrypted payloads, and dispatches messages through the Gateway.

## When to use

* Your Agent needs to respond to Feishu bot messages in 1:1 chats or group @-mentions.
* Your application already runs Spring Boot (the callback controller auto-registers).

## Add the dependency

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-channel-feishu</artifactId>
    <version>${agentscope.version}</version>
</dependency>
```

## Prerequisites

1. Create a **Custom App** in the [Feishu Developer Console](https://open.feishu.cn/).
2. Enable the **Bot** capability.
3. Configure the **Event Subscription** callback URL to point to your application:
   `https://your-host/api/channels/feishu/{channelId}/callback`
4. Note down the **App ID** and **App Secret**. Optionally configure an **Encrypt Key** and **Verification Token**.

## Quickstart

```java theme={null}
FeishuChannel channel = FeishuChannel.fromProperties(
    "my-feishu",
    ChannelConfig.of("my-feishu", "main"),
    Map.of(
        "appId",     "cli_xxxxx",
        "appSecret", "your-app-secret"
    ));

GatewayBootstrap gw = GatewayBootstrap.builder()
    .agent("main", agent)
    .channel(channel)
    .build();

gw.start();
```

The `FeishuCallbackController` is a Spring `@RestController` that auto-registers at `/api/channels/feishu/{channelId}/callback`. It handles the URL verification handshake automatically.

## Configuration properties

| Property | Required | Default | Description |
| - | - | - | - |
| `appId` | Yes | — | Feishu custom-app id (cli\_xxx) |
| `appSecret` | Yes | — | Feishu custom-app secret |
| `encryptKey` | No | — | AES-256-CBC encrypt key; enables payload encryption |
| `verificationToken` | No | — | URL verification token for the challenge handshake |
| `callbackPath` | No | `/api/channels/feishu/{channelId}/callback` | Override the callback URL path |
| `apiBase` | No | `https://open.feishu.cn` | Feishu Open API base URL |

## Encryption

When `encryptKey` is configured, the callback body arrives as `{"encrypt":"<base64>"}`. The adapter decrypts it automatically (AES-256-CBC with SHA-256 key derivation) and verifies the `X-Lark-Signature` header.

## Message flow

**Inbound:** `FeishuCallbackController` → optional decryption → URL verification check → event\_id dedup → `FeishuInboundMapper` (text messages only in MVP) → bot-loop guard → Gateway.

**Outbound:** `FeishuOutboundClient` sends replies via `POST /open-apis/im/v1/messages` with a `tenant_access_token` from `FeishuAccessTokenProvider`. Tokens are cached and proactively refreshed at \~80% of TTL.


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