docs(feishu): 200340 on card buttons is a callback-subscription gap, not a payload bug
Six issues (#10251, #10073, #13924, #38305, #25886, #8246) and four PRs proposed json.dumps()-ing CallBackCard.data. The lark_oapi SDK types `data` as Any and marshals the whole response with JSON.marshal(), so a dict already reaches Feishu as the nested object the card-callback doc shows in its response example; a string would nest a JSON *string* there instead. Feishu documents 200340 as "the application has not configured the card callback address or the configured request address is invalid" — the click is rejected before delivery (nothing reaches Hermes), which matches the reports (no gateway log, all four buttons identical). The docs told users to subscribe to `card.action.trigger` under Event Subscriptions; it lives under the separate Callback Configuration tab and needs its own long-connection/URL mode and a published app version. Spell out the four steps and map the sibling codes (200342/200343 = unreachable URL; 200672/200673 = our payload). Refs #10251
This commit is contained in:
@@ -82,8 +82,9 @@ In the Feishu developer console, go to **Permission Management** and add the fol
|
||||
In **Events and Callbacks**:
|
||||
|
||||
1. Set the connection mode to **Long Connection (WebSocket)** (recommended) or configure a webhook URL
|
||||
2. In the **Event Configuration** section, subscribe to:
|
||||
2. In the **Event Configuration** tab, subscribe to:
|
||||
- `im.message.receive_v1` — required for receiving messages
|
||||
3. In the **Callback Configuration** tab (a separate tab from events), set the same connection mode and add the `card.action.trigger` callback — required for the approval / update-prompt buttons. See [Required Feishu App Configuration](#required-feishu-app-configuration).
|
||||
|
||||
### Publish the App
|
||||
|
||||
@@ -291,21 +292,26 @@ This is also how **command approval** works — when the agent needs to run a da
|
||||
|
||||
### Required Feishu App Configuration
|
||||
|
||||
Interactive cards require **three** configuration steps in the Feishu Developer Console. Missing any of them causes error **200340** when users click card buttons.
|
||||
Interactive cards require **four** configuration steps in the Feishu Developer Console. Missing any of them causes error **200340** when users click card buttons.
|
||||
|
||||
1. **Subscribe to the card action event:**
|
||||
In **Event Subscriptions**, add `card.action.trigger` to your subscribed events.
|
||||
1. **Subscribe to the card action callback (not an event):**
|
||||
In **Development Configuration > Events and Callbacks**, open the **Callback Configuration** tab — it is separate from the **Event Configuration** tab where `im.message.receive_v1` lives — and add `card.action.trigger` under *Subscribed Callbacks*. Adding it as an event does not deliver button clicks.
|
||||
|
||||
2. **Enable the Interactive Card capability:**
|
||||
In **App Features > Bot**, ensure the **Interactive Card** toggle is enabled. This tells Feishu that your app can receive card action callbacks.
|
||||
2. **Set the callback delivery mode:**
|
||||
On the same tab choose **Long Connection** when Hermes runs in `websocket` mode (the Lark SDK receives the callback on the existing connection), or enter the request URL in webhook mode (the same endpoint as your event webhook, e.g. `https://your-server:8765/feishu/webhook`). Feishu must be able to reach and resolve that URL; otherwise clicks fail with 200342/200343.
|
||||
|
||||
3. **Configure the Card Request URL (webhook mode only):**
|
||||
In **App Features > Bot > Message Card Request URL**, set the URL to the same endpoint as your event webhook (e.g. `https://your-server:8765/feishu/webhook`). In WebSocket mode this is handled automatically by the SDK.
|
||||
3. **Enable the Interactive Card capability:**
|
||||
In **App Features > Bot**, ensure the **Interactive Card** toggle is enabled.
|
||||
|
||||
4. **Publish a new app version:**
|
||||
Callback changes only take effect after **Version Management > Create version** is published (and approved, for enterprise apps). Feishu's own description of 200340 is "the application has not configured the card callback address or the configured address is invalid … ensure that you have created and published the latest version of the app".
|
||||
|
||||
:::warning
|
||||
Without all three steps, Feishu will successfully *send* interactive cards (sending only requires `im:message:send` permission), but clicking any button will return error 200340. The card appears to work — the error only surfaces when a user interacts with it.
|
||||
Without all four steps, Feishu will successfully *send* interactive cards (sending only requires `im:message:send` permission), but clicking any button returns error 200340. The card appears to work — the error only surfaces when a user interacts with it, and the click never reaches Hermes (nothing is logged), because Feishu rejects it before delivering the callback.
|
||||
:::
|
||||
|
||||
Error codes 200672 / 200673 mean the callback *did* reach Hermes and Feishu rejected the response payload; those are adapter bugs — please file an issue with the gateway log.
|
||||
|
||||
## Document Comment Intelligent Reply
|
||||
|
||||
Beyond chat, the adapter can also answer `@`-mentions left on **Feishu/Lark documents**. When a user comments on a document (local text selection or whole-doc comment) and @-mentions the bot, Hermes reads the document plus the surrounding comment thread and posts an LLM reply inline on the thread.
|
||||
@@ -582,7 +588,8 @@ WebSocket and per-group ACL settings are configured via `config.yaml` under `pla
|
||||
| Bot identity not auto-detected | Usually a transient network issue reaching Feishu's bot info endpoint. Set `FEISHU_BOT_OPEN_ID` and `FEISHU_BOT_NAME` manually as a workaround. |
|
||||
| Peer bot messages still ignored after enabling `FEISHU_ALLOW_BOTS` | Hermes can't identify itself yet — set `FEISHU_BOT_OPEN_ID` (and `FEISHU_BOT_USER_ID` if your app uses `sender_id_type=user_id`). |
|
||||
| Peer bots show as `ou_xxxxxx` instead of by name | Grant the `application:bot.basic_info:read` scope. |
|
||||
| Error 200340 when clicking approval buttons | Enable **Interactive Card** capability and configure **Card Request URL** in the Feishu Developer Console. See [Required Feishu App Configuration](#required-feishu-app-configuration) above. |
|
||||
| Error 200340 (also seen as 220340) when clicking approval buttons | Feishu has no valid card callback for the published app version: add `card.action.trigger` under the **Callback Configuration** tab (not Event Configuration), pick Long Connection / the request URL, enable **Interactive Card**, then publish a new version. See [Required Feishu App Configuration](#required-feishu-app-configuration). The click never reaches Hermes, so nothing appears in `gateway.log`. |
|
||||
| Error 200342 / 200343 when clicking approval buttons | Webhook mode: Feishu cannot connect to / resolve the callback request URL. Fix the URL or switch to Long Connection. |
|
||||
| `Webhook rate limit exceeded` | More than 120 requests/minute from the same IP. This is usually a misconfiguration or loop. |
|
||||
|
||||
## Toolset
|
||||
|
||||
Reference in New Issue
Block a user