Skip to main content
DingTalk integration uses Stream Mode, eliminating the need for a public IP or webhook configuration.

​
Features

  • ✅ Stream Mode (no public IP required)
  • ✅ AppKey and AppSecret authentication
  • ✅ Staff ID-based access control
  • ✅ Simple setup and configuration

​
Setup

1

Create a DingTalk bot

  1. Visit DingTalk Open Platform
  2. Click Create Application (创建应用)
  3. Choose Internal Application (企业内部应用)
  4. Fill in application name and description
2

Add Robot capability

  1. In your application, go to Application Functions (应用功能)
  2. Click Add Robot (添加机器人)
  3. Toggle Stream Mode (长连接模式) to ON
  4. Save configuration
Stream Mode requires nanobot to be running to receive messages
3

Configure permissions

In Permissions (权限管理):Add necessary permissions:
  • Send messages to users
  • Receive messages from users
  • Access basic user info (optional)
Apply and wait for approval if required.
4

Get credentials

In Credentials & Basic Info (凭证与基础信息):Copy:
  • AppKey (also called Client ID)
  • AppSecret (also called Client Secret)
5

Publish the app

  1. Go to Version Management (版本管理)
  2. Create a version and submit for review
  3. Or publish to internal organization only
6

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APP_KEY",
      "clientSecret": "YOUR_APP_SECRET",
      "allowFrom": ["YOUR_STAFF_ID"]
    }
  }
}
7

Start the gateway

nanobot gateway
You should see:
DingTalk channel connected via Stream Mode
8

Find your Staff ID

  1. Message your bot in DingTalk
  2. Check nanobot logs — it will display the sender’s Staff ID
  3. Copy the Staff ID and add it to allowFrom in config
  4. Restart gateway if needed
Alternatively, use ["*"] to allow all users (not recommended for production).

​
Configuration Options

​
enabled
boolean
required
Enable the DingTalk channel
​
clientId
string
required
AppKey (Client ID) from DingTalk Open Platform
​
clientSecret
string
required
AppSecret (Client Secret) from DingTalk Open Platform
​
allowFrom
array
required
List of DingTalk Staff IDs allowed to interact with the botExamples:
  • Single user: ["123456789"]
  • Multiple users: ["123456789", "987654321"]
  • All users: ["*"] (not recommended for production)
Find Staff IDs in nanobot logs when users message the bot

​
Stream Mode vs Webhook

DingTalk supports two ways to receive events:
  • ✅ No public IP required
  • ✅ No SSL certificate needed
  • ✅ Works behind firewall/NAT
  • ✅ Simpler setup
  • This is what nanobot uses by default

​
Webhook Mode

  • ❌ Requires public IP
  • ❌ Requires HTTPS with valid certificate
  • ❌ More complex setup
  • Only use if you have specific webhook requirements

​
Troubleshooting

  1. Check Stream Mode: Verify Stream Mode is enabled in robot settings
  2. Check Staff ID: Ensure your Staff ID is in allowFrom
  3. Check permissions: Verify all required permissions are approved
  4. Check app status: App must be published (at least to internal org)
  5. Check logs: Run nanobot gateway -v for detailed logs
  1. Verify AppKey (clientId) and AppSecret (clientSecret) are correct
  2. Check internet connectivity
  3. Ensure no firewall blocks Stream Mode connections
  4. Try restarting gateway: nanobot gateway
  5. Check DingTalk Open Platform status
If you see permission errors:
  1. Go to DingTalk Open Platform → Your App → Permissions
  2. Verify all required permissions are added and approved
  3. Some permissions require admin approval
  4. Wait for approval, then restart gateway
To get your Staff ID:
  1. Temporarily set allowFrom: ["*"]
  2. Restart gateway
  3. Send a message to the bot
  4. Check logs — Staff ID will be displayed
  5. Copy the Staff ID and add it to allowFrom
  6. Remove "*" and restart gateway
If messages aren’t received:
  1. Go to Version Management in DingTalk Open Platform
  2. Ensure app is published (even just to internal users)
  3. Check app status is “Active” or “Online”
  4. Restart gateway after publishing

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "dingabcdef123456",
      "clientSecret": "abcdefghijklmnopqrstuvwxyz123456",
      "allowFrom": ["123456789"]
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us