Skip to content

Commit 64430fa

Browse files
authored
docs: sync Lark/Feishu guide with current capabilities and permissions (#10400)
* docs: sync Lark/Feishu guide with current capabilities and permissions The Lark guide still described the adapter as of v4.15.0: - Receiving voice, video, and files has been supported since v4.16.0, and quoted (reply) message contents are parsed as well. - Documented config field names (encrypt_key, verification_token) did not match the actual lark_encrypt_key / lark_verification_token. - The permission list recommended im:message:send and im:resource:upload, which Feishu no longer accepts for new applications; im:message covers sending and im:resource covers resource upload/download. The one-click permission URL is updated accordingly. - Group chats only receive @-mentioned messages unless im:message.group_msg is granted, so the wake-prefix wording and the final /help step were corrected. - Long connections are supported for both Lark China and Lark International; webhook is only a fallback, not a requirement for international Lark. * docs: correct Lark media support in plugin platform matrix The zh plugin platform matrix marked Lark Record and Video as unsupported, but the adapter receives and sends both. * docs: clarify Lark group delivery and wake conditions The group-chat wording only mentioned @ mentions. Delivery (which events Lark pushes to AstrBot) and waking (which received messages AstrBot responds to) are separate layers: a group chat only pushes messages that @ mention the bot unless im:message.group_msg is granted, while AstrBot also responds to @ALL (unless ignore_at_all is set), replies to its own messages, and wake-prefixed messages.
1 parent 57ac1d8 commit 64430fa

3 files changed

Lines changed: 35 additions & 27 deletions

File tree

‎docs/en/platform/lark.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22

33
## Supported Message Types
44

5-
> Version v4.15.0.
5+
> Version v4.16.0.
66
77
| Message Type | Receive Support | Send Support | Notes |
88
| --- | --- | --- | --- |
99
| Text | Yes | Yes | |
1010
| Image | Yes | Yes | |
11-
| Voice | No | Yes | |
12-
| Video | No | Yes | |
13-
| File | No | Yes | |
11+
| Voice | Yes | Yes | Converted to wav on receive and opus on send |
12+
| Video | Yes | Yes | Converted to mp4 before sending |
13+
| File | Yes | Yes | |
14+
15+
When you receive a quoted (reply) message, AstrBot parses the quoted text, images, videos, and files.
16+
17+
In group chats, the bot responds to messages that @ mention it, @ all members (unless disabled), reply to it, or start with a wake prefix such as `/`.
1418

1519
Proactive message push: Supported.
1620

@@ -24,21 +28,21 @@ Lark supports two setup methods: one-click QR creation in AstrBot, or manually c
2428

2529
### Option 1: One-click QR Creation
2630

27-
AstrBot version requirement: >= 4.25.0.
31+
AstrBot version requirement: >= v4.25.0.
2832

2933
Open the AstrBot management panel, click `Platforms` in the left sidebar, click `Add Adapter`, and select `lark`.
3034

3135
Under `Creation Method`, select `One-click QR Creation`, choose the China or international edition as needed, then scan the QR code with the Lark mobile app and confirm. After creation succeeds, AstrBot automatically fills in the app's `app_id`, `app_secret`, and domain configuration.
3236

3337
> [!IMPORTANT]
34-
> After an app is created through QR scanning, group chats receive only messages that @ mention the bot or messages triggered by a wake prefix such as `/` by default. If you need the bot to receive all group messages, enable the additional permissions in the Lark Developer Console.
38+
> In group chats, Lark only pushes messages that @ mention the bot to AstrBot by default. If you need the bot to receive all group messages, enable the `im:message.group_msg` permission in the Lark Developer Console.
3539
>
3640
> Replace `<APP_ID>` in the URL below with your Lark app ID, then open it to jump to the permission enablement page:
3741
>
3842
> To find the App ID, go back to AstrBot's `Platforms` page, select the Lark bot you just created, and check `app_id` under `Connection settings`.
3943
>
4044
> ```text
41-
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,contact:user.base:readonly,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message:send,im:message,im:message:send_as_bot,im:resource:upload,im:resource,cardkit:card:write,im:message.group_at_msg:readonly,im:message.group_msg&op_from=openapi&token_type=tenant
45+
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,contact:user.base:readonly,im:message,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message.group_msg,im:message:send_as_bot,im:resource,cardkit:card:write&op_from=openapi&token_type=tenant
4246
> ```
4347
4448
After QR creation succeeds, continue checking the event subscription, permissions, version release, and group installation steps below.
@@ -74,9 +78,9 @@ Fill in the configuration fields as follows:
7478
7579
For the domain field, if you're using Lark China, keep the default value. If you're using Lark International, set it to `https://open.larksuite.com`. If you're using a self-hosted enterprise Lark instance, enter your Lark instance's domain.
7680
77-
For the subscription method, `socket` uses a long connection subscription approach, while `webhook` sends events to your developer server and requires a public server. Generally, `socket` is recommended. However, if you're using Lark International or a self-hosted Lark instance, choose `webhook`. The subsequent configuration steps will differ accordingly.
81+
For the subscription method, `socket` uses a long connection subscription approach, while `webhook` sends events to your developer server and requires a public server. Generally, `socket` is recommended, and both Lark China and Lark International support long connections. For a self-hosted Lark instance, choose `webhook` if long connections are unavailable. The subsequent configuration steps will differ accordingly.
7882
79-
If you selected the `webhook` method, navigate to the Lark Developer Console, click on "Events & Callbacks," then "Encryption Policy," and fill in the Encrypt Key. While not mandatory, AstrBot takes your data security seriously, so we strongly recommend setting this up. After filling it in, copy the `Encrypt Key` and `Verification Token` to the corresponding `encrypt_key` and `verification_token` fields in AstrBot's configuration.
83+
If you selected the `webhook` method, navigate to the Lark Developer Console, click on "Events & Callbacks," then "Encryption Policy," and fill in the Encrypt Key. While not mandatory, AstrBot takes your data security seriously, so we strongly recommend setting this up. After filling it in, copy the `Encrypt Key` and `Verification Token` into the corresponding `Encrypt Key` (`lark_encrypt_key`) and `Verification Token` (`lark_verification_token`) fields in AstrBot.
8084
8185
Click `Save`.
8286
@@ -111,16 +115,16 @@ Click to enable the following permissions.
111115
112116
Then click the `Save` button at the top.
113117
114-
Next, click on "Permission Management," click "Enable Permissions," and enter `im:message:send,im:message,im:message:send_as_bot`. Add the filtered permissions.
118+
Next, click on "Permission Management," click "Enable Permissions," and enter `im:message,im:message:send_as_bot`. Add the filtered permissions.
115119
116-
Enter `im:resource:upload,im:resource` again to enable image upload permissions.
120+
Enter `im:resource` to enable uploading and downloading images, files, and other resources.
117121
118122
Enable `contact:contact.base:readonly` and `contact:user.base:readonly` so private-message senders can be shown by their display names.
119123
120124
If you want to use the bot in group chats, additionally enable `im:message.group_at_msg:readonly` and `im:message.group_msg`.
121125
122126
> [!TIP]
123-
> Apps created through one-click QR creation are suitable for @ mentions and wake-prefix triggers by default. To receive every group message, make sure `im:message.group_msg` is enabled. You can also use the permission URL above to quickly open the corresponding page.
127+
> An app created through one-click QR creation only receives group messages that @ mention the bot by default. To receive every group message, make sure `im:message.group_msg` is enabled. You can also use the permission URL above to quickly open the corresponding page.
124128
125129
If you want to use streaming output, additionally enable `Create and update cards (cardkit:card:write)`.
126130
@@ -146,6 +150,6 @@ Search for the bot you just created. For example, if you created the `AstrBot` b
146150
147151
## 🎉 All Done!
148152
149-
Send a `/help` command in the group, and the bot will respond.
153+
Mention the bot in the group and send a `/help` command, and the bot will respond.
150154
151155
![Success](https://files.astrbot.app/docs/source/images/lark/image-13.png)

‎docs/zh/dev/star/plugin.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@ async def on_message(self, event: AstrMessageEvent):
188188
| QQ 个人号(aiocqhttp) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
189189
| Telegram | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
190190
| QQ 官方接口 | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
191-
| 飞书 | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
191+
| 飞书 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
192192
| 企业微信 | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
193193
| 钉钉 | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
194194

‎docs/zh/platform/lark.md‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22

33
## 支持的基本消息类型
44

5-
> 版本 v4.15.0。
5+
> 版本 v4.16.0。
66
77
| 消息类型 | 是否支持接收 | 是否支持发送 | 备注 |
88
| --- | --- | --- | --- |
99
| 文本 | 是 | 是 | |
1010
| 图片 | 是 | 是 | |
11-
| 语音 | 否 | 是 | |
12-
| 视频 | 否 | 是 | |
13-
| 文件 | 否 | 是 | |
11+
| 语音 | 是 | 是 | 接收时转为 wav,发送时转为 opus |
12+
| 视频 | 是 | 是 | 发送时转为 mp4 |
13+
| 文件 | 是 | 是 | |
14+
15+
接收引用(回复)消息时,AstrBot 会解析被引用消息中的文本、图片、视频、文件等内容。
16+
17+
群聊中,机器人会响应 @ 机器人、@ 全体成员(未禁用时)、引用机器人消息以及以唤醒前缀(例如 `/`)开头的消息。
1418

1519
主动消息推送:支持。
1620

@@ -24,21 +28,21 @@
2428

2529
### 方式一:扫码一键创建
2630

27-
需要版本 >4.25.0。
31+
需要 AstrBot 版本 >= v4.25.0。
2832

29-
进入 AstrBot 管理面板,点击左边栏 `机器人`,然后点击 `+ 创建机器人`,选择 `lark(飞书)`。
33+
进入 AstrBot 管理面板,点击左边栏 `机器人`,然后点击 `创建机器人`,选择 `lark(飞书)`。
3034

3135
在 `选择创建方式` 中选择 `扫码一键创建`,按需选择国内版或海外版,然后使用手机飞书扫描页面中的二维码并确认。创建成功后,AstrBot 会自动写入该应用的 `app_id`、`app_secret` 和域名配置。
3236

3337
> [!IMPORTANT]
34-
> 通过扫码方式创建后,群聊下默认仅会接收 @ 机器人和通过唤醒前缀(例如 `/`)触发的消息。如果你希望机器人接收群聊中的所有消息,需要前往飞书开发者后台为应用开通额外权限。
38+
> 群聊中,飞书默认只会把 @ 机器人的消息推送给 AstrBot。如果你希望机器人接收群聊中的所有消息,需要前往飞书开发者后台为应用开通 `im:message.group_msg` 权限。
3539
>
3640
> 可以将下面链接中的 `<APP_ID>` 替换为你的飞书应用 App ID 后打开,一键进入权限开通页:
3741
>
3842
> App ID 获取方式:回到 AstrBot 的 `机器人` 页,选中刚刚创建的飞书机器人,在 `接入设置` 中查看 `app_id`。
3943
>
4044
> ```text
41-
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,contact:user.base:readonly,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message:send,im:message,im:message:send_as_bot,im:resource:upload,im:resource,cardkit:card:write,im:message.group_at_msg:readonly,im:message.group_msg&op_from=openapi&token_type=tenant
45+
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,contact:user.base:readonly,im:message,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message.group_msg,im:message:send_as_bot,im:resource,cardkit:card:write&op_from=openapi&token_type=tenant
4246
> ```
4347
4448
扫码创建完成后,建议继续检查后文的事件订阅、权限、版本发布和拉入群组步骤。
@@ -74,9 +78,9 @@
7478
7579
对于 domain,如果您使用国内版飞书,保持默认即可;如果您正在用国际版飞书,请设置为 `https://open.larksuite.com`;如果您使用企业自部署飞书,请填写您的飞书实例的域名。
7680
77-
对于订阅方式,`socket` 代表使用「长连接」订阅方式,`webhook` 代表「将事件发送至开发者服务器」的订阅方式,后者需要您拥有公网服务器。一般来说使用 `socket` 即可,如果您使用国际版飞书或者企业自部署飞书,请选择 `webhook`。相应地,接下来的配置也会有所不同。
81+
对于订阅方式,`socket` 代表使用「长连接」订阅方式,`webhook` 代表「将事件发送至开发者服务器」的订阅方式,后者需要您拥有公网服务器。一般来说使用 `socket` 即可,国内版和国际版飞书均支持长连接;如果您使用企业自部署飞书且长连接不可用,请选择 `webhook`。相应地,接下来的配置也会有所不同。
7882
79-
如果您选择了 `webhook` 方式,选择了之后,前往飞书的开发者后台,点击事件与回调,点击加密策略,填写 Encrypt Key。这不是必须的,AstrBot 十分注重你的数据安全,所以请务必填写。填写后复制 `Encrypt Key` 和 `Verification Token` 到 AstrBot 配置的 `encrypt_key` 和 `verification_token` 处。
83+
如果您选择了 `webhook` 方式,选择了之后,前往飞书的开发者后台,点击事件与回调,点击加密策略,填写 Encrypt Key。这不是必须的,AstrBot 十分注重你的数据安全,所以请务必填写。填写后将 `Encrypt Key` 和 `Verification Token` 复制到 AstrBot 配置中对应的 `Encrypt Key`(`lark_encrypt_key`)和 `Verification Token`(`lark_verification_token`)字段。
8084
8185
点击 `保存`。
8286
@@ -113,14 +117,14 @@
113117
114118
接下来,点击权限管理,点击开通权限,输入 `im:message,im:message:send_as_bot`。添加筛选到的权限。
115119
116-
再次输入 `im:resource:upload,im:resource` 开通上传图片相关的权限。
120+
再次输入 `im:resource` 开通上传、下载图片和文件等资源的权限。
117121
118122
开通 `contact:contact.base:readonly` 和 `contact:user.base:readonly`,用于读取私聊发送者的显示名。
119123
120124
如果需要在群聊里使用,请额外开通 `im:message.group_at_msg:readonly` 和 `im:message.group_msg` 权限。
121125
122126
> [!TIP]
123-
> 扫码一键创建的应用默认适合 @ 机器人和唤醒前缀触发。如果要接收群聊所有消息,请确认已经开通 `im:message.group_msg`。你也可以使用上文提供的权限开通链接快速进入对应页面。
127+
> 扫码一键创建的应用默认只能收到被 @ 的群聊消息。如果要接收群聊中的所有消息,请确认已经开通 `im:message.group_msg`。你也可以使用上文提供的权限开通链接快速进入对应页面。
124128
125129
如果需要使用流式输出,请额外开通 `创建与更新卡片(cardkit:card:write)` 权限。
126130
@@ -146,6 +150,6 @@
146150
147151
## 🎉 大功告成
148152
149-
在群内发送一个 `/help` 指令,机器人将做出响应。
153+
在群内 @ 机器人并发送一个 `/help` 指令,机器人将做出响应。
150154
151155
![成功](https://files.astrbot.app/docs/source/images/lark/image-13.png)

0 commit comments

Comments
 (0)