Back to Details

lark

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Lark (Feishu) API

Lark (Feishu) API

Complete Lark/Feishu integration for enterprise collaboration, including messaging, group management, contacts, and calendar.
面向企业协作场景的完整Lark/Feishu集成方案，涵盖消息、群组管理、通讯录和日历功能。

When to Use

适用场景

  • Send automated notifications to users or groups
  • Build interactive bot workflows
  • Manage group chats and members
  • Query contacts and organization structure
  • Sync calendar events and schedules
  • Integrate Lark with other systems
  • 向用户或群组发送自动化通知
  • 构建交互式机器人工作流
  • 管理群聊及成员
  • 查询通讯录与组织架构
  • 同步日历事件与日程
  • 将Lark与其他系统集成

Prerequisites

前置条件

Set the following environment variables:
bash
export LARK_APP_ID=cli_xxxxx
export LARK_APP_SECRET=xxxxx
Get your credentials from: https://open.larkoffice.com/
设置以下环境变量：
bash
export LARK_APP_ID=cli_xxxxx
export LARK_APP_SECRET=xxxxx
从以下地址获取凭证：https://open.larkoffice.com/

Required Permissions

所需权限

Enable these API scopes in your Lark app:
  • im:message
    - Send and read messages
  • im:chat
    - Manage group chats
  • contact:user.base:readonly
    - Read contacts
  • calendar:calendar
    - Manage calendars
在你的Lark应用中启用以下API权限范围：
  • im:message
    - 发送和读取消息
  • im:chat
    - 管理群聊
  • contact:user.base:readonly
    - 读取通讯录
  • calendar:calendar
    - 管理日历

Token Management

Token管理

Lark uses tenant access tokens that expire after 2 hours. Use this helper to get or refresh the token:
bash
undefined
Lark使用的租户访问令牌有效期为2小时。使用以下辅助工具获取或刷新令牌：
bash
undefined

Get or refresh token (cached to /tmp/lark_token.json)

获取或刷新令牌（缓存至/tmp/lark_token.json）

get_lark_token() { local token_file="/tmp/lark_token.json" local current_time=$(date +%s)

Check if cached token is still valid

if [ -f "$token_file" ]; then local expire_time=$(jq -r '.expire_time // 0' "$token_file" 2>/dev/null || echo "0") if [ "$current_time" -lt "$expire_time" ]; then jq -r '.tenant_access_token' "$token_file" return 0 fi fi

Get new token

local response=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
-H "Content-Type: application/json"
-d "{"app_id": "${LARK_APP_ID}", "app_secret": "${LARK_APP_SECRET}"}")
local code=$(echo "$response" | jq -r '.code // -1') if [ "$code" != "0" ]; then echo "Error: $(echo "$response" | jq -r '.msg')" >&2 return 1 fi
local expire=$(echo "$response" | jq -r '.expire') local expire_time=$((current_time + expire - 300)) echo "$response" | jq ". + {expire_time: $expire_time}" > "$token_file" jq -r '.tenant_access_token' "$token_file" }
get_lark_token() { local token_file="/tmp/lark_token.json" local current_time=$(date +%s)

检查缓存令牌是否仍有效

if [ -f "$token_file" ]; then local expire_time=$(jq -r '.expire_time // 0' "$token_file" 2>/dev/null || echo "0") if [ "$current_time" -lt "$expire_time" ]; then jq -r '.tenant_access_token' "$token_file" return 0 fi fi

获取新令牌

local response=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
-H "Content-Type: application/json"
-d "{"app_id": "${LARK_APP_ID}", "app_secret": "${LARK_APP_SECRET}"}")
local code=$(echo "$response" | jq -r '.code // -1') if [ "$code" != "0" ]; then echo "Error: $(echo "$response" | jq -r '.msg')" >&2 return 1 fi
local expire=$(echo "$response" | jq -r '.expire') local expire_time=$((current_time + expire - 300)) echo "$response" | jq ". + {expire_time: $expire_time}" > "$token_file" jq -r '.tenant_access_token' "$token_file" }

Usage in commands

在命令中使用

TOKEN=$(get_lark_token)

Or get token directly without caching:

```bash
TOKEN=$(bash -c 'curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\": \"${LARK_APP_ID}\", \"app_secret\": \"${LARK_APP_SECRET}\"}"' | jq -r '.tenant_access_token')
TOKEN=$(get_lark_token)

或者直接获取令牌，不使用缓存：

```bash
TOKEN=$(bash -c 'curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{\"app_id\": \"${LARK_APP_ID}\", \"app_secret\": \"${LARK_APP_SECRET}\"}"' | jq -r '.tenant_access_token')

Examples

示例

1. Authentication - Get Access Token

1. 身份验证 - 获取访问令牌

Get and display tenant access token:
Write to 
/tmp/lark_request.json
:
json
{
  "app_id": "${LARK_APP_ID}",
  "app_secret": "${LARK_APP_SECRET}"
}
bash
bash -c 'curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json'
获取并显示租户访问令牌：
写入到
/tmp/lark_request.json
：
json
{
  "app_id": "${LARK_APP_ID}",
  "app_secret": "${LARK_APP_SECRET}"
}
bash
bash -c 'curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json'

2. Messaging - Send Messages

2. 消息功能 - 发送消息

Send Text Message to User

向用户发送文本消息

Write to 
/tmp/lark_request.json
:
json
{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Hello World\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "receive_id": "ou_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Hello World\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Text Message to Group Chat

向群聊发送文本消息

Write to 
/tmp/lark_request.json
:
json
{
  "receive_id": "oc_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Group message\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "receive_id": "oc_xxx",
  "msg_type": "text",
  "content": "{\"text\": \"Group message\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Rich Text (Post) Message

发送富文本（Post）消息

Write to 
/tmp/lark_request.json
:
json
{
  "receive_id": "ou_xxx",
  "msg_type": "post",
  "content": "{\"zh_cn\": {\"title\": \"Title\", \"content\": [[{\"tag\": \"text\", \"text\": \"Content\"}]]}}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "receive_id": "ou_xxx",
  "msg_type": "post",
  "content": "{\"zh_cn\": {\"title\": \"Title\", \"content\": [[{\"tag\": \"text\", \"text\": \"Content\"}]]}}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Send Interactive Card Message

发送交互式卡片消息

Write to 
/tmp/lark_request.json
:
json
{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"Alert\"}}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"plain_text\", \"content\": \"Message\"}}]}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"Alert\"}}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"plain_text\", \"content\": \"Message\"}}]}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Reply to Message

回复消息

Write to 
/tmp/lark_request.json
:
json
{
  "msg_type": "text",
  "content": "{\"text\": \"Reply content\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages/om_xxx/reply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "msg_type": "text",
  "content": "{\"text\": \"Reply content\"}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages/om_xxx/reply" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Get Chat History

获取聊天记录

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/messages?container_id_type=chat&container_id=oc_xxx&page_size=20" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/messages?container_id_type=chat&container_id=oc_xxx&page_size=20" \
  -H "Authorization: Bearer ${TOKEN}"

3. Chat Management - Group Operations

3. 聊天管理 - 群组操作

Create Group Chat

创建群聊

Write to 
/tmp/lark_request.json
:
json
{
  "name": "Project Team",
  "description": "Project discussion group",
  "user_id_list": ["ou_xxx", "ou_yyy"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "name": "Project Team",
  "description": "Project discussion group",
  "user_id_list": ["ou_xxx", "ou_yyy"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

List All Chats

列出所有群聊

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/chats" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/chats" \
  -H "Authorization: Bearer ${TOKEN}"

Get Chat Info

获取群聊信息

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx" \
  -H "Authorization: Bearer ${TOKEN}"

Add Members to Chat

添加群成员

Write to 
/tmp/lark_request.json
:
json
{
  "id_list": ["ou_xxx", "ou_yyy"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "id_list": ["ou_xxx", "ou_yyy"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Remove Members from Chat

移除群成员

Write to 
/tmp/lark_request.json
:
json
{
  "id_list": ["ou_xxx"]
}
bash
TOKEN=$(get_lark_token)
curl -X DELETE "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "id_list": ["ou_xxx"]
}
bash
TOKEN=$(get_lark_token)
curl -X DELETE "https://open.feishu.cn/open-apis/im/v1/chats/oc_xxx/members?member_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

4. Contacts - Directory Queries

4. 通讯录 - 目录查询

Get User Info

获取用户信息

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/ou_xxx?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/ou_xxx?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"

Search Users

搜索用户

Write to 
/tmp/lark_request.json
:
json
{
  "query": "John"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/contact/v3/users/search?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "query": "John"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/contact/v3/users/search?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

List Departments

列出部门

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/departments?parent_department_id=0" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/departments?parent_department_id=0" \
  -H "Authorization: Bearer ${TOKEN}"

Get Department Members

获取部门成员

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}"

5. Calendar - Schedule Management

5. 日历 - 日程管理

List Calendars

列出日历

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}"

Create Calendar

创建日历

Write to 
/tmp/lark_request.json
:
json
{
  "summary": "Project Calendar",
  "description": "Calendar for project events"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "summary": "Project Calendar",
  "description": "Calendar for project events"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Create Calendar Event

创建日历事件

Note: Replace 
<calendar_id>
with an actual calendar ID from List Calendars API.
bash
TOKEN=$(get_lark_token)
注意：将
<calendar_id>
替换为从“列出日历”API获取的实际日历ID。
bash
TOKEN=$(get_lark_token)

Convert ISO 8601 to Unix timestamp

将ISO 8601格式转换为Unix时间戳

START_TS=$(date -d "2025-01-15T10:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s) END_TS=$(date -d "2025-01-15T11:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T11:00:00+08:00" +%s)
START_TS=$(date -d "2025-01-15T10:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s) END_TS=$(date -d "2025-01-15T11:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T11:00:00+08:00" +%s)

Write request with timestamps

写入包含时间戳的请求内容

cat > /tmp/lark_request.json <<EOF { "summary": "Team Meeting", "description": "Weekly sync", "start_time": {"timestamp": "${START_TS}"}, "end_time": {"timestamp": "${END_TS}"} } EOF
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d @/tmp/lark_request.json
undefined
cat > /tmp/lark_request.json <<EOF { "summary": "Team Meeting", "description": "Weekly sync", "start_time": {"timestamp": "${START_TS}"}, "end_time": {"timestamp": "${END_TS}"} } EOF
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d @/tmp/lark_request.json
undefined

List Calendar Events

列出日历事件

bash
TOKEN=$(get_lark_token)
bash
TOKEN=$(get_lark_token)

Convert date range

转换日期范围

START_TS=$(date -d "2025-01-01T00:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-01T00:00:00+08:00" +%s) END_TS=$(date -d "2025-01-31T23:59:59+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-31T23:59:59+08:00" +%s)
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events?start_time=${START_TS}&end_time=${END_TS}"
-H "Authorization: Bearer ${TOKEN}"
undefined
START_TS=$(date -d "2025-01-01T00:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-01T00:00:00+08:00" +%s) END_TS=$(date -d "2025-01-31T23:59:59+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-31T23:59:59+08:00" +%s)
curl -X GET "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events?start_time=${START_TS}&end_time=${END_TS}"
-H "Authorization: Bearer ${TOKEN}"
undefined

6. Bot Information

6. 机器人信息

Get Bot Info

获取机器人信息

bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/bot/v3/info" \
  -H "Authorization: Bearer ${TOKEN}"
bash
TOKEN=$(get_lark_token)
curl -X GET "https://open.feishu.cn/open-apis/bot/v3/info" \
  -H "Authorization: Bearer ${TOKEN}"

Workflows

工作流示例

Send System Alert to Group

向群聊发送系统告警

Write to 
/tmp/lark_request.json
:
json
{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"System Alert\"}, \"template\": \"red\"}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"lark_md\", \"content\": \"**Error:** Service down\"}}]}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "receive_id": "oc_xxx",
  "msg_type": "interactive",
  "content": "{\"header\": {\"title\": {\"tag\": \"plain_text\", \"content\": \"System Alert\"}, \"template\": \"red\"}, \"elements\": [{\"tag\": \"div\", \"text\": {\"tag\": \"lark_md\", \"content\": \"**Error:** Service down\"}}]}"
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Create Team Group with Members

创建包含成员的团队群聊

Write to 
/tmp/lark_request.json
:
json
{
  "name": "Q1 Project",
  "description": "Q1 project discussion",
  "user_id_list": ["ou_abc", "ou_def", "ou_ghi"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json
写入到
/tmp/lark_request.json
：
json
{
  "name": "Q1 Project",
  "description": "Q1 project discussion",
  "user_id_list": ["ou_abc", "ou_def", "ou_ghi"]
}
bash
TOKEN=$(get_lark_token)
curl -X POST "https://open.feishu.cn/open-apis/im/v1/chats?user_id_type=open_id" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/lark_request.json

Query Organization Structure

查询组织架构

bash
TOKEN=$(get_lark_token)
bash
TOKEN=$(get_lark_token)

Get root departments

获取根部门

curl -X GET "https://open.feishu.cn/open-apis/contact/v3/departments?parent_department_id=0"
-H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .department_id, name: .name}'
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/departments?parent_department_id=0"
-H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .department_id, name: .name}'

Get members in a department

获取部门成员

curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id"
-H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .user_id, name: .name}'
undefined
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/find_by_department?department_id=od_xxx&user_id_type=open_id"
-H "Authorization: Bearer ${TOKEN}" | jq '.data.items[] | {id: .user_id, name: .name}'
undefined

Schedule a Meeting

安排会议

bash
TOKEN=$(get_lark_token)

START_TS=$(date -d "2025-01-20T09:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T09:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-20T10:30:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T10:30:00+08:00" +%s)
bash
TOKEN=$(get_lark_token)

START_TS=$(date -d "2025-01-20T09:00:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T09:00:00+08:00" +%s)
END_TS=$(date -d "2025-01-20T10:30:00+08:00" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-20T10:30:00+08:00" +%s)

Write request with timestamps

写入包含时间戳的请求内容

cat > /tmp/lark_request.json <<EOF { "summary": "Sprint Planning", "description": "Sprint 5 planning session", "start_time": {"timestamp": "${START_TS}"}, "end_time": {"timestamp": "${END_TS}"} } EOF
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d @/tmp/lark_request.json
undefined
cat > /tmp/lark_request.json <<EOF { "summary": "Sprint Planning", "description": "Sprint 5 planning session", "start_time": {"timestamp": "${START_TS}"}, "end_time": {"timestamp": "${END_TS}"} } EOF
curl -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/<calendar_id>/events"
-H "Authorization: Bearer ${TOKEN}"
-H "Content-Type: application/json"
-d @/tmp/lark_request.json
undefined

Message Types Reference

消息类型参考

Typemsg_typecontent Format
Text
text
{"text": "message"}
Rich Text
post
{"zh_cn": {"title": "...", "content": [...]}}
Image
image
{"image_key": "img_xxx"}
Card
interactive
{"header": {...}, "elements": [...]}
类型msg_type内容格式
文本
text
{"text": "message"}
富文本
post
{"zh_cn": {"title": "...", "content": [...]}}
图片
image
{"image_key": "img_xxx"}
卡片
interactive
{"header": {...}, "elements": [...]}

ID Types Reference

ID类型参考

ID TypeDescriptionExample
open_id
User open ID (default)
ou_xxx
user_id
User ID
abc123
union_id
Union ID across apps
on_xxx
email
User email address
user@example.com
chat_id
Group chat ID
oc_xxx
ID类型描述示例
open_id
用户开放ID（默认）
ou_xxx
user_id
用户ID
abc123
union_id
跨应用统一ID
on_xxx
email
用户邮箱
user@example.com
chat_id
群聊ID
oc_xxx

Guidelines

注意事项

  1. Token Management: Tokens expire after 2 hours. Use the 
    get_lark_token
    helper function for automatic caching and refresh.
  2. Rate Limits: Lark has rate limits per app. Add delays for bulk operations to avoid hitting limits.
  3. ID Types: Use 
    open_id
    for most user operations. Use 
    chat_id
    when targeting group chats.
  4. Card Builder: Design complex interactive cards using Lark Card Builder: https://open.larkoffice.com/tool/cardbuilder
  5. Error Handling: Check the 
    code
    field in responses. 
    0
    means success, non-zero indicates an error.
  6. Content Escaping: Message content must be JSON-escaped when passed as string. Use 
    jq
    to build complex payloads:
    bash
    CONTENT=$(jq -n --arg text "Hello" '{text: $text}')
curl ... -d "{\"content\": \"$(echo $CONTENT | jq -c .)\"}"
  7. Date Conversion: Calendar events require Unix timestamps. Use 
    date
    command with appropriate flags for your OS:
    • Linux: 
      date -d "2025-01-15T10:00:00+08:00" +%s
    • macOS: 
      date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s
  1. Token管理：令牌有效期为2小时。使用
    get_lark_token
    辅助函数实现自动缓存和刷新。
  2. 速率限制：Lark对每个应用设置了调用速率限制。批量操作时请添加延迟，避免触发限制。
  3. ID类型：大多数用户操作使用
    open_id
    。针对群聊时使用
    chat_id
    。
  4. 卡片构建：使用Lark卡片构建器设计复杂的交互式卡片：https://open.larkoffice.com/tool/cardbuilder
  5. 错误处理：检查响应中的
    code
    字段。
    0
    表示成功，非零值表示存在错误。
  6. 内容转义：消息内容作为字符串传递时必须进行JSON转义。使用
    jq
    构建复杂请求体：
    bash
    CONTENT=$(jq -n --arg text "Hello" '{text: $text}')
curl ... -d "{\"content\": \"$(echo $CONTENT | jq -c .)\"}"
  7. 日期转换：日历事件需要使用Unix时间戳。根据操作系统使用对应参数的
    date
    命令：
    • Linux：
      date -d "2025-01-15T10:00:00+08:00" +%s
    • macOS：
      date -j -f "%Y-%m-%dT%H:%M:%S%z" "2025-01-15T10:00:00+08:00" +%s

API Reference

API参考