Connect Hermes to DingTalk with Stream Mode

Hermes can operate as a DingTalk chatbot in direct messages and group chats. The recommended Stream Mode opens a long-lived outbound WebSocket from the Hermes host, so the deployment does not need a public webhook, public IP, or inbound firewall rule.

Choose the conversation boundary

Direct messages receive a dedicated session and do not require an @mention. In groups, mention gating prevents the bot from answering every conversation. Keep group_sessions_per_user: true when several people share a group: each person then gets separate context instead of inheriting another member's transcript.

Use hermes gateway setup and select DingTalk. The wizard supports QR authorization or manual client credentials. Install the DingTalk extras if the adapter reports missing packages, then record an explicit allowed-user policy. Optional AI Cards can stream structured replies; plain Markdown remains the simpler baseline.

Setup checklist

• Create or authorize a DingTalk robot with Stream Mode enabled.
• Install the DingTalk adapter dependencies.
• Configure an explicit user allowlist.
• Keep per-user group sessions unless shared context is intentional.
• Require mentions in normal group conversations.
• Enable AI Cards only after the plain reply path works.

Pitfalls

A connected stream does not prove the sender is authorized. Intersecting an environment allowlist with a config allowlist can unintentionally deny everyone. A stale session webhook cannot deliver a delayed reply; send a fresh message before diagnosing credentials. Reconnection loops usually point to invalid app credentials, a disabled robot, or blocked outbound WebSockets.

Verification steps

1. Start the gateway and confirm the DingTalk stream connects.
2. Send one DM from an allowed user and verify one reply.
3. Post an unmentioned group message and confirm Hermes stays quiet.
4. Mention Hermes from two users and confirm their context remains isolated.
5. Restart the gateway and verify automatic reconnection without duplicate replies.

Read the official DingTalk guide for current setup fields, display controls, media behavior, and troubleshooting.