Skip to main content

DingTalk Integration Guide

This guide provides detailed instructions for configuring DingTalk IM channel integration in Wegent.

πŸ“‹ Table of Contents​

βœ… Prerequisites​

Before setting up DingTalk integration, ensure you have:

  • DingTalk Enterprise account with admin access
  • Access to DingTalk Open Platform
  • Wegent instance with admin privileges
  • At least one configured Agent (Team) in Wegent

πŸ”§ Step 1: Create DingTalk Application​

  1. Log in to DingTalk Open Platform
  2. Navigate to Application Development β†’ Enterprise Internal Application
  3. Click Create Application
  4. Fill in application details:
    • Application Name: Your bot name (e.g., "Wegent AI Assistant")
    • Application Description: Brief description of the bot's purpose
    • Application Icon: Upload an appropriate icon

πŸ” Step 2: Configure Application Permissions​

Enable the following permissions for your application:

Robot Permissions:

  • qyapi_robot_sendmsg - Send robot messages
  • qyapi_chat_manage - Manage group chats

AI Card Permissions (for streaming responses):

  • Card.Instance.Write - Create and update AI card instances
  • Card.Streaming.Write - Stream write AI card content

User Information Permissions:

  • Contact.User.Read - Read user information
  • Contact.User.mobile - Access user mobile (optional)

πŸ’‘ Note: AI Card permissions are required for streaming response effects. Without these permissions, the bot will not be able to use AI Card features and will fall back to plain text message mode.

πŸ“ Step 3: Get Application Credentials​

  1. In your application settings, navigate to Credentials and Basic Info
  2. Copy the following values:
    • Client ID (AppKey)
    • Client Secret (AppSecret)

⚠️ Security Note: Keep your Client Secret secure. Never share it or commit it to version control.

πŸ”„ Step 4: Enable Message Stream Mode​

  1. In application settings, go to Robot Configuration
  2. Enable Message Receiving Mode: Stream Mode
  3. This allows Wegent to receive messages via WebSocket without configuring callback URLs

βš™οΈ Step 5: Configure IM Channel in Wegent​

  1. Log in to Wegent as an administrator
  2. Navigate to Admin Panel β†’ IM Channels
  3. Click Add Channel
  4. Fill in the configuration:
FieldDescriptionExample
Channel NameDisplay name for this channel"DingTalk Bot"
Channel TypeSelect platformDingTalk
Client IDFrom Step 3dingxxxxxxxx
Client SecretFrom Step 3xxxxxxxxxxxxxxxx
Default AgentAgent to handle messagesSelect from list
Default ModelOverride model (optional)Leave empty to use agent's default
Enable AI CardUse streaming AI Cardβœ… Recommended
  1. Click Save to create the channel
  2. Toggle Enable to activate the channel

βœ”οΈ Step 6: Verify Connection​

  1. Check the channel status in the IM Channels list
  2. Status should show Connected (green indicator)
  3. View uptime and last error information if available

πŸ§ͺ Step 7: Test the Integration​

  1. Open DingTalk and find your bot
  2. Send a test message: "Hello"
  3. Verify you receive an AI response

🎨 DingTalk-Specific Features​

Group Chat Bot​

Add the bot to DingTalk group chats:

  1. In the group chat, click Group Settings β†’ Smart Group Assistant
  2. Click Add Robot
  3. Select your created robot
  4. The bot can now respond to @mentions in the group chat

Direct Message Bot​

Users can chat with the bot directly:

  1. Search for the bot name in DingTalk
  2. Click on the bot card
  3. Start the conversation

AI Card Streaming​

DingTalk AI Cards provide a rich streaming response experience:

  • Display content being generated in real-time
  • Support Markdown formatting
  • Code block syntax highlighting
  • Collapsible long content

❓ Troubleshooting​

Connection Issues​

Channel shows "Disconnected"​

Possible causes:

  1. Invalid Client ID or Client Secret
  2. Network connectivity issues
  3. DingTalk API service disruption

Solutions:

  1. Verify credentials in DingTalk Open Platform
  2. Check network connectivity from Wegent server
  3. Try restarting the channel
  4. Check DingTalk service status

Messages not being received​

Possible causes:

  1. Stream mode not enabled in DingTalk
  2. Robot permissions not configured
  3. Channel not enabled in Wegent

Solutions:

  1. Verify Stream Mode is enabled in DingTalk app settings
  2. Check all required permissions are granted
  3. Ensure channel is enabled (toggle is on)

Response Issues​

Bot not responding​

Possible causes:

  1. Default Agent not configured
  2. Agent has no model assigned
  3. Rate limiting

Solutions:

  1. Verify a default Agent is selected for the channel
  2. Ensure the Agent has a working model configuration
  3. Check for rate limit errors in channel status

Slow or incomplete responses​

Possible causes:

  1. AI Card streaming issues
  2. Network latency
  3. Large response content

Solutions:

  1. Try disabling AI Card streaming temporarily
  2. Check network connectivity
  3. The system will fall back to sync mode if streaming fails

User Issues​

User not recognized​

Possible causes:

  1. User mapping configuration issues
  2. DingTalk user info not accessible

Solutions:

  1. Check user permissions in DingTalk app
  2. Verify user mapping configuration
  3. Contact administrator for enterprise user mapping

User creation failed​

Possible causes:

  1. Missing Contact.User.Read permission
  2. Failed to retrieve DingTalk staff ID

Solutions:

  1. Ensure permission to read user information is granted
  2. Re-authorize application permissions
  3. Check if DingTalk user is in the enterprise organization

πŸ”— Related Resources​

Wegent Documentation​

DingTalk Official Resources​

Get Help​

Connect your AI agents to DingTalk and empower your team! πŸš€