hermes-agent/website/docs/user-guide/messaging/dingtalk.md

sidebar_position	title	description
10	DingTalk	Set up Hermes Agent as a DingTalk bot using Stream Mode for real-time messaging

DingTalk Setup

Hermes connects to DingTalk through the dingtalk-stream SDK using Stream Mode — a WebSocket-based protocol that requires no public webhook URL. Messages arrive in real-time and responses are sent via the session webhook in markdown format.

DingTalk (钉钉) is Alibaba's enterprise communication platform with over 700 million registered users, making it the #1 business application in China. It combines messaging, video conferencing, task management, and workflow automation into a single platform used by millions of organizations.

:::info Dependencies The DingTalk adapter requires additional Python packages:

pip install dingtalk-stream httpx

httpx is already a core Hermes dependency, so in practice you only need dingtalk-stream. :::

---

Prerequisites

• DingTalk developer account — register at open-dev.dingtalk.com
• An application created on the DingTalk Open Platform with Robot (机器人) capability enabled

---

Step 1: Create a DingTalk Application

1. Go to open-dev.dingtalk.com and log in
2. Click Create Application (创建应用)
3. Fill in the application name and description
4. Under Capabilities (添加能力), enable Robot (机器人)
5. In the Robot configuration:
   • Enable Stream Mode (Stream 模式) — this is critical, as it eliminates the need for a public webhook URL
   • Set the bot name and avatar
6. Navigate to Credentials & Basic Info (凭证与基本信息) to find:
   • AppKey — this is your DINGTALK_CLIENT_ID
   • AppSecret — this is your DINGTALK_CLIENT_SECRET
7. Publish the application (发布)

:::tip Stream Mode is strongly recommended over the legacy HTTP webhook approach. It works behind firewalls, NATs, and requires no public IP or domain — the SDK maintains a persistent WebSocket connection to DingTalk's servers. :::

---

Step 2: Configure Hermes

The easiest way:

hermes gateway setup

Select DingTalk from the platform menu. The wizard will:

1. Check if dingtalk-stream is installed
2. Prompt for your AppKey (Client ID)
3. Prompt for your AppSecret (Client Secret)
4. Configure allowed users and access policies

Manual Configuration

Add to ~/.hermes/.env:

# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Security (recommended)
DINGTALK_ALLOWED_USERS=user1_staff_id,user2_staff_id    # Comma-separated DingTalk staff IDs

# Optional
DINGTALK_HOME_CHANNEL=user1_staff_id                     # Default delivery target for cron jobs

Then start the gateway:

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

---

Access Control

DM Access

DM access follows the same pattern as all other Hermes platforms:

1. DINGTALK_ALLOWED_USERS set → only those users can message
2. No allowlist set → unknown users get a DM pairing code (approve via hermes pairing approve dingtalk CODE)
3. DINGTALK_ALLOW_ALL_USERS=true → anyone can message (use with caution)

Group Access

In group chats, the bot responds when @mentioned. Group access follows the same rules — only allowed users can trigger the bot, even in groups.

---

Features

Stream Mode (No Webhook URL)

Unlike traditional bot platforms that require a publicly accessible webhook endpoint, DingTalk's Stream Mode uses a persistent WebSocket connection initiated from your side. This means:

• No public IP required — works behind firewalls and NATs
• No domain or SSL certificate needed — the SDK handles the connection
• Automatic reconnection — if the connection drops, the adapter reconnects with exponential backoff (2s → 5s → 10s → 30s → 60s)

Markdown Replies

Responses are sent in DingTalk's markdown format, which supports rich text formatting including headers, bold, italic, links, and code blocks.

DM and Group Chat

The adapter supports both:

• Direct Messages (1:1) — private conversations with the bot
• Group Chat — the bot responds when @mentioned in a group

Message Deduplication

The adapter tracks recently processed message IDs (up to 1,000 messages within a 5-minute window) to prevent duplicate processing if DingTalk redelivers a message.

Auto-Reconnection

If the WebSocket connection drops, the adapter automatically reconnects using exponential backoff:

• Retry intervals: 2s, 5s, 10s, 30s, 60s
• Reconnection is transparent — no manual intervention needed

---

Troubleshooting

Problem	Solution
"dingtalk-stream not installed"	Run pip install dingtalk-stream httpx in the Hermes environment
"DINGTALK_CLIENT_ID not set"	Set DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET in ~/.hermes/.env
Bot not responding	Verify the application is published on open-dev.dingtalk.com and Stream Mode is enabled
Connection keeps dropping	Check network connectivity. The adapter will auto-reconnect with backoff. Check logs for specific error messages.
Messages processed twice	This is rare — the deduplication window handles most cases. If persistent, check that only one gateway instance is running.
Bot responds to no one	Configure DINGTALK_ALLOWED_USERS, use DM pairing, or explicitly allow all users through gateway policy if you want broader access.
Group messages ignored	Ensure the bot is @mentioned in group chats. Only @mentions trigger the bot in groups.

---

Security

:::warning Always configure access controls. The bot has terminal access by default. Without DINGTALK_ALLOWED_USERS or DM pairing, the gateway denies all incoming messages as a safety measure. :::

• Use DM pairing or explicit allowlists for safe onboarding of new users
• Keep your AppSecret confidential — treat it like a password
• The DINGTALK_CLIENT_SECRET in ~/.hermes/.env should be readable only by the user running Hermes
• DingTalk's Stream Mode connection is encrypted via TLS

---

Environment Variables Reference

Variable	Required	Default	Description
DINGTALK_CLIENT_ID	Yes	—	DingTalk application AppKey
DINGTALK_CLIENT_SECRET	Yes	—	DingTalk application AppSecret
DINGTALK_ALLOWED_USERS	No	—	Comma-separated DingTalk staff IDs
DINGTALK_ALLOW_ALL_USERS	No	false	Allow all users (not recommended)
DINGTALK_HOME_CHANNEL	No	—	Default delivery target for cron jobs