DingTalk Bot Setup Guide

🤖 DingTalk Bot Setup Guide

This guide covers how to create and configure a DingTalk bot to connect with AionUi, enabling AI assistant interactions through DingTalk.

English | 简体中文

🎯 Overview

AionUi supports DingTalk bot integration, allowing you to chat with your AI assistant directly through DingTalk. This guide will walk you through:

1. Creating a bot application on DingTalk Open Platform
2. Configuring credentials in AionUi
3. Authorizing users and starting conversations

---

📋 Prerequisites

• A DingTalk account with developer access
• AionUi application installed
• Basic understanding of bot applications

---

🚀 Step-by-Step Setup

Step 1: Create a Bot Application on DingTalk Open Platform

1. Visit DingTalk Open Platform

   • Go to DingTalk Open Platform
   • Log in with your DingTalk account

2. Create Application

   • After logging in, navigate to Application Development (应用开发) → Enterprise Internal Development (企业内部开发)
   • Click "Create Application" (创建应用)
   • Select Robot (机器人) as the application type

   

3. Get Your Credentials

   • In the application details page, find the Development Information (开发信息) or Credentials (凭证) section
   • Copy your AppKey (this is your Client ID)
   • Copy your AppSecret (this is your Client Secret)
   • ⚠️ Important: Keep these credentials secure and never share them publicly

4. Configure Message Reception Mode

   • In the application configuration, find "Message Reception Mode" (消息接收模式) or "Connection Mode" (连接方式)
   • Select Stream Mode (流式连接)
   • This enables real-time message streaming and supports AI Card streaming responses

   

5. Publish DingTalk Bot

   • After completing the configuration, click the Publish (发布) button to publish the bot

   

---

Step 2: Enable Enterprise Application Permissions

⚠️ Note: Non-admin users need admin approval to enable permissions

In the application details page, go to "Permission Management" (权限管理) or "API Permissions" (接口权限) section, and enable the following permissions one by one:

• Card.Streaming.Write - AI Card streaming write permission
• Card.Instance.Write - AI Card instance write permission
• qyapi_robot_sendmsg - Robot send message permission

These permissions are required for the bot to function properly.

---

Step 3: Publish Enterprise Application

1. Configure Visibility Scope

   • In the application details page, find "Visibility Scope" (可见范围) or "Usage Scope" (使用范围) settings
   • Set visibility to "Only Me" (仅自己) for testing, or select users/departments who need access

2. Enable Robot

   • Ensure the robot feature is enabled
   • Check basic information like robot name and avatar

3. Publish Application

   • Click the Publish (发布) button
   • Confirm the publishing information is correct
   • Wait for the publishing to complete

   

💡 Tip: After publishing, the bot can be searched and used by users. For testing purposes, you can set it to "Only Me" first.

---

Step 4: Configure AionUi

1. Open AionUi Settings

   • Launch AionUi application
   • Go to Settings (设置)
   • Navigate to WebUI (Channel) section
   • Find the "DingTalk" channel card
   • Expand the DingTalk configuration

   

2. Enter Credentials

   • In the DingTalk configuration form:
     • Client ID: Paste the AppKey you obtained in Step 1
     • Client Secret: Paste the AppSecret you obtained in Step 1
   • Click "Test & Connect" to verify the connection

   

3. Configure Agent and Model

   • Select the Agent you want to use for DingTalk conversations
   • Choose the Model for the selected agent
   • These settings determine which AI assistant will respond to DingTalk messages

   

---

Step 5: Authorize Users

After successfully connecting, you need to authorize users who can interact with the bot:

1. Find Your Bot in DingTalk

   • Open DingTalk application
   • Search for your bot by name
   • Start a conversation with the bot

2. Send a Test Message

   • Send any message to the bot (e.g., "Hello")
   • This will trigger a pairing request

   

3. Approve the Pairing Request

   • In AionUi, go back to Settings → Channels → DingTalk
   • You should see a "Pending Pairings" section
   • Click "Approve" to authorize the user
   • The user will now be able to chat with the AI assistant through DingTalk

   

4. Start Chatting

   • Once approved, users can send messages to the bot
   • The AI assistant will respond in real-time using DingTalk's AI Card streaming feature

   

---

🔧 Troubleshooting

Connection Issues

Problem: Cannot connect to DingTalk API

• Solution:
  • Verify your Client ID and Client Secret are correct
  • Check your internet connection
  • Ensure the bot application is properly configured on DingTalk Open Platform

Authorization Issues

Problem: Users cannot send messages to the bot

• Solution:
  • Make sure the user has been approved in AionUi settings
  • Verify the bot is enabled in AionUi
  • Check that the bot application is published/activated on DingTalk Open Platform

Message Not Received

Problem: Bot doesn't respond to messages

• Solution:
  • Check the connection status in AionUi settings
  • Verify the agent and model are properly configured
  • Ensure the bot has the necessary permissions on DingTalk Open Platform (especially the three permissions mentioned in Step 2)
  • Confirm the bot application has been successfully published (Step 3)

---

📚 Additional Resources

• DingTalk Open Platform Documentation
• AionUi Configuration Guides
• AionUi FAQ

---

🔗 Quick Links

• 🚀 Getting Started
• ⚙️ LLM Configuration
• 🤖 Multi-Agent Mode Setup
• 💻 WebUI Configuration
• ❓ FAQ

---

Need help? Check the FAQ or open an issue on GitHub.