# Feishu

Feishu access uses Feishu Open Platform long connection event subscriptions. Users can DM or mention the bot to query status, send commands, or ask device questions; text, rich text, images, and voice are supported, with ASR required for voice.

## Usage Modes

| Mode | Trigger | Notes |
| --- | --- | --- |
| Bot DM | Send a message directly to the bot | Good for personal status queries and control commands. |
| Group mention | Mention the bot in a group chat and enter a question | Good for team collaboration around devices. |
| Image message | Send an image, optionally with text | Images enter the Device Agent as visual input. |
| Voice message | Send a voice message | Requires ASR configuration. Voice is transcribed before entering the conversation. |

## Prepare the Feishu App

1. Create an internal app in Feishu Open Platform.
2. Add bot capability.
3. Copy `App ID` and `App Secret` from credentials and basic information.
4. Enable event subscription through long connection mode.
5. Subscribe to `im.message.receive_v1`.
6. Grant the permissions required for reading messages and sending bot replies.
7. Publish the app and add the bot to the DMs or groups where it will be used.

If event subscription uses encryption or verification token checks, keep `Encrypt Key` and `Verification Token` and enter them in the Device Agent console.

## Configure Device Agent

Open **Settings → Channels → Feishu** and fill in:

| Field | `.env` | Description |
| --- | --- | --- |
| Enabled | `FEISHU_ENABLED` | Starts the Feishu channel |
| App ID | `FEISHU_APP_ID` | Feishu app `App ID`, usually `cli_xxx` |
| App Secret | `FEISHU_APP_SECRET` | Feishu app secret |
| Encrypt Key | `FEISHU_ENCRYPT_KEY` | Optional. Required when encrypted event subscription is enabled |
| Verification Token | `FEISHU_VERIFICATION_TOKEN` | Optional. Required when token verification is configured |
| Allow list | `FEISHU_ALLOW_FROM` | Optional Feishu user `open_id` allow list |

You can also configure it in `.env`:

```bash
FEISHU_ENABLED=true
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=
FEISHU_VERIFICATION_TOKEN=
FEISHU_ALLOW_FROM=ou_xxx,ou_yyy
```

Restart the service after saving.

## Verify Access

1. Confirm the service has restarted.
2. Check logs for `Feishu: enabled` and `feishu channel started (WebSocket)`.
3. Send a DM to the bot, or mention the bot in a group.
4. If the allow list is enabled, make sure the sender `open_id` is included.

In group chats, mention the bot. In DMs, send messages directly. Image messages enter the Device Agent as visual input. Voice messages are transcribed before entering the conversation.

## Checks

- No reply: confirm the app is published, the bot is in the chat, and long connection event subscription is enabled.
- Token verification fails: confirm `Verification Token` matches the Feishu console.
- Encrypted messages fail: confirm `Encrypt Key` matches exactly, with no extra spaces.
- Voice is not transcribed: enable an ASR service in [Configuration](../../operate-reference/configuration.md).