Skip to main content
With DingTalk integration, Xpert can receive messages from DingTalk private chats and group chats, then send expert responses back to DingTalk.

​
Capability Overview

Current @xpert-ai/plugin-dingtalk capabilities:
  • Receive DingTalk events via HTTP callback
  • Handle private chat messages
  • Handle group messages when users mention the bot (@bot)
  • Send text/Markdown/card notifications via middleware
  • Update sent messages via middleware
  • Recall OTO (human-bot) messages via middleware
Current limitations:
  • HTTP callback only (no Stream mode)
  • In groups, only @bot messages are processed
  • Recall currently applies to OTO messages only
  • Group list APIs are not stable across tenants; do not rely on automatic group discovery

​
Prerequisites

Before setup, prepare:
  1. A DingTalk enterprise account with app management permission
  2. An internal enterprise app with robot capability enabled
  3. A public Xpert service URL
  4. Callback security values (callbackToken, callbackAesKey)

​
Required Permissions

To read users (for user selector or dingtalk_list_users), you must grant:
  • qyapi_get_department_member (department member read permission)
Without this permission, DingTalk APIs return insufficient permission errors (for example 60011).

​
Create DingTalk Integration in Xpert

Go to Settings -> System Integrations and create a provider of type DingTalk.

​
Required fields

FieldDescription
Client ID (AppKey)DingTalk AppKey (same as Client ID)
Client SecretDingTalk app secret
Enable HTTP CallbackMust be enabled in current version
Callback TokenSignature verification token
Callback AES KeyUsed to decrypt callback payload
FieldDescription
Robot CodeNeeded for proactive send/update/recall operations
XpertFallback target when trigger binding is not hit
Preferred Languagezh-Hans or en
:::tip Client ID and DingTalk AppKey are the same value. :::

​
Configure DingTalk Callback

After saving integration, you can get callback info from system integration test: 
POST /api/dingtalk/webhook/:integrationId
Example: 
https://<your-domain>/api/dingtalk/webhook/<integrationId>
Recommended DingTalk console setup:
  1. Use this public callback URL in event/callback settings.
  2. Keep DingTalk token/aes_key consistent with Xpert integration config.
  3. Use HTTP push mode.

​
Build an Auto-Reply Bot (MyCoder Scenario)

  1. Create and validate a DingTalk integration in Xpert.
  2. Add DingTalk Trigger to target expert workflow and select that integration.
  3. Publish the expert.
  4. Add the application bot to target group.
  5. Send @bot message in the group for verification.
Routing priority after publish:
  1. Existing conversation binding
  2. DingTalk trigger binding (integrationId -> xpertId)
  3. Integration-level fallback xpertId

​
DingTalk Notify Middleware

Common tools:
  • dingtalk_send_text_notification
  • dingtalk_send_rich_notification
  • dingtalk_update_message
  • dingtalk_recall_message
  • dingtalk_list_users
dingtalk_send_rich_notification supports:
  • markdown
  • interactive
  • template

​
Recipient Configuration

Middleware resolves target by recipient_type + recipient_id. Common recipient_type values:
  • user_id
  • open_id
  • chat_id
Best practices:
  • For user notifications, prefer stable user identifiers (open_id or mapped user_id).
  • For group notifications, use chat_id (openConversationId).
  • recipient_id can use runtime variable (for example {{state.dingtalkRecipientId}}).

​
References