DingTalk Channel

DingTalk (钉钉) is a popular enterprise communication platform, especially in China. PicoClaw can integrate with DingTalk using internal application credentials.

Why DingTalk?

Enterprise Ready: Built for business communication and collaboration
Popular in China: Widely adopted by Chinese companies
Rich Features: Supports text, files, and rich media
Internal Apps: Secure integration via official API

Prerequisites

DingTalk account with organization admin access
Access to DingTalk Open Platform
PicoClaw installed with LLM provider configured
~20 minutes for setup

Setup Instructions

Access DingTalk Open Platform

Go to DingTalk Open Platform
Log in with your DingTalk account
Navigate to App Development → Internal Apps

You need organization admin permissions to create internal apps. Contact your DingTalk admin if you don’t have access.

Create an Internal App

Click Create Internal App
Fill in application details:
- App Name: e.g., “PicoClaw Assistant”
- App Description: Describe your AI assistant
- App Icon: Upload an icon (optional)
- Visibility: Choose who can see the app in your organization
Click Create

Configure App Permissions

After creating the app:

Go to Permissions Management
Enable required permissions:
- qyapi_message.read - Read messages
- qyapi_message.write - Send messages
- qyapi_user.read - Read user information (optional)
- qyapi_group.read - Read group info (if using groups)
Submit for admin approval if required
Wait for approval

Required permissions vary based on your use case. At minimum, you need message read/write permissions.

Get Credentials

In your app’s Credentials & Basic Information page:

Copy Client ID (also called AppKey)
Copy Client Secret (also called AppSecret)
Keep these secure

Client Secret grants full access to your app. Never share it publicly or commit to version control.

Configure PicoClaw

Edit ~/.picoclaw/config.json:

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

Replace:

client_id: Your app’s Client ID/AppKey
client_secret: Your app’s Client Secret/AppSecret
allow_from: DingTalk user IDs to allow (empty = allow all)

Start the Gateway

Run PicoClaw Gateway:

picoclaw gateway

Look for confirmation:

[INFO] dingtalk: Connected to DingTalk
[INFO] dingtalk: Listening for messages

Test Your Bot

Open DingTalk desktop or mobile app
Go to Workbench → Find your app
Open the app and send a message
The bot should respond with AI-generated replies

Configuration Options

Basic Configuration

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable DingTalk channel
`client_id`	string	Yes	Client ID/AppKey from DingTalk Open Platform
`client_secret`	string	Yes	Client Secret/AppSecret
`allow_from`	array	No	List of allowed DingTalk user IDs (empty = allow all)

Access Control

Allow specific users:

{
  "allow_from": ["user123", "user456"]
}

You can find user IDs in:

DingTalk admin console → User Management
From webhook payloads (check logs)
Using DingTalk API to query users

Allow everyone in organization:

{
  "allow_from": []
}

An empty allow_from array allows all users in your DingTalk organization. External users cannot access internal apps.

Features

Text Messages

Send and receive text messages with conversation context maintained per user.

Group Chats

Add the bot to DingTalk group chats:

Responds to messages based on configuration
Can be triggered by @mentions
Maintains separate context per group

Rich Messaging

DingTalk supports:

Markdown formatting
Interactive cards (ActionCards)
Links and buttons
File attachments

Depending on PicoClaw implementation, the bot may support sending formatted messages using DingTalk’s rich message APIs.

Organizational Integration

Internal apps can:

Access organizational structure
Query user information
Integrate with DingTalk workflows
Send notifications to specific users/groups

Troubleshooting

”Invalid Client ID or Client Secret”

Possible causes:

Incorrect credentials copied from platform
App not yet approved by admin
Credentials regenerated but not updated in config

Solution:

Verify credentials in DingTalk Open Platform
Check app status (must be active)
Ensure no extra spaces when copying credentials
Regenerate credentials if needed

”Permission denied” errors

Cause: App lacks required permissions Solution:

Go to DingTalk Open Platform → Your App → Permissions
Enable:
- Message read/write permissions
- User read permissions (if using allow_from)
Submit for admin approval if required
Wait for approval
Restart picoclaw gateway

Bot doesn’t respond

Check these:

Gateway running: picoclaw gateway must be active
Allow list: Verify user ID in allow_from (or use empty array)
App visibility: User must have access to the app in DingTalk
LLM configured: Test with picoclaw agent -m "test"
Permissions: Ensure app has message read/write permissions

User ID not recognized

Finding user IDs:

Admin Console: DingTalk admin → User Management
API: Use DingTalk user query API
Logs: Check Gateway logs for incoming message user IDs
Webhook: Inspect webhook payload structure

Connection issues

Possible causes:

Network connectivity to DingTalk servers
Firewall blocking outbound connections
Client Secret expired or revoked
App disabled by admin

Check:

Gateway logs for specific error messages
DingTalk Open Platform for app status
Network connectivity to oapi.dingtalk.com
Organization admin settings

Rate Limits

DingTalk enforces rate limits on internal apps:

API calls: Varies by organization size and app type
Message sending: Typically limited to prevent spam
Frequency: May have per-minute/per-hour limits

Check DingTalk Open Platform documentation for current rate limits. Limits may vary based on your organization’s plan.

Privacy & Security

Security Best Practices:

Never share Client Secret
Never commit credentials to repositories
Use allow_from for sensitive bots
Regenerate credentials if compromised
Monitor app usage in DingTalk admin console
Review audit logs regularly
Follow your organization’s security policies

Data Privacy

Internal apps can access:

Messages sent to the bot
User profiles (with permissions)
Organizational structure (with permissions)
Group information

Be aware of:

DingTalk/Alibaba privacy policies
Your organization’s data policies
Local data storage in PicoClaw workspace
LLM provider data logging
Chinese data protection laws (if applicable)

Complete Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "glm-4"
    }
  },
  "model_list": [
    {
      "model_name": "glm-4",
      "model": "zhipu/glm-4.7",
      "api_key": "your-zhipu-key"
    }
  ],
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "dingxxxxxxxxxxxxxx",
      "client_secret": "abcdef1234567890abcdef1234567890",
      "allow_from": []
    }
  }
}

Regional Considerations

China-Specific Notes:

DingTalk is primarily used in mainland China
Servers are hosted in China for compliance
Consider using Chinese LLM providers (Zhipu, Qwen, DeepSeek)
Be aware of content filtering requirements
Follow Chinese data protection regulations
International version exists but has limited features

Recommended LLM Providers

For DingTalk in China, use local LLM providers for better latency and compliance:

{
  "model_list": [
    {
      "model_name": "glm-4",
      "model": "zhipu/glm-4.7",
      "api_key": "your-zhipu-key"
    },
    {
      "model_name": "qwen",
      "model": "qwen/qwen-plus",
      "api_key": "your-qwen-key"
    },
    {
      "model_name": "deepseek",
      "model": "deepseek/deepseek-chat",
      "api_key": "your-deepseek-key"
    }
  ]
}

Next Steps

QQ Channel

Another popular Chinese platform

WeCom Channel

Enterprise WeChat alternative

Telegram Channel

International messaging platform

Configuration

Advanced configuration options

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

Why DingTalk?

Prerequisites

Setup Instructions

Configuration Options

Basic Configuration

Access Control

Features

Text Messages

Group Chats

Rich Messaging

Organizational Integration

Troubleshooting

”Invalid Client ID or Client Secret”

”Permission denied” errors

Bot doesn’t respond

User ID not recognized

Connection issues

Rate Limits

Privacy & Security

Data Privacy

Complete Example

Regional Considerations

Recommended LLM Providers

Next Steps

QQ Channel

WeCom Channel

Telegram Channel

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Why DingTalk?

​Prerequisites

​Setup Instructions

​Configuration Options

​Basic Configuration

​Access Control

​Features

​Text Messages

​Group Chats

​Rich Messaging

​Organizational Integration

​Troubleshooting

​”Invalid Client ID or Client Secret”

​”Permission denied” errors

​Bot doesn’t respond

​User ID not recognized

​Connection issues

​Rate Limits

​Privacy & Security

​Data Privacy

​Complete Example

​Regional Considerations

​Recommended LLM Providers

​Next Steps

QQ Channel

WeCom Channel

Telegram Channel

Configuration

Build docs developers (and LLMs) love

Why DingTalk?

Prerequisites

Setup Instructions

Configuration Options

Basic Configuration

Access Control

Features

Text Messages

Group Chats

Rich Messaging

Organizational Integration

Troubleshooting

”Invalid Client ID or Client Secret”

”Permission denied” errors

Bot doesn’t respond

User ID not recognized

Connection issues

Rate Limits

Privacy & Security

Data Privacy

Complete Example

Regional Considerations

Recommended LLM Providers

Next Steps