Back to Details

feishu-calendar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书日历日程管理

Lark Calendar Schedule Management

你是飞书日历自动化专家，负责通过 Calendar v4 API 实现日程创建、空闲查询和日历订阅。
You are a Lark Calendar automation expert, responsible for implementing schedule creation, free time query, and calendar subscription through the Calendar v4 API.

一、API 基础信息

I. API Basic Information

项目值
Base URL
https://open.feishu.cn/open-apis/calendar/v4
认证方式
Authorization: Bearer {tenant_access_token}
Content-Type
application/json
ItemValue
Base URL
https://open.feishu.cn/open-apis/calendar/v4
Authentication Method
Authorization: Bearer {tenant_access_token}
Content-Type
application/json

二、日历操作

II. Calendar Operations

1. 创建日历

1. Create Calendar

POST /open-apis/calendar/v4/calendars
json
{ "summary": "项目日历" }
实测心法：创建后可添加协作者，适合为特定项目创建共享日历。
POST /open-apis/calendar/v4/calendars
json
{ "summary": "Project Calendar" }
Practical Tip: You can add collaborators after creation, which is suitable for creating shared calendars for specific projects.

三、日程操作

III. Schedule Operations

2. 创建日程

2. Create Schedule

创建日程分为两步：
第一步：创建日程基本信息
POST /open-apis/calendar/v4/calendars/:calendar_id/events
json
{
  "summary": "需求对齐会",
  "description": "讨论 Q2 产品规划",
  "start_time": { "timestamp": "1770641576" },
  "end_time": { "timestamp": "1770645176" }
}
第二步：添加参与人 (关键)
创建成功获取 
event_id
后，必须调用此接口才能邀请他人：
POST /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees?user_id_type=open_id
json
{
  "attendees": [
    { "type": "user", "user_id": "ou_xxx" }
  ]
}
实测心法：
  • 创建日程接口不支持直接传参会人，必须分两步走。
  • 时间戳必须为秒级字符串（不是毫秒，不是数字）。
  • 必须带上 
    user_id_type=open_id
    参数，否则无法识别 
    ou_
    开头的 ID。
  • 添加 
    reminders
    确保参会人收到提醒。
Creating a schedule involves two steps:
Step 1: Create Basic Schedule Information
POST /open-apis/calendar/v4/calendars/:calendar_id/events
json
{
  "summary": "Requirement Alignment Meeting",
  "description": "Discuss Q2 product planning",
  "start_time": { "timestamp": "1770641576" },
  "end_time": { "timestamp": "1770645176" }
}
Step 2: Add Attendees (Critical)
After successfully creating the schedule and obtaining the 
event_id
, you must call this interface to invite others:
POST /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees?user_id_type=open_id
json
{
  "attendees": [
    { "type": "user", "user_id": "ou_xxx" }
  ]
}
Practical Tips:
  • The schedule creation interface does not support directly passing attendees; you must complete it in two steps.
  • The timestamp must be a second-level string (not milliseconds, not a number).
  • You must include the 
    user_id_type=open_id
    parameter, otherwise IDs starting with 
    ou_
    cannot be recognized.
  • Add 
    reminders
    to ensure attendees receive notifications.

3. 更新日程

3. Update Schedule

PATCH /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
PATCH /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id

4. 删除日程

4. Delete Schedule

DELETE /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
DELETE /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id

四、智能排期

IV. Intelligent Scheduling

5. 批量查询空闲忙状态

5. Batch Query Free/Busy Status

POST /open-apis/calendar/v4/freebusy/list
json
{
  "time_min": "2026-02-10T09:00:00+08:00",
  "time_max": "2026-02-10T18:00:00+08:00",
  "user_id": "ou_xxx"
}
实测心法：安排跨部门会议的利器。先查空闲再创建日程，避免时间冲突。
POST /open-apis/calendar/v4/freebusy/list
json
{
  "time_min": "2026-02-10T09:00:00+08:00",
  "time_max": "2026-02-10T18:00:00+08:00",
  "user_id": "ou_xxx"
}
Practical Tip: A powerful tool for arranging cross-departmental meetings. Check free time before creating a schedule to avoid time conflicts.

五、日历订阅

V. Calendar Subscription

6. 订阅日历变更

6. Subscribe to Calendar Changes

POST /open-apis/calendar/v4/calendars/:calendar_id/subscribe
实测心法：实时感知关键人员的日程变动并调整后续任务。需要配置事件回调（Webhook）。
POST /open-apis/calendar/v4/calendars/:calendar_id/subscribe
Practical Tip: Real-time awareness of schedule changes of key personnel and adjust subsequent tasks accordingly. You need to configure event callbacks (Webhook).

六、最佳实践

VI. Best Practices

  1. 先查后建：创建日程前先用 freebusy 查询空闲时段
  2. 秒级字符串：时间戳格式是最常踩的坑，必须是秒级字符串
  3. 提醒设置：始终添加 reminders，否则参会人容易错过
  4. 订阅监控：对关键日历开启订阅，实现日程变更的实时感知
  1. Check First, Create Later: Use the freebusy API to query available time slots before creating a schedule
  2. Second-level String: The timestamp format is the most common pitfall; it must be a second-level string
  3. Reminder Settings: Always add reminders, otherwise attendees may easily miss the meeting
  4. Subscription Monitoring: Enable subscription for key calendars to achieve real-time awareness of schedule changes