> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# DingTalk

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

* [DingTalk Integration](../../plugin/integration/dingtalk-integration/)
* [DingTalk Trigger](../../plugin/trigger/dingtalk-trigger/)

## 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

## Recommended setup

1. Install `@xpert-ai/plugin-dingtalk` at the tenant level.
2. Create a [DingTalk Integration](../../plugin/integration/dingtalk-integration/). Prefer **DingTalk Stream mode** (`dingtalk_long`).
3. Add [DingTalk Trigger](../../plugin/trigger/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`.

<Tip>
  `Client ID` and DingTalk console `AppKey` are the same value.
</Tip>

## 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

* [DingTalk Open Platform](https://open.dingtalk.com/document/dingstart)
* [Robot Development Overview](https://open.dingtalk.com/document/development/development-robot-overview)
* [Robot Sends Group Message](https://open.dingtalk.com/document/development/the-robot-sends-a-group-message)
* [Robot Sends Interactive Card](https://open.dingtalk.com/document/development/robots-send-interactive-cards)