🏠 回到导航页 ← 返回飞书功能页面

📱 飞书 API 使用指南

详细的飞书机器人接口使用说明，包含完整的API调用示例

📋 目录

1 概述

飞书API提供了完整的企业通信解决方案，支持群组管理、消息发送、历史查询等功能。本指南将详细介绍如何使用这些API接口。

注意： 使用飞书API需要先在飞书开放平台创建应用并获取相应的权限。

主要功能：

2 认证配置

首先需要配置应用凭证并获取访问令牌。

获取 Tenant Access Token：

POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal 
curl -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
-H 'Content-Type: application/json' \
-d '{
    "app_id": "your_app_id",
    "app_secret": "your_app_secret"
}'
响应示例： 
{
    "code": 0,
    "msg": "success",
    "tenant_access_token": "t-g104498ae...",
    "expire": 7200
}
重要： Token有效期为2小时，请妥善保管并及时刷新。
3 查看群组列表

获取机器人所在的所有群组信息。

GET https://open.feishu.cn/open-apis/im/v1/chats 
curl -X GET 'https://open.feishu.cn/open-apis/im/v1/chats?page_size=20' \
-H 'Authorization: Bearer t-your_token_here'

参数说明：

参数 类型 说明
page_size int 分页大小，默认20，最大100
page_token string 分页标记，用于获取下一页
响应示例： 
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [{
            "chat_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
            "name": "测试群组",
            "description": "这是一个测试群组",
            "avatar": "https://...",
            "external": false
        }],
        "has_more": false,
        "page_token": ""
    }
}
4 发送文本消息

向指定群组发送文本消息，支持@用户功能。

POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id 
curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
-H 'Authorization: Bearer t-your_token_here' \
-H 'Content-Type: application/json' \
-d '{
    "receive_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
    "msg_type": "text",
    "content": "{\"text\":\"Hello, 这是一条测试消息！\"}"
}'

@用户示例：

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
-H 'Authorization: Bearer t-your_token_here' \
-H 'Content-Type: application/json' \
-d '{
    "receive_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
    "msg_type": "text",
    "content": "{\"text\":\"所有人 请注意重要通知！\"}"
}'

参数说明：

参数 类型 说明
receive_id string 群组或用户ID
msg_type string 消息类型：text/image/interactive
content string 消息内容（JSON字符串）
5 发送图片消息

发送图片消息需要先上传图片获取image_key，然后发送消息。

步骤1：上传图片

POST https://open.feishu.cn/open-apis/im/v1/images 
curl -X POST 'https://open.feishu.cn/open-apis/im/v1/images' \
-H 'Authorization: Bearer t-your_token_here' \
-F 'image_type=message' \
-F 'image=@/path/to/your/image.png'
上传响应： 
{
    "code": 0,
    "msg": "success",
    "data": {
        "image_key": "img_v3_02n3_453e9693-9833-4d13-96ef-b383477c49bg"
    }
}

步骤2：发送图片消息

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
-H 'Authorization: Bearer t-your_token_here' \
-H 'Content-Type: application/json' \
-d '{
    "receive_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
    "msg_type": "image",
    "content": "{\"image_key\":\"img_v3_02n3_453e9693-9833-4d13-96ef-b383477c49bg\"}"
}'
提示： 支持的图片格式包括PNG、JPG、JPEG、BMP、GIF、WEBP等，单张图片大小不超过30MB。
6 发送消息卡片

发送富文本消息卡片，支持复杂的交互内容。

简单消息卡片：

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
-H 'Authorization: Bearer t-your_token_here' \
-H 'Content-Type: application/json' \
-d '{
    "receive_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
    "msg_type": "interactive",
    "content": "{\"elements\":[{\"tag\":\"markdown\",\"content\":\"**重要通知**\\n\\n请所有同事注意：\\n- 明天召开全员会议\\n- 时间：下午2点\\n- 地点：会议室A\\n\\n所有人\"}]}"
}'

模板消息卡片：

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id' \
-H 'Authorization: Bearer t-your_token_here' \
-H 'Content-Type: application/json' \
-d '{
    "receive_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
    "msg_type": "interactive",
    "content": "{\"type\":\"template\",\"data\":{\"template_id\":\"your_template_id\",\"template_version_name\":\"1.0.0\",\"template_variable\":{\"title\":\"系统通知\",\"content\":\"您有新的任务待处理\"}}}"
}'
注意： 模板消息需要先在飞书开放平台创建消息模板并获得审核通过。
7 撤回消息

撤回已发送的消息（需要在24小时内）。

DELETE https://open.feishu.cn/open-apis/im/v1/messages/{message_id} 
curl -X DELETE 'https://open.feishu.cn/open-apis/im/v1/messages/om_dc13264520392913993dd051dba21dcf' \
-H 'Authorization: Bearer t-your_token_here'
成功响应： 
{
    "code": 0,
    "msg": "success",
    "data": {}
}
失败响应示例： 
{
    "code": 230002,
    "msg": "Bot/User can NOT be out of the chat.",
    "error": {
        "log_id": "202509121619514C0A9A4827E58F88583A"
    }
}
限制： 只能撤回机器人自己发送的消息，且必须在24小时内撤回。
8 查询会话历史

获取指定群组的历史消息记录。

GET https://open.feishu.cn/open-apis/im/v1/messages 
curl -X GET 'https://open.feishu.cn/open-apis/im/v1/messages?container_id=oc_5e6688c96088d5d605f3658d2ccc88fc&container_id_type=chat&start_time=1608594809&end_time=1609296809&page_size=50&sort_type=ByCreateTimeDesc' \
-H 'Authorization: Bearer t-your_token_here'

参数说明：

参数 类型 说明
container_id string 群组ID
container_id_type string 固定值：chat
start_time int 开始时间（Unix时间戳）
end_time int 结束时间（Unix时间戳）
page_size int 分页大小，最大100
sort_type string 排序方式：ByCreateTimeAsc/ByCreateTimeDesc
响应示例： 
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": false,
        "page_token": "",
        "items": [{
            "message_id": "om_dc13264520392913993dd051dba21dcf",
            "create_time": "1615380573411",
            "chat_id": "oc_5e6688c96088d5d605f3658d2ccc88fc",
            "sender": {
                "id": "ou_155184d1e73cbfb8973e5a9e698e74f2",
                "sender_type": "user"
            },
            "body": {
                "content": "{\"text\":\"这是一条测试消息\"}"
            },
            "msg_type": "text",
            "deleted": false
        }]
    }
}
9 常见问题

Q1: Token过期怎么办？

A: Token有效期为2小时，需要定期刷新。建议在Token过期前30分钟重新获取。

Q2: 为什么无法发送消息到某个群？

A: 请检查：

Q3: 图片上传失败怎么办？

A: 请检查：

Q4: 撤回消息失败？

A: 撤回限制：

技术支持： 如需更多帮助，请参考飞书开放平台官方文档或联系技术支持团队。