feishu-calendar

Feishu Calendar Management (feishu-calendar)

🚨 Must-read before execution

✅ Fixed time zone：Asia/Shanghai（UTC+8）
✅ Time format: ISO 8601 / RFC 3339 (with time zone), for example 2026-02-25T14:00:00+08:00
✅ create minimum required：summary, start_time, end_time
✅ user_open_id strongly recommended: obtained from SenderId (ou_xxx), to ensure the user can see the schedule
✅ ID format conventions: user ou_..., group oc_..., meeting room omm_..., email email@...

📋 Quick index: intent → tool → required parameters

User intent	Tool	action	Required parameters	Strongly recommended	Common optional
Create meeting	feishu_calendar_event	create	summary, start_time, end_time	user_open_id	attendees, description, location
Query schedules for a time period	feishu_calendar_event	list	start_time, end_time	-	-
Change schedule time	feishu_calendar_event	patch	event_id, start_time/end_time	-	summary, description
Search meetings by keyword	feishu_calendar_event	search	query	-	-
Reply to invitation	feishu_calendar_event	reply	event_id, rsvp_status	-	-
Query recurring schedule instances	feishu_calendar_event	instances	event_id, start_time, end_time	-	-
Query free/busy	feishu_calendar_freebusy	list	time_min, time_max, user_ids[]	-	-
Invite attendees	feishu_calendar_event_attendee	create	calendar_id, event_id, attendees[]	-	-
Remove attendees	feishu_calendar_event_attendee	batch_delete	calendar_id, event_id, user_open_ids[]	-	-

🎯 Core constraints (knowledge not revealed by the Schema)

1. Why is user_open_id required?

The tool uses the user's identity: the schedule is created on the user's primary calendar, and the user themselves can see it.

But why still pass user_open_id: add the organizer as anattendee, to ensure:

✅ The organizer receives schedule notifications
✅ The organizer can reply with RSVP status (accepted/declined/tentative)
✅ The organizer appears in the attendee list
✅ Other attendees can see the organizer

If not passed：

⚠️ The user can see the schedule, but will not be an attendee
⚠️ If there are only other attendees, the organizer is not in the list (does not conform to normal logic)

2. Attendee permissions (attendee_ability)

The tool has already set the default attendee_ability: "can_modify_event", attendees can edit the schedule and manage participants.

Permission value	Capability
`none`	No permission
`can_see_others`	Can view the attendee list
`can_invite_others`	Can invite others
`can_modify_event`	Can edit the schedule (recommended)

3. Uniformly use open_id (ou_... format)

✅ Create schedule:user_open_id = SenderId
✅ Invite attendees:attendees[].id = "ou_xxx"
✅ Remove attendees:user_open_ids = ["ou_xxx"](the tool has been optimized, just pass open_id directly)

⚠️ ID format distinction：

ou_xxx: the user's open_id (the one you should use）
user_xxx: the schedule's internal attendee_id (returned by the list interface, used only for internal records)

4. Meeting room booking is an asynchronous process

After adding a meeting room type attendee, the meeting room enters an asynchronous booking process:

API returns success → rsvp_status: "needs_action"(booking in progress)
Background asynchronous processing
Final status:accept(success) or decline(failure)

Query booking result: use feishu_calendar_event_attendee.list to view rsvp_status。

5. The instances action is only valid for recurring schedules

⚠️ Important：instances action Only valid for recurring events, must satisfy:

event_id must be the ID of a recurring event (the event has a recurrence field)
If called on a normal event, it will return an error

How to determine：

First use get action to get event details
Check whether the return value contains a recurrence field and it is not empty
If yes, you can call instances to get the instance list

📌 Usage scenario examples

Scenario 1: Create a meeting and invite attendees

{
  "action": "create",
  "summary": "项目复盘会议",
  "description": "讨论 Q1 项目进展",
  "start_time": "2026-02-25 14:00:00",
  "end_time": "2026-02-25 15:30:00",
  "user_open_id": "ou_aaa",
  "attendees": [
    {"type": "user", "id": "ou_bbb"},
    {"type": "user", "id": "ou_ccc"},
    {"type": "resource", "id": "omm_xxx"}
  ]
}

Scenario 2: Query a user's events for the next week

{
  "action": "list",
  "start_time": "2026-02-25 00:00:00",
  "end_time": "2026-03-03 23:59:00"
}

Scenario 3: View the busy/free time of multiple users

{
  "action": "list",
  "time_min": "2026-02-25 09:00:00",
  "time_max": "2026-02-25 18:00:00",
  "user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
}

Note: user_ids is an array, supporting 1-10 users. Meeting room busy/free queries are currently not supported.

Scenario 4: Modify event time

{
  "action": "patch",
  "event_id": "xxx_0",
  "start_time": "2026-02-25 15:00:00",
  "end_time": "2026-02-25 16:00:00"
}

Scenario 5: Search events (by keyword)

{
  "action": "search",
  "query": "项目复盘"
}

Scenario 6: Reply to an event invitation

{
  "action": "reply",
  "event_id": "xxx_0",
  "rsvp_status": "accept"
}

🔍 Common errors and troubleshooting

Error symptom	Root cause	Solution
The organizer is not in the attendee list	Not passed `user_open_id`	Strongly recommend passing `user_open_id = SenderId`
Attendees cannot see other attendees	`attendee_ability` insufficient permissions	The tool has already set by default `can_modify_event`
Incorrect time	Used a Unix timestamp	Use ISO 8601 format instead (with time zone):`2024-01-01T00:00:00+08:00`
Meeting room shows "reserving"	Meeting room reservation is asynchronous	After waiting a few seconds, use `list` to query `rsvp_status`
Permission error when modifying an event	The current user is not the organizer, and the event does not have editable permissions set	Ensure that when the event is created, `attendee_ability: "can_modify_event"`
Cannot view the attendee list	The current user does not have view permission	Ensure you are the organizer or the event has `can_see_others` or higher permissions set

📚 Appendix: Background knowledge

A. Calendar architecture model

Feishu Calendar uses a three-layer architecture：

日历（Calendar）
  └── 日程（Event）
       └── 参会人（Attendee）

Key understanding：

User's primary calendar: The event is created on the initiating user's primary calendar, and the user themselves can see it
Attendee mechanism: By adding attendees, the event also appears in other people's calendars
Permission model: The event's attendee_ability parameter controls whether attendees can edit the event, invite others, and view the participant list

B. Attendee types

type: "user" + id: "ou_xxx" — Feishu user (using open_id)
type: "chat" + id: "oc_xxx" — Feishu group
type: "resource" + id: "omm_xxx" — Meeting room
type: "third_party" + id: "email@example.com" — External email

C. Event lifecycle

Create: Create the event on the user's primary calendar (the tool uses the user's identity)
Invite attendees: Share the event with other attendees via the attendee API
Attendee reply: Attendees can accept/decline/tentative
Modify: The organizer or attendees with permissions can modify
Delete: After deletion, the status becomes cancelled

D. Calendar type description

Type	Description	Can be deleted	Can be modified
`primary`	Primary calendar (one per user/app)	❌ No	✅ Yes
`shared`	Shared calendar (created and shared by users)	✅ Yes	✅ Yes
`resource`	Meeting room calendar	❌ No	❌ No
`google`	Bound Google calendar	❌ No	❌ No
`exchange`	Bound Exchange calendar	❌ No	❌ No

E. Reply status (rsvp_status) description

Status	Meaning (user)	Meaning (meeting room)
`needs_action`	Not replied	Booking in progress
`accept`	Accepted	Booking successful
`tentative`	Tentative	-
`decline`	Declined	Booking failed
`removed`	Removed	Removed

F. Usage limits (from Feishu OAPI documentation)

Up to 3000 attendees per event
Limit for adding attendees at a time：
- User-type attendees: 1000 people
- Meeting rooms: 100
The primary calendar cannot be deleted(calendars with type primary)
Meeting room booking may fail：
- Time conflict
- No booking permission
- Meeting room configuration restrictions