Lark API 参考
约 1012 字大约 3 分钟
2026-03-28
飞书 (Lark) Bot API 完整方法签名 — 消息发送、回复、富文本、文件上传、消息撤回。
Quick Reference
# 通过插件访问
await self.api.lark.send_text(receive_id, "消息内容")
await self.api.lark.reply_text(message_id, "回复内容")API 架构
LarkBotAPI (IAPIClient)
├── send_message() ← 通用消息发送
├── send_text() ← 文本消息便捷方法
├── reply_message() ← 引用回复
├── reply_text() ← 文本回复便捷方法
├── send_post() ← 富文本 (post) 消息
├── reply_post() ← 富文本回复
├── send_msg_array() ← MessageArray → 自动转换
├── reply_msg_array() ← MessageArray 回复
├── delete_message() ← 撤回消息
└── upload_file() ← 上传文件消息发送
send_message()
通用消息发送方法。其他发送方法均基于此实现。
async def send_message(
receive_id: str,
receive_id_type: str = "chat_id",
msg_type: str = "text",
content: str = "",
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
receive_id | str | — | 接收者 ID |
receive_id_type | str | "chat_id" | ID 类型:chat_id / open_id / user_id / union_id / email |
msg_type | str | "text" | 消息类型:text / post / image / interactive 等 |
content | str | "" | 消息内容 JSON 字符串 |
返回: SDK response.data(包含 message_id 等),失败返回 None。
send_text()
发送文本消息的便捷方法。
async def send_text(
receive_id: str,
text: str,
receive_id_type: str = "chat_id",
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
receive_id | str | — | 接收者 ID |
text | str | — | 文本内容 |
receive_id_type | str | "chat_id" | ID 类型 |
# 发到群聊
await self.api.lark.send_text("oc_xxxx", "Hello!")
# 发给用户
await self.api.lark.send_text("ou_xxxx", "Hi!", receive_id_type="open_id")消息回复
reply_message()
引用回复消息。
async def reply_message(
message_id: str,
msg_type: str = "text",
content: str = "",
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
message_id | str | — | 要回复的消息 ID |
msg_type | str | "text" | 消息类型 |
content | str | "" | 消息内容 JSON 字符串 |
reply_text()
文本引用回复的便捷方法。
async def reply_text(message_id: str, text: str) -> Anyawait self.api.lark.reply_text("om_xxxx", "收到你的消息!")富文本消息 (Post)
send_post()
发送富文本 (post) 消息。
async def send_post(
receive_id: str,
content: str,
receive_id_type: str = "chat_id",
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
receive_id | str | — | 接收者 ID |
content | str | — | post 格式 JSON 字符串 |
receive_id_type | str | "chat_id" | ID 类型 |
reply_post()
引用回复富文本消息。
async def reply_post(message_id: str, content: str) -> AnyLarkPostBuilder 构造器
LarkPostBuilder 提供链式 API 构造飞书 post 富文本:
from ncatbot.adapter.lark import LarkPostBuilder
content = (
LarkPostBuilder("公告")
.text("加粗文本 ", styles=["bold"])
.link("飞书", "https://www.feishu.cn")
.newline()
.at("ou_xxxx")
.text(" 请查看")
.newline()
.hr()
.code_block("print('hello')", language="Python")
.img("img_key_xxx")
.build() # → JSON 字符串
)
await self.api.lark.send_post("oc_xxxx", content)| 方法 | 说明 | 类型 |
|---|---|---|
.text(text, styles=) | 文本段 | 行内 |
.link(text, href, styles=) | 超链接 | 行内 |
.at(user_id, styles=) | @用户 | 行内 |
.emotion(emoji_type) | 表情 | 行内 |
.img(image_key) | 图片 | 块级 |
.media(file_key, image_key=) | 视频/媒体 | 块级 |
.hr() | 分割线 | 块级 |
.code_block(text, language=) | 代码块 | 块级 |
.md(text) | Markdown 块 | 块级 |
.newline() | 换行 | 控制 |
.build() | 构建为 JSON 字符串 | 输出 |
.build_dict() | 构建为字典 | 输出 |
MessageArray 转换
send_msg_array()
将 MessageArray 自动转换为飞书消息发送。纯文本内容自动降级为 text 类型。
async def send_msg_array(
receive_id: str,
msg: MessageArray,
title: str = "",
receive_id_type: str = "chat_id",
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
receive_id | str | — | 接收者 ID |
msg | MessageArray | — | 消息数组 |
title | str | "" | 富文本标题 |
receive_id_type | str | "chat_id" | ID 类型 |
reply_msg_array()
将 MessageArray 转换为飞书引用回复。
async def reply_msg_array(
message_id: str,
msg: MessageArray,
title: str = "",
) -> AnyMessageArray → Post 映射规则
| 消息段 | Post 元素 |
|---|---|
PlainText | {"tag": "text"} (遇 \n 自动换行) |
At | {"tag": "at"} |
Image | {"tag": "img"}(独占一行) |
Video | {"tag": "media"}(独占一行) |
Reply | 忽略(引用回复通过 API 实现) |
消息撤回
delete_message()
撤回(删除)指定消息。
async def delete_message(message_id: str) -> Anyawait self.api.lark.delete_message("om_xxxx")文件上传
upload_file()
上传文件到飞书服务器,返回 file_key 用于后续消息发送。
async def upload_file(
file_type: str,
file_name: str,
file: IO[Any],
duration: Optional[int] = None,
) -> Any| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
file_type | str | — | 文件类型:opus / mp4 / pdf / doc / xls / ppt / stream |
file_name | str | — | 文件名 |
file | IO[Any] | — | 文件对象 |
duration | int | None | None | 音视频时长(毫秒),仅 opus/mp4 需要 |
返回: response.data(包含 file_key),失败返回 None。
with open("document.pdf", "rb") as f:
result = await self.api.lark.upload_file("pdf", "document.pdf", f)
file_key = result.file_key交叉引用
| 如果你在找… | 去这里 |
|---|---|
| 飞书事件类型 | Lark 事件 |
| 飞书数据类型 | Lark 类型 |
| 飞书适配器指南 | Lark 适配器 |
| 通用 Trait 协议 | Traits |
版权所有
版权归属:GEYUANwuqi
