mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-15 17:30:13 +08:00
feat: supports scan QR code to configure feishu / lark (#8191)
* feat(lark): implement app registration and bot info retrieval - Add app registration functionality for Lark and Feishu platforms, including endpoints and request handling. - Introduce polling mechanism for app registration status. - Create bot info retrieval functionality to fetch bot details after successful registration. - Enhance dashboard with new UI components for one-click QR setup and manual setup options. - Update internationalization files to support new features and actions. - Add unit tests for app registration endpoint resolution and data handling. * feat(weixin_oc): add WeChat login registration and QR code handling
This commit is contained in:
Weilong Liao
@@ -20,6 +20,31 @@ The Lark client version must be >= 7.20. Lower versions only display the title a
|
||||
|
||||
## Creating a Bot
|
||||
|
||||
Lark supports two setup methods: one-click QR creation in AstrBot, or manually creating a custom enterprise app in the Lark Developer Console.
|
||||
|
||||
### Option 1: One-click QR Creation
|
||||
|
||||
AstrBot version requirement: >= 4.25.0.
|
||||
|
||||
Open the AstrBot management panel, click `Bots` in the left sidebar, click `+ Create Bot`, and select `lark`.
|
||||
|
||||
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.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 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.
|
||||
>
|
||||
> Replace `<APP_ID>` in the URL below with your Lark app ID, then open it to jump to the permission enablement page:
|
||||
>
|
||||
> To find the App ID, go back to AstrBot's `Bots` page, find the Lark bot you just created, click `Edit`, and check the dialog that opens.
|
||||
>
|
||||
> ```text
|
||||
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.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
|
||||
> ```
|
||||
|
||||
After QR creation succeeds, continue checking the event subscription, permissions, version release, and group installation steps below.
|
||||
|
||||
### Option 2: Manual Creation
|
||||
|
||||
Navigate to the [Developer Console](https://open.feishu.cn/app) and create a custom enterprise application.
|
||||
|
||||
|
||||
@@ -38,6 +63,7 @@ Click on "Credentials & Basic Info" to obtain your app_id and app_secret.
|
||||
2. Click on `Bots` in the left sidebar
|
||||
3. In the right panel, click `+ Create Bot`
|
||||
4. Select `lark`
|
||||
5. If you want AstrBot to create the app for you, select `One-click QR Creation` and complete the scan. If you already created the app yourself, select `Manual Creation`
|
||||
|
||||
Fill in the configuration fields as follows:
|
||||
|
||||
@@ -45,7 +71,6 @@ Fill in the configuration fields as follows:
|
||||
- Enable: Check this option
|
||||
- app_id: The app_id you obtained earlier
|
||||
- app_secret: The app_secret you obtained earlier
|
||||
- Bot name: Your Lark bot's name
|
||||
|
||||
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.
|
||||
|
||||
@@ -92,6 +117,11 @@ Next, click on "Permission Management," click "Enable Permissions," and enter `i
|
||||
|
||||
Enter `im:resource:upload,im:resource` again to enable image upload permissions.
|
||||
|
||||
If you want to use the bot in group chats, additionally enable `im:message.group_at_msg:readonly` and `im:message.group_msg`.
|
||||
|
||||
> [!TIP]
|
||||
> 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.
|
||||
|
||||
If you want to use streaming output, additionally enable `Create and update cards (cardkit:card:write)`.
|
||||
|
||||
The final set of permissions should look like this:
|
||||
|
||||
@@ -25,6 +25,8 @@ AstrBot supports connecting a personal WeChat account through the `Personal WeCh
|
||||
2. Click `Bots` in the left sidebar.
|
||||
3. Click `+ Create Bot` in the upper-right corner.
|
||||
4. Select `Personal WeChat`.
|
||||
5. The login QR code is shown directly. Scan it with WeChat on your phone and confirm the login inside WeChat.
|
||||
6. After login succeeds, click `Save`.
|
||||
|
||||
## Configuration Notes
|
||||
|
||||
@@ -44,15 +46,12 @@ Leave the remaining options at their default values unless you explicitly know y
|
||||
|
||||
## QR Login
|
||||
|
||||
1. Fill in the configuration and click `Save`.
|
||||
2. Return to the bot list. AstrBot will automatically request a login QR code from WeChat.
|
||||
3. On the bot card, click `View QR Code` to open the QR dialog.
|
||||
4. Scan it with WeChat on your phone, then confirm the login inside WeChat.
|
||||
After you select `Personal WeChat`, AstrBot automatically requests a login QR code from WeChat and shows it directly in the create-bot dialog. Scan it with WeChat on your phone and confirm the login. When the QR area shows the login-success state, click `Save` to finish creating the bot.
|
||||
|
||||
After login succeeds, AstrBot will automatically persist the login state. On later restarts, if the session is still valid, you usually do not need to scan again.
|
||||
After login succeeds and the bot is saved, AstrBot will automatically persist the login state. On later restarts, if the session is still valid, you usually do not need to scan again.
|
||||
|
||||
> [!NOTE]
|
||||
> If the QR code expires, AstrBot will automatically request a new one. Please scan the refreshed QR code instead of the old one.
|
||||
> If the QR code expires, close and reopen the create-bot dialog, or select `Personal WeChat` again to request a new QR code.
|
||||
|
||||
## Verification
|
||||
|
||||
|
||||
@@ -20,6 +20,31 @@
|
||||
|
||||
## 创建机器人
|
||||
|
||||
飞书（Lark）支持两种创建方式：在 AstrBot 中扫码一键创建，或在飞书开发者后台手动创建企业自建应用。
|
||||
|
||||
### 方式一：扫码一键创建
|
||||
|
||||
需要版本 >4.25.0。
|
||||
|
||||
进入 AstrBot 管理面板，点击左边栏 `机器人`，然后点击 `+ 创建机器人`，选择 `lark(飞书)`。
|
||||
|
||||
在 `选择创建方式` 中选择 `扫码一键创建`，按需选择国内版或海外版，然后使用手机飞书扫描页面中的二维码并确认。创建成功后，AstrBot 会自动写入该应用的 `app_id`、`app_secret` 和域名配置。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 通过扫码方式创建后，群聊下默认仅会接收 @ 机器人和通过唤醒前缀（例如 `/`）触发的消息。如果你希望机器人接收群聊中的所有消息，需要前往飞书开发者后台为应用开通额外权限。
|
||||
>
|
||||
> 可以将下面链接中的 `<APP_ID>` 替换为你的飞书应用 App ID 后打开，一键进入权限开通页：
|
||||
>
|
||||
> App ID 获取方式：回到 AstrBot 的 `机器人` 页，找到刚刚创建的飞书机器人，点击 `编辑`，弹出的对话框中可以看到 App ID。
|
||||
>
|
||||
> ```text
|
||||
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.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
|
||||
> ```
|
||||
|
||||
扫码创建完成后，建议继续检查后文的事件订阅、权限、版本发布和拉入群组步骤。
|
||||
|
||||
### 方式二：手动创建
|
||||
|
||||
前往 [开发者后台](https://open.feishu.cn/app) ，创建企业自建应用。
|
||||
|
||||
|
||||
@@ -38,6 +63,7 @@
|
||||
2. 点击左边栏 `机器人`
|
||||
3. 然后在右边的界面中，点击 `+ 创建机器人`
|
||||
4. 选择 `lark(飞书)`
|
||||
5. 如果使用扫码一键创建，选择 `扫码一键创建` 并完成扫码；如果使用自己创建的企业自建应用，选择 `手动创建`
|
||||
|
||||
弹出的配置项填写：
|
||||
|
||||
@@ -45,7 +71,6 @@
|
||||
- 启用(enable): 勾选。
|
||||
- app_id: 获取的 app_id
|
||||
- app_secret: 获取的 app_secret
|
||||
- 飞书机器人的名字
|
||||
|
||||
对于 domain，如果您使用国内版飞书，保持默认即可；如果您正在用国际版飞书，请设置为 `https://open.larksuite.com`；如果您使用企业自部署飞书，请填写您的飞书实例的域名。
|
||||
|
||||
@@ -94,6 +119,9 @@
|
||||
|
||||
如果需要在群聊里使用，请额外开通 `im:message.group_at_msg:readonly` 和 `im:message.group_msg` 权限。
|
||||
|
||||
> [!TIP]
|
||||
> 扫码一键创建的应用默认适合 @ 机器人和唤醒前缀触发。如果要接收群聊所有消息，请确认已经开通 `im:message.group_msg`。你也可以使用上文提供的权限开通链接快速进入对应页面。
|
||||
|
||||
如果需要使用流式输出，请额外开通 `创建与更新卡片(cardkit:card:write)` 权限。
|
||||
|
||||
最终开通的权限如下图：
|
||||
|
||||
@@ -23,6 +23,8 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
|
||||
2. 点击左侧栏 `机器人`。
|
||||
3. 点击右上角 `+ 创建机器人`。
|
||||
4. 选择 `个人微信`。
|
||||
5. 页面会直接显示登录二维码，使用手机微信扫码，并在微信内确认登录。
|
||||
6. 登录成功后点击 `保存`。
|
||||
|
||||
## 配置项说明
|
||||
|
||||
@@ -42,18 +44,12 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
|
||||
|
||||
## 扫码登录
|
||||
|
||||
1. 填好配置后点击 `保存`。
|
||||
2. 返回机器人列表，AstrBot 会自动向微信接口申请登录二维码。
|
||||
3. 在**机器人卡片**中点击 “查看二维码” 按钮，会弹出二维码对话框。（点击保存之后可能需要等 5 到 10 秒左右才会出现这个按钮）
|
||||
4. 使用手机微信扫码，并在微信内确认登录。
|
||||
选择 `个人微信` 后，AstrBot 会自动向微信接口申请登录二维码，并直接显示在创建机器人弹窗中。使用手机微信扫码确认后，二维码会显示登录成功状态，此时点击 `保存` 即可完成创建。
|
||||
|
||||
|
||||
|
||||
登录成功后，AstrBot 会自动保存登录态。后续重启时，如果登录态仍有效，通常不需要再次扫码。
|
||||
登录成功并保存后，AstrBot 会自动保存登录态。后续重启时，如果登录态仍有效，通常不需要再次扫码。
|
||||
|
||||
> [!NOTE]
|
||||
> 1. 如果二维码过期，AstrBot 会自动重新申请新的二维码。刷新后请使用新的二维码重新扫码。
|
||||
> 2. 如果 WebUI 没看到 “查看二维码” 按钮，可以前往终端或者 WebUI 控制台，找到 `请使用手机微信扫码登录，二维码有效期 5 分钟，过期后会自动刷新。` 对应的日志，附近会显示二维码扫码链接和终端直接输出的二维码，直选择一种方式扫码即可。
|
||||
> 如果二维码过期，请关闭并重新打开创建机器人弹窗，或重新选择 `个人微信` 以获取新的二维码。
|
||||
|
||||
## 验证
|
||||
|
||||
@@ -77,4 +73,3 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
|
||||
|
||||
- 该适配器通过扫码登录个人微信，接入方式与微信公众号、企业微信不同。
|
||||
- 不需要配置公网回调地址，也不需要开启统一 Webhook 模式。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user