SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfeishu-calendar

feishu-calendar

Office & productivity

View repository

Updated 10-15 16:29

About this skill

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[] - -

🎯 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 participant 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"

⚠️ 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:

  1. API returns success → rsvp_status: "needs_action"(booking in progress)
  2. Background asynchronous processing
  3. 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 schedules, must satisfy:

  1. event_id must be the ID of a recurring event (the event has a recurrence field)
  2. If called on a regular event, an error will be returned

How to determine：

  1. First use get action to get event details
  2. Check whether the return value contains a recurrence field and it is not empty
  3. If so, 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 Did not pass user_open_id Strongly recommended to pass user_open_id = SenderId
Attendees cannot see other attendees attendee_ability insufficient permissions The tool has set by default can_modify_event
Incorrect time Used a Unix timestamp Switch to ISO 8601 format (with time zone):2024-01-01T00:00:00+08:00
Meeting room shows "reserving" Meeting room reservation is asynchronous Wait a few seconds and then use list to query rsvp_status
Modifying an event reports a permission error 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 set can_see_others or higher permissions

📚 Appendix: Background knowledge

A. Calendar architecture model

Feishu Calendar uses a three-layer architecture：

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

Key understanding：

  1. User's primary calendar: The event is created on the initiating user's primary calendar, and the user themselves can see it
  2. Attendee mechanism: By adding attendees, the event is also displayed in other people's calendars
  3. 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

  1. Create: Create the event on the user's primary calendar (the tool uses the user's identity)
  2. Invite attendees: Share the event with other attendees via the attendee API
  3. Attendee reply: Attendees can accept/decline/tentative
  4. Modify: The organizer or attendees with permission can modify
  5. 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 Linked Google calendar ❌ No ❌ No
exchange Linked 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)

  1. A maximum of 3000 attendees per event
  2. Limit for adding attendees at a time：
    • User-type attendees: 1000 people
    • Meeting rooms: 100
  3. The primary calendar cannot be deleted(calendars with type primary)
  4. Meeting room booking may fail：
    • Time conflict
    • No booking permission
    • Meeting room configuration restrictions