lark-contact
open.feishu.cn
Resolve Lark/Feishu names & emails to open_id, or look up user details by open_id
What is lark-contact?
lark-contact provides two focused operations for the Feishu/Lark directory: (1) search for users by name or email to obtain their open_id, and (2) look up a known open_id to retrieve name, department, email, contact info, personal status, and bio/signature. It supports both user-identity and bot-identity paths, which have different capabilities. It does not handle department tree traversal, listing employees by department, or org chart queries.
- Searches Feishu/Lark contacts by name or email and returns open_id (user identity only)
- Looks up user profile details by open_id including name, department, email, and contact info (bot or user identity)
- Retrieves personal status and individual signature/bio for multiple users in batch (user identity only)
- Distinguishes between user-identity and bot-identity command paths with clear routing
- Returns cross-tenant user flags and handles empty fields per Feishu visibility rules
- Integrates with lark-im and lark-calendar for downstream messaging and scheduling workflows
How to install lark-contact
npx skills add null --skill lark-contact- lark-cli must be installed and available in PATH
- Valid Feishu/Lark credentials configured for either user identity or bot identity
- Appropriate directory visibility permissions (admin may need to expand scope to avoid 41050 errors)
- Target users must be within the caller's visible scope in the Feishu tenant
How to use lark-contact
- 1.Determine your current identity: user or bot, as available commands differ between them
- 2.To find a user by name or email (user identity only): run `lark-cli contact +search-user --query "<name>"`
- 3.To look up a user by open_id as bot: run `lark-cli contact +get-user --user-id <open_id>`
- 4.To look up yourself or a known ID as user: run `lark-cli contact +search-user --user-ids me` or `+search-user --user-ids <id>`
- 5.To batch-query personal status and signatures: first run `lark-cli schema contact.user_profiles.batch_query` to inspect parameters, then call with `--data` payload
- 6.If a name search returns multiple results, present all candidates to the user and ask them to confirm before proceeding
- 7.Once you have the open_id and only need to message or schedule, switch to lark-im or lark-calendar directly
- 8.If you encounter a 41050 Permission denied error, check identity type and ask an admin to adjust directory visibility
Use cases
- Find a colleague's open_id by name before sending them a message via lark-im
- Resolve an email address to an open_id for calendar invite workflows
- Batch-query personal status and bio signatures for a list of known open_ids
- Confirm the correct user when a name search returns multiple matches before taking any action
- Look up profile details for a user when only their open_id is available
- Developers building Feishu/Lark bots that need to resolve user identities
- Automation engineers orchestrating multi-step workflows involving messaging or scheduling
- Agents that receive a person's name from user input and need to act on their account
- Teams integrating Feishu contact data into internal tools or dashboards
- Anyone using lark-cli who needs to bridge human-readable names to Feishu API identifiers
lark-contact FAQ
No. Name/email search via +search-user is only available under user identity. Bot identity only supports looking up a user by a known open_id using +get-user.
Present all candidates to the user and let them choose. Do not automatically select the first result, especially if the next action has side effects like sending a message or creating a calendar event.
Cross-tenant users have restricted visibility by Feishu's rules. Most business fields will be empty strings. Handle this with null/empty value fallbacks in downstream logic.
The current identity does not have directory visibility for the target user. Switch to bot identity, or ask a Feishu admin to expand the visible scope for your app or account.
No. Department tree traversal, listing employees by department, and org chart queries are out of scope. Use lark-openapi-explorer to find the appropriate native OpenAPI endpoints for those needs.
Full instructions (SKILL.md)
Source of truth, from open.feishu.cn.
name: lark-contact version: 1.0.0 description: "飞书 / Lark 通讯录:按姓名 / 邮箱解析成 open_id,或按 open_id 反查姓名 / 部门 / 邮箱 / 联系方式 / 个人状态 / 签名。当用户提到某人姓名要下一步发消息 / 排日程,或拿到 open_id 想查具体信息时使用。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli contact --help"
选哪个命令
user 身份和 bot 身份是两条完全独立的路径。先确定当前身份,再按下表选命令:
| 想做什么 | user 身份 | bot 身份 |
|---|---|---|
| 按姓名 / 邮箱搜员工拿 open_id | +search-user | 不支持 |
| 已知 open_id 取他人资料 | +search-user --user-ids <id> | +get-user --user-id <id> |
| 查看自己 | +get-user 或 +search-user --user-ids me | 不支持 |
| 查同事的个人状态 / 签名 | user_profiles batch_query | 不支持 |
已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 lark-im / lark-calendar。
典型场景
找张三给他发消息:先搜,确认 open_id,再发:
lark-cli contact +search-user --query "张三" --has-chatted --as user
lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
批量查同事的个人状态 / 个性签名(先用 schema 看参数)。
lark-cli schema contact.user_profiles.batch_query
lark-cli contact user_profiles batch_query \
--params '{"user_id_type":"open_id"}' \
--data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
--as user
搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
注意事项
- 41050 / Permission denied 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见
lark-shared。 - 跨租户用户(
is_cross_tenant=true)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。 - ID 类型:默认
open_id。+get-user可改--user-id-type union_id|user_id;+search-user只接受open_id。
不在本 skill 范围
- 发消息 / 查聊天记录 →
lark-im - 排日程 / 邀请会议 →
lark-calendar - 部门树 / 按部门列员工 / 组织架构 →
lark-openapi-explorer查找原生接口
Related skills
More from open.feishu.cn and the wider catalog.
lark-approval
Query, process, and initiate Lark approval tasks via CLI — search definitions, manage instances, and handle approvals.
lark-doc
Read, create, and edit Feishu cloud documents (Docx/Wiki) with content manipulation and media handling.
lark-base
Operate Feishu Multidimensional Tables (Base): create tables, manage fields, records, views, formulas, forms, dashboards, workflows, and permissions.
lark-calendar
Manage Lark calendar events and meeting rooms: view, create, update, search events, check availability, and book rooms.
lark-drive
Manage Feishu Drive files and folders: upload, download, organize, and import local documents.
lark-im
Lark/Feishu IM skill: send messages, manage group chats, download files, handle interactive cards, and more.