Blog / channel guide
Hermes Agent Feishu and Lark Setup Guide
Feishu and Lark give Hermes Agent a full enterprise workspace: direct messages, group chats, file and image attachments, and interactive approval cards for actions that need a human decision. The recommended connection mode is a long-lived outbound WebSocket, which means no public webhook endpoint is required.
- 01
Create the app in the developer console
Use the fastest available path to create the bot application, then make sure the bot capability is enabled for it before configuring anything else.
- 02
Store the app credentials as a secret
Copy the app credentials into the Hermes Agent deployment screen. Anyone holding the app secret can impersonate the bot, so treat it as a password.
- 03
Choose the connection mode
Prefer the long connection, which the assistant opens outbound and which needs no public endpoint. Choose the webhook mode only if your network requires Feishu or Lark to push events in.
- 04
Grant the message and media scopes
Add the scopes needed to receive messages, send as the bot, and read shared resources. Add identity scopes only when you need allowlist matching.
- 05
Subscribe to the message event
Register the incoming message event, and add the card action callback if you want approval buttons to work inside the chat.
- 06
Test a direct message, then a group mention
Direct messages should always get a reply. In group chats the assistant should answer only when the bot is mentioned.
Four-step path
How do you connect Hermes Agent to Feishu or Lark?
Five checkpoints: create the app, choose the connection mode, grant the message scopes, subscribe to the message event, then test a direct message and a group mention.
- Step 01
Create the app in the developer console
Use the fastest available path to create the bot application, then make sure the bot capability is enabled for it before configuring anything else.
- Step 02
Store the app credentials as a secret
Copy the app credentials into the Hermes Agent deployment screen. Anyone holding the app secret can impersonate the bot, so treat it as a password.
- Step 03
Choose the connection mode
Prefer the long connection, which the assistant opens outbound and which needs no public endpoint. Choose the webhook mode only if your network requires Feishu or Lark to push events in.
- Step 04
Grant the message and media scopes
Add the scopes needed to receive messages, send as the bot, and read shared resources. Add identity scopes only when you need allowlist matching.
- Step 05
Subscribe to the message event
Register the incoming message event, and add the card action callback if you want approval buttons to work inside the chat.
- Step 06
Test a direct message, then a group mention
Direct messages should always get a reply. In group chats the assistant should answer only when the bot is mentioned.
Should you use the long connection or a webhook?
Use the long connection unless you have a specific reason not to: the assistant opens it outbound, so there is no public endpoint to expose, secure, and monitor.
- Long connection: outbound only, no inbound firewall rule, no certificate to manage.
- Webhook: needs a reachable HTTPS endpoint and certificate lifecycle work.
- Choose one mode for events and keep the callback configuration consistent.
- Changing modes later is a configuration change, not a reinstall.
Which permissions does the bot need?
Start with the message permissions that let the assistant receive messages, send replies as the bot, and read shared images and files. Identity and reaction scopes are optional extras.
- Receive and read messages is the core scope; without it the bot is silent.
- Send as the bot is required before any reply can be delivered.
- Resource access is needed for images, audio, and file attachments.
- Reaction and identity scopes add approval and allowlist features.
How does the assistant behave in group chats?
Direct messages are always answered, while group chats require a mention. Session history in a shared chat is isolated per user by default.
Per-user isolation matters in a workspace where several people share a channel. Without it, one person's long conversation becomes everyone else's context, which inflates both cost and confusion.
How do interactive approvals work?
Sensitive actions can be approved from the chat itself through interactive cards, so a person can confirm or reject an action without leaving the conversation.
- The card action callback must be registered, or the buttons do nothing.
- Keep approval rights limited to the people who own the action.
- Treat an approval card as an audit record of who authorised what.
- Test the approval path before relying on it for anything destructive.
Does it matter whether you use Feishu or Lark?
The integration is the same, but the console you register the app in and the domain your tenant uses are different, so the credentials only work for the tenant that issued them.
- Register the app in the console that matches your organisation.
- Credentials from one tenant will not authorise the other.
- Workspace administrators may need to approve the app before use.
- Confirm which tenant the assistant belongs to before inviting it to channels.
Which primary sources support this page?
Product behavior is checked against the current deployment flow. These external links provide the upstream project or channel documentation used for setup details.
Direct answers
Frequently asked questions
Do I need a public webhook endpoint for Feishu or Lark?
No, not with the long connection mode. The assistant opens the connection outbound, so no inbound endpoint is required.
Can the assistant receive files and images?
Yes, once the resource scope is granted. Without it the assistant receives the message but cannot read the attached content.
Why does the bot stay silent in a group chat?
Group chats require a mention. Mention the bot, or confirm that the message event subscription and message scopes are both in place.
Can scheduled jobs deliver into Feishu or Lark?
Yes. Set a home chat for scheduled delivery so a daily briefing or alert lands in the right conversation.
Key takeaways
- Feishu and Lark give Hermes Agent a full enterprise workspace: direct messages, group chats, file and image attachments, and interactive approval cards for actions that need a human decision. The recommended connection mode is a long-lived outbound WebSocket, which means no public webhook endpoint is required.
- Start with one model, one channel, and one controlled test conversation.
- Use managed hosting when deployment speed matters more than operating the server yourself.
Continue the setup
Related Hermes Agent guides
Blog guide
How to Choose a Hermes Agent Channel
Compare Telegram, Discord, and WhatsApp for Hermes Agent deployment. Choose the best channel for support, daily briefings, and team operations.
Read nextBlog guide
Hermes Agent Microsoft Teams Setup for Work Accounts
Add Hermes Agent to Microsoft Teams with a bot registration, tenant admin consent, and a private chat test. Covers scopes, policies, and silent-bot fixes.
Read nextBlog guide
Hermes Agent Google Chat Setup with a Service Account
Connect Hermes Agent to Google Chat with a service account, Chat API app config, and a Workspace test space. Includes verification and silent-bot fixes.
Read nextBlog guide
Why Hermes Agent Is Not Sending or Receiving Messages
Troubleshoot Hermes Agent message failures across Telegram, Discord, and WhatsApp by checking channel access, runtime state, model keys, and logs.
Read next