DingTalk Plugin
This guide uses a DingTalk enterprise internal application. You need an enterprise administrator or an account able to develop apps, request permissions, and publish releases. The plugin reads directories, binds members, sends personal work notifications, and provides Soln sign-in through DingTalk.
1. Create An Internal Application
- Sign in to the DingTalk Open Platform, select the enterprise, and create an internal application under application development
- Enable the web application capability and enter the application name and description
- Record the Client ID (AppKey) and Client Secret (AppSecret) from credentials, and the AgentId from application details
- Include test members and required departments in both application availability and directory authorization scopes
Client ID, Client Secret, and AgentId must belong to the same application. AgentId is not the enterprise CorpId or a group webhook.
2. Request Permissions By Feature
Use the app's permission management. After approval, create and publish a version and complete any administrator approval required by the console. Selecting a permission without publishing may not make it effective.
| Feature | Required capability | Actual calls |
|---|---|---|
| Sign-in identity | Personal permission Contact.User.Read; the authorization request also includes openid and corpid | OAuth and GET /v1.0/contact/users/me |
| Email sign-in and matching | Directory field permission for email and personal information (fieldEmail), plus member detail access | Member details using the enterprise user ID |
| Departments | Department read access, including qyapi_get_department_list | /auth/scopes, /topapi/v2/department/get, /topapi/v2/department/listsub |
| Members | Permission to read department member details and individual member details; separate access for email and other restricted fields | /topapi/v2/user/list, /topapi/v2/user/get |
| Message push | Send work notifications; commonly identified as qyapi_robot_asyncsend in the console | /topapi/message/corpconversation/asyncsend_v2 |
DingTalk can change permission groups and labels. Use the failing endpoint's documentation and the permission identifiers shown in your console. The personal Contact.User.Read permission does not grant enterprise-wide directory access.
Structure synchronization writes to your Soln tenant using these read capabilities. It does not require permission to modify the DingTalk directory.
3. Install The Soln Plugin
- Install DingTalk under Integration → Apps → Plugins, entering Client ID and Client Secret
- Normally choose Match enabled tenant members by email. Explicit email allowlist also requires the initial email allowlist. An allowlist does not create Soln members; sign-in still needs an available matching member
- Wait for installation and activation, then open App Information and copy the Identity Provider Redirect URL and Single Sign-On Entry URL
See Enterprise Identity Plugins for directory binding, synchronization, and notification operations.
4. Register The Callback And Workspace Entry
| Value from Soln | DingTalk setting |
|---|---|
| Identity Provider Redirect URL | Redirect URL / Callback URL under the application's security or sign-in settings; enter the full HTTPS URL |
| Single Sign-On Entry URL | Web application Home URL and PC Home URL |
For a tenant at https://workspace.example.com, the plugin callback is typically https://workspace.example.com/plugins/dingtalk/callback. Copy the current value shown by Soln, including its path. Use the sign-in entry as the home page; the callback is a protocol endpoint, not the home page.
Installation creates the enterprise SSO connection. Confirm it is enabled under Account Center → SSO, then launch from the DingTalk workspace with an email matching an enabled Soln member. Sign-in does not create members.
5. Fetch And Bind The Directory
- Open the plugin's Organization Mapping and click Fetch Directory
- Check coverage. For the full tree, authorize the root department and its descendants and publish the change
- Under Users → Automatic Binding, match a unique field such as email, or bind existing members manually
Work notifications use the enterprise userid, not unionid. The organization list's root ID 1 is an organization mapping identifier, not CorpId.
6. Send Approval And Other Reminders
- Enable work notification permission, include recipients in app visibility, and bind them to available Soln members
- Under Message Push → Push Configuration, add a business application and enter its AgentId from step 1
- Select approval or other message templates as needed, save, and enable the configuration in the list
- Generate a new approval or reminder, inspect Message Logs, and check that application's work notifications in DingTalk
The plugin sends native OA work cards. DingTalk may display the application name as the header text; message parameters cannot force that name to change. Rename the app in DingTalk if appropriate. No group robot is required, and native DingTalk approval instances are not created.
Read The DingTalk Lists
See Enterprise Identity Plugin Lists And Actions for fixed columns, toolbar buttons, binding dialogs, and notification logs. The following provider fields appear only when returned. Dynamic names and IDs can repeat fixed columns because they preserve the API field meanings.
Organizations And Departments
The organization collection uses readable root-department data; the department collection shows authorized departments and may include the root again. Check authorization scope if the root organization is absent.
| Field | Meaning and values |
|---|---|
dept_id / parent_id | Department / parent ID. The root is normally 1; provider parent 0 is not an internal organization UUID |
name / code / source_identifier | Name / department code / source identifier; inspect actual values before code-based binding |
order | Sort value, not depth or member count |
member_count / owning_member_count | Member count including descendants / direct members, not occupied Soln seats |
dept_manager_userid_list | Department leader userids; does not assign Soln roles |
create_dept_group / auto_add_user / group_contain_sub_dept | Create a department group / auto-add users / include subdepartments; Boolean values display Yes/No |
dept_group_chat_id / org_dept_owner | Department group ID / owner userid; not personal notification recipient bindings |
hide_dept / outer_dept | Hide department / restrict directory visibility, distinct from disabling a department |
outer_permit_depts / outer_permit_users / user_permits / dept_permits | Department or user IDs controlling provider visibility |
auto_approve_apply / emp_apply_join_dept | Automatically approve joining / allow employee joining; these do not configure Soln approvals |
attrs | Department attributes and metadata. value is the value, rawValue the original value, and meta.code the attribute code |
extention | Department extension fields using the provider's spelling, distinct from user extension |
hide_scene_config / outer_scene_config | Whether hiding/restrictions apply in chat, tree, search, and profile contexts; inspect nested details |
union_dept_ext / from_union_org | Linked-organization department information / origin flag, not an internal organization binding |
tags | Education tags such as campus, period, grade, and class |
Users
| Field | Meaning and values |
|---|---|
userid / unionid | Enterprise user ID / developer-scoped user ID; current binding and notifications use userid |
name / job_number / title | Name / employee number / position; matching names do not prove identity |
email / org_email | Email / enterprise email; select a populated, unique value for automatic binding |
dept_id_list / dept_order | Department IDs / ordering within departments; membership can be multiple |
active | DingTalk activation, shown as activated/not activated, separate from Soln member status |
admin / boss / leader | Enterprise administrator / owner / department supervisor, shown as Yes/No |
avatar | Avatar URL rather than a local image file |
mobile / state_code / hide_mobile / telephone | Mobile / dialing code / mobile hidden / extension; subject to permissions and profile settings |
hired_date | Hire date; millisecond timestamps are formatted for display |
extension | Member custom attributes; inspect the structure in the drawer |
exclusive_account / work_place / remark | Enterprise account flag / workplace / remarks |
To bind by job_number, choose the actual internal employee-number field rather than assuming it has the same code. Check the internal label and code in the automatic binding selector.
Troubleshooting
| Symptom | Action |
|---|---|
Missing qyapi_get_department_list | Request department read permission, publish, confirm approval, and fetch again |
| Department or user outside authorization scope | Check both directory and application scopes; granting individual users does not grant the full department tree |
| Identity available but email missing | Check fieldEmail, member email data, member detail access, and the enabled Soln member's email |
| Message rejected | Check that AgentId belongs to the Client ID's app, work notification permission, enterprise userid, and recipient visibility |
| Accepted but not visible yet | task_id confirms asynchronous submission; inspect the application's work notifications, recipient, provider limits, and any sending results available in DingTalk administration |
| Tunnel domain changed | Update the tenant public origin, redirect URL, and web/PC home URLs. Newly generated messages use the updated links |