Skip to main content
The DingTalk plugin provides a bot entry point and notification tools. For new message-entry setup, use the plugin integration and trigger docs first:

​
Capability overview

Current @xpert-ai/plugin-dingtalk capabilities:
  • receive DingTalk events through Stream mode or HTTP callback
  • handle direct chat messages
  • handle group messages when users mention the bot (@bot)
  • send text, Markdown, or card notifications through middleware/tools
  • update sent messages
  • recall OTO (human-bot) messages
  • list DingTalk users when contact permissions are granted
  1. Install @xpert-ai/plugin-dingtalk at the tenant level.
  2. Create a DingTalk Integration. Prefer DingTalk Stream mode (dingtalk_long).
  3. Add DingTalk Trigger to the target Digital Expert workflow.
  4. Select the DingTalk integration and publish the Digital Expert.
  5. Add the application bot to the target group or direct-chat scenario and test with an @bot message.
HTTP mode is still available when Stream mode cannot be used, but it requires a public HTTPS callback URL and matching callback Token/AES Key.

​
Required permissions

To read users for user selectors or dingtalk_list_users, grant:
  • qyapi_get_department_member (department member read permission)
Without this permission, DingTalk APIs can return insufficient permission errors such as 60011.
Client ID and DingTalk console AppKey are the same value.

​
Notification middleware/tools

Common DingTalk 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

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

​
Routing after publish

When used as a bot entry point, message routing is:
  1. Existing DingTalk conversation binding
  2. DingTalk trigger binding (integrationId -> xpertId)
If both are missing, DingTalk messages cannot find a target Digital Expert.

​
References