Feishu Plugin

This guide uses a Feishu enterprise self-built application and an account able to manage apps, permissions, directory scopes, and publication. The plugin connects to open.feishu.cn; do not mix Lark international credentials or hosts with this configuration.

1. Create An Application

1. Open the Feishu application console and create a self-built application
2. Record App ID and App Secret under credentials and basic information
3. Add the Web App capability; add Bot when using notifications
4. Configure the directory data scope in permission management and the application availability scope for the test members and required departments

2. Request API And Field Permissions

Feature	Permission or setting	Actual endpoint
Directory	Application directory read access, such as Read contacts as an app (contact:contact:readonly_as_app). If granular scopes are required, use the requirements for each endpoint on the right	GET /contact/v3/scopes, /contact/v3/departments/{id}, /contact/v3/departments/{id}/children, /contact/v3/users/find_by_department, /contact/v3/users/{id}
Group-based authorization	Also request contact:group:readonly when directory access is granted through user groups	Group membership lookup
Sign-in email	contact:user.email:readonly	Authorization request and email in /authen/v1/user_info
Sign-in employee information	contact:user.employee:readonly	Authorization request and user information
Directory email, phone, and other fields	Request the relevant field permissions and populate enterprise profiles. Check application directory permissions separately from user-authorized sign-in permissions	Directory user details
Personal messages	Enable the bot and request Send messages as an app (im:message:send_as_bot)	POST /im/v1/messages?receive_id_type=open_id

Paths are relative to https://open.feishu.cn/open-apis. User-authorized sign-in scopes do not substitute for application permissions used with a tenant_access_token.

After configuring permissions and data scope, create and publish a version and complete enterprise administrator approval. Publish subsequent capability, permission, and availability changes as required by the console.

Organization synchronization writes to Soln, so permission to modify Feishu contacts is not required.

3. Install The Soln Plugin

1. Under Integration → Apps → Plugins, install Feishu with App ID and App Secret
2. Select the sign-in Email field. The default is enterprise_email; choose email if that is the field your enterprise uses. The plugin uses the selected field without automatically switching
3. Normally choose Match enabled tenant members by email. Explicit email allowlist also requires the allowlist and does not create members
4. After activation, copy the Identity Provider Redirect URL and Single Sign-On Entry URL from App Information

4. Register The Redirect And Workspace Entry

Soln value	Feishu setting
Identity Provider Redirect URL	Security Settings → Redirect URLs; enter the full URL
Single Sign-On Entry URL	The web app's workspace or application home, including desktop and mobile entries required by the console

For https://workspace.example.com, the callback is typically https://workspace.example.com/plugins/feishu/callback. Copy the value shown by Soln, including the path. The callback is not the workspace home page.

Installation creates an enterprise SSO connection. Check it under Account Center → SSO and launch from Feishu with an authorized member. The selected email field must match an enabled Soln member. Sign-in does not create a new member.

5. Fetch The Directory And Send Messages

1. Under Organization Mapping, click Fetch Directory and inspect organizations, departments, and users
2. Match a unique field such as email, or bind manually. Individual-user authorization can return only users; it does not prove department access
3. Under Message Push → Push Configuration, add a business application, choose message templates, and enable it
4. Generate a new approval or ordinary reminder, then check Message Logs and the Feishu application bot's private conversation

Messages use an open_id belonging to this application. Do not substitute an open_id from another app, a user_id, or a union_id. No DingTalk AgentId or group webhook is required.

The plugin sends bot cards and Soln detail links rather than creating Feishu third-party approvals or tasks. See Enterprise Identity Plugins for notification and structure synchronization behavior.

Read The Feishu Lists

See Enterprise Identity Plugin Lists And Actions for fixed columns, search, pagination, export, binding, and delivery logs. Feishu fields depend on application data scope and field permissions; not every enterprise returns every field below.

Organizations And Departments

The organization collection uses readable root department 0. With partial user or department authorization, the root may be invisible; an empty organization list does not mean the enterprise has no organization.

Field	Meaning and values
open_department_id / department_id	System / custom department ID. The plugin traverses open_department_id; do not interchange them
name / i18n_name	Department name / localized names such as zh_cn, en_us, ja_jp, not separate departments
parent_department_id	Parent ID in the department ID type used for the request
leader_user_id / leaders	Supervisor / leader array; leaderType is 1 primary or 2 deputy, and leaderID identifies the person
order / chat_id	Sort value / department group ID, not a personal recipient ID
member_count / primary_member_count	Members including descendants / primary membership count, not active Soln seats
status.is_deleted	Provider deletion flag displayed as Yes/No; does not bypass internal deletion dependencies
unit_ids / department_hrbps	Unit IDs / department HRBP user IDs
group_chat_employee_types	Employee types permitted in department groups; see user codes below

Users

Field	Meaning and values
open_id / user_id / union_id	App-scoped / user / developer-scoped ID. Binding and cards use this application's open_id
name / en_name / nickname	Name / English name / alias. Shared names are not sufficient identity evidence
email / enterprise_email	Email / enterprise email. List matching and the plugin's sign-in email field are configured separately
employee_no / job_title	Employee number / position
department_ids / orders	Department IDs / ordering per department; orders[].is_primary_dept identifies primary membership
status.is_activated	Provider activation, separate from Soln enablement
status.is_frozen / is_frozen	Suspended flag, displayed as Yes/No
status.is_resigned / status.is_exited / status.is_unjoin	Resigned / exited / not joined. These are separate flags, not a single numeric status
is_tenant_manager	Feishu super-administrator flag, without granting Soln administration
gender	0 private, 1 male, 2 female, 3 other
employee_type	1 regular, 2 intern, 3 outsourced, 4 labor, 5 consultant
join_time	Hire date, formatted from a seconds timestamp
avatar / avatar_key	Avatar URL object / file key; avatar_72, avatar_240, avatar_640, avatar_origin are image sizes
mobile / mobile_visible	Phone / visibility; can be absent when unavailable or unauthorized
leader_user_id / dotted_line_leader_user_ids	Direct / dotted-line manager IDs
custom_attrs	Custom fields with id, type, and value, rather than internal member identifiers
custom_attrs[].type	TEXT, HREF, ENUMERATION, PICTURE_ENUM, or GENERIC_USER; inspect the matching value structure in details
assign_info	Feishu product licenses and validity periods, not Soln subscription seats
department_path	Nested department paths and localized names, readable in the drawer
city / country / work_station / geo	Work city / country or region / desk / data residency

For example, when status.is_frozen is Yes, check external status and internal enablement. A Bound label alone does not guarantee notification availability.

Troubleshooting

Symptom	Action
One user but no organizations or departments	Check whether only that user is authorized. Authorize departments for a subtree, or the entire enterprise/root scope for the complete tree
Root department readable but deletion not applied	Root readability does not prove enterprise-wide authorization. Missing departments are processed only with confirmed full directory scope
Directory permission granted but calls denied	Check application-level permissions, directory scope, published version, administrator approval, and the failing endpoint's requirements
Missing email or sign-in mismatch	Check field permissions, populated profiles, and whether enterprise_email or email is selected
Message rejected or recipient unavailable	Check bot capability, im:message:send_as_bot, publication, app visibility, and this application's open_id
Detail link asks for sign-in	Complete Soln sign-in through the SSO entry and verify the member's business permissions
Domain change breaks sign-in	Update the tenant public origin, Feishu redirect URL, and workspace home before testing again

Official References

• Feishu application console
• Get contact authorization scope
• Get a department
• Send a message