Deploy a Feishu or Lark Bot with WebSocket Events

Hermes supports Feishu and Lark through an app with bot capabilities and event subscriptions. WebSocket long-connection mode is the simplest default because it avoids exposing a public webhook, while webhook mode remains available for environments that require it.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/feishu

Build the app around least privilege

Create the app in the appropriate Feishu or Lark developer console, enable its bot capability, and collect the App ID and App Secret. The official setup flow can guide app creation and configuration. Review each requested permission rather than accepting a broad template without understanding it.

Subscribe only to events that Hermes needs. Publish the app to the intended organization and test with a small user group before wider installation. Store the App Secret as a secret, not in a shared YAML file or troubleshooting screenshot.

Launch checklist

Create the Feishu or Lark app in the correct tenant.
Enable the bot capability.
Record the App ID and protect the App Secret.
Grant the documented required permissions only.
Subscribe to the required message and interaction events.
Select WebSocket mode unless a reviewed webhook architecture is required.
Run hermes gateway setup and select Feishu or Lark.
Configure sender and group access policy.
Publish the app to a limited test audience.

Operate the long connection

The adapter runs a WebSocket client and reconnects when the platform drops the connection. Monitor reconnect frequency and event lag rather than assuming automatic reconnection always means healthy service. A reconnect must not replay an event into duplicate agent work.

Interactive cards, reactions, media, and threaded conversations have distinct event shapes. Validate only the capabilities your workflow promises. For a basic assistant, reliable text and thread routing are more valuable than enabling every optional permission.

Common pitfalls

Creating the app in the wrong Feishu or Lark tenant.
Granting optional permissions without a feature that needs them.
Forgetting to publish the app after configuring events.
Mixing webhook and WebSocket assumptions during troubleshooting.
Treating an automatic reconnect as proof that no events were lost or duplicated.
Allowing every group member to invoke privileged tools.

Verification steps

Confirm the app is published to the intended test tenant and users.
Start the gateway and verify the WebSocket connection remains stable.
Send a direct message and a group mention from an authorized user.
Confirm replies return to the correct conversation and thread.
Test an unauthorized user or unapproved group.
Force one controlled reconnect and verify event processing resumes without duplicate output.
Review platform and gateway logs for denied scopes, expired credentials, event lag, and leaked secrets.