Connect a Feishu bot
Create a Feishu application, configure message delivery, connect Onevium, and verify a two-turn conversation.
ChannelsConnect a Feishu group to Onevium#
You will create a Feishu internal app, connect its bot to Onevium, and verify two messages in a test group. The walkthrough uses the mainland Feishu console; do not assume Lark credentials and endpoints are interchangeable.
Create the platform application#
- Open the Feishu developer console and create an internal application in the intended organization.
- In Add Features → Bot, enable the bot and set its name and icon.
- Open Credentials & Basic Info. Keep the App ID and App Secret for Onevium's credential fields.
- Prepare a test group. The application will need an available-user range that includes its test members.
Onevium receives events through a long connection; this setup does not need your own public callback server.
Configure messages, events, and cards#
In Permissions, add the capabilities you actually need:
| Capability | Permission |
|---|---|
| Receive human @mentions in groups | im:message.group_at_msg:readonly |
| Receive direct messages, if enabled | im:message.p2p_msg:readonly |
| Send bot replies | im:message:send_as_bot |
| Create/update streaming card entities | cardkit:card:write |
These identifiers correspond to the official receive-message event, send-message API, and card creation API. Grant requested permissions and complete any organization approval before testing.
In Events & Callbacks, select Use long connection to receive events. Add Receive message v2.0, event key im.message.receive_v1. If using card approval buttons, also configure the callback card.action.trigger. Save the configuration, create a version, and publish it to the test audience.
If the console says no long connection is available, complete the Onevium connection below, ensure it is running, then return to verify and save the subscription. Do not create a second application to solve a connection-state error.
Fill the Onevium connection#
Open Channels → New Channel, choose Single bot and Feishu. Enter App ID and App Secret, then click Register Credentials. Continue after the connection check succeeds.
| Field | First-test value |
|---|---|
| Bot Name | Docs helper |
| Description | Answer questions about the demo project |
| Model | A provider/model already working in ordinary chat |
| Working Directory | Select the demo project folder |
| Conversation Mode | Each person gets their own conversation |
| Chat Scope | Groups only |
| Auto-approve Actions | Ask before every action for the first test |
| Role Description | Optional; a short label for the bot's role |
| System Prompt | Use the example below |
You are the demo project's documentation helper.
Answer questions about explicitly named project files.
Before editing files or running commands, explain the intended action.
For the connection test, remember the test code within this conversation.
Save the bot and check its running status; use Start if stopped. Add the published bot to the Feishu test group. Keep Onevium and the computer running.
Check two replies#
Mention the bot with “The test code is alpha-27.” After its reply, mention it again and ask “What was the test code?” Expect alpha-27, with the execution visible in Onevium's corresponding chat.
For shared context, open that chat's Chat Settings → Conversation Mode, switch to Everyone shares one conversation, and repeat using two test users. This changes conversation sharing, not the platform's permission to read historical group messages.
Add only the extra capabilities you need#
| Additional workflow | What to configure |
|---|---|
| Direct messages | Add im:message.p2p_msg:readonly; allow DMs in Chat Scope and set the DM policy/allowed user IDs |
| Upload images or files | Add im:resource or the applicable upload permission; verify one attachment separately |
| Resolve member/chat names | Check contact:user.base:readonly and im:chat:readonly when those lookups are needed |
| Receive unmentioned group messages | Requires broader group-message permission such as im:message.group_msg, plus the chat's Passive Context setting |
The official upload API, user lookup, and chat lookup document these optional permissions. A basic group reply does not need document-writing or presentation-writing scopes.
Troubleshoot by stage#
- Register Credentials fails: confirm App ID and Secret belong to the same app; inspect the displayed network or token error.
- Running but no inbound messages: check
im.message.receive_v1, long-connection selection, published audience, group membership, and that the bot was mentioned. - Input arrives but no reply: check the model result, pending approval, and send permission.
- Card fails: check
cardkit:card:writeand the platform error. Onevium has a fallback message path; still verify that a readable final response arrived.
Next steps#
Use the channel overview for conversation scope and automations for scheduled delivery. Compare DingTalk if your team uses another platform.