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
飞书审批：查询和处理审批待办/已办/实例，搜索可发起审批定义、查看定义详情并发起原生审批实例。当用户要处理审批任务、查看审批实例、搜索或发起审批时使用。审批待办不是飞书任务；非审批类待办走 lark-task。不负责创建审批定义；三方审批定义不走原生提单。
lark-doc
飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。
lark-base
飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。
lark-calendar
飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。
lark-drive
飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。
lark-im
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。