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

# DingTalk

> Send Human Input requests to DingTalk as link messages: create the app, connect it to Dify, and fix what goes wrong

Dify works through an internal app that you create in your DingTalk organization. The app:

* Sends requests to members through its bot, each as a message with a link to the form in Dify.
* Lets Dify read the member directory and match each person to a workspace member by email.

## Before You Start

Make sure that:

* You can create internal apps in your DingTalk organization's Developer Console.
* [`CONSOLE_WEB_URL`](https://docs.dify.ai/en/self-host/deploy/configuration/environments#console_web_url) is set to an address members can open, since every request links there.

## Create the App

In the [DingTalk Developer Console](https://open-dev.dingtalk.com/), go to **App Development** > **DingTalk App** and click **Create App**. Give the app a name and a description, and click **Save**. Then:

1. In the app, open **Add App Capability** and click **Add** on the **Bot** card.

2. On the **Bots** page, turn on **Bot Configuration**, fill in the required fields, then click **Publish**.

   * In **Bot name**, give the bot a name members will recognize, such as *Dify*: requests arrive from a bot with this name.

   * Leave **Message receiving mode** as **Stream mode**.

3. In **Manage permissions**, set **Contacts API permission scope** to **All employees**. Then search for each of these permission codes and enable it:

   * `qyapi_robot_sendmsg`
   * `qyapi_get_department_list`
   * `qyapi_get_department_member`
   * `qyapi_get_member`
   * `fieldEmail`

4. In **Version Management and Release**, click **Create New Version**, set **Available scope** to **All employees**, and click **Save**.

   If you're not a DingTalk admin, your admin may need to approve it first. Wait until it's published before you connect next.

## Connect in Dify

1. In **Settings** > **Channels**, find DingTalk and click **Connect**.

   > [!NOTE]
   >
   > If another IM (instant messaging app) is already connected, click **Replace** instead. Check [what replacing clears](https://docs.dify.ai/en/self-host/use-dify/workspace/channels/overview#replace-or-remove-your-im) first.

2. Enter the values from DingTalk:

   * **Corp ID**: the **CorpId** on the Developer Console's home page.
   * **Client ID** and **Client Secret**: on your app's **Credentials and Basic Information** page.

   > [!NOTE]
   >
   > Whenever you change one of these values in DingTalk, update it in Dify too.

3. Click **Connect**. Dify checks the connection before saving.

## Sync and Test

1. In **Channels**, click **Sync now** to bind members' IM identities. See [Sync Members](https://docs.dify.ai/en/self-host/use-dify/workspace/channels/overview#sync-members) for what each result means.

2. With your own IM identity bound, send yourself a test request:

   * For a quick check that messages reach you, use **Test message** in a Human Input node's **Message template**: pick DingTalk as the **Test channel** and click **Save and test**. It sends you the message without running the workflow.
   * To check the whole flow, turn on Debug Mode in the node, pick DingTalk, and test-run the workflow. When the message arrives in your chat with the bot, open the link, sign in, respond, and check that the run continues.

   If the test fails or nothing arrives, see [Troubleshooting](#troubleshooting).

## What Members See

Each request arrives in the member's one-on-one chat with the bot. It's a text message built from the node's [message template](https://docs.dify.ai/en/self-host/use-dify/nodes/human-input.md#write-the-notification): the subject, then the body with the link.

![Request as a DingTalk Message](https://mintcdn.com/dify-6c0370d8/Q8QYd_xcsh-LWaCu/images/use-dify/workspace/channels-dingtalk-request-message.png?fit=max\&auto=format\&n=Q8QYd_xcsh-LWaCu\&q=85\&s=0150b37deb18378db1afa8780c342748)

Request as a DingTalk Message

The subject is what members read first, so make it say what they're deciding, such as *Approve refund for order 1042*.

Members open the link and respond in Dify, signed in with the account the request was sent to. A forwarded link doesn't work for anyone else, so add everyone who should respond as a recipient.

## Troubleshooting

> [accordion] Connecting says DingTalk could not verify complete member authorization
>
> Dify can't read your whole DingTalk directory, because **Contacts API permission scope** isn't **All employees**. Change it in **Manage permissions**, then click **Connect** again.

> [accordion] Connecting fails with API error code 88 or 60011
>
> The app lacks `qyapi_get_department_list`. Enable it in **Manage permissions**, then click **Connect** again.

> [accordion] A sync says the provider directory could not be read
>
> Usually the app lacks `qyapi_get_department_member`. Enable it in **Manage permissions** and sync again.

> [accordion] Members stay Not matched after a sync
>
> Dify found no matching email for them. Depending on who's affected:
>
> * Every member: the app lacks `fieldEmail`. Enable it in **Manage permissions** and sync again.
> * Some members: Dify reads the email on each member's DingTalk profile, not their DingTalk enterprise mailbox. For members who have only an enterprise mailbox, add an email to their profile and sync again, or [bind them by hand](https://docs.dify.ai/en/self-host/use-dify/workspace/contacts.md#bind-by-hand).

> [accordion] A test request fails
>
> Something stops Dify from sending: **Test message** shows "Test failed. Check the channel configuration and try again.", or a Debug Mode run fails with "No one can approve this step."
>
> Check that:
>
> * The app has `qyapi_robot_sendmsg` enabled.
> * The bot is published, and you published an app version after it.
> * Your own IM identity is bound.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.