botserver/docs/src/chapter-05/keyword-book.md

BOOK

Schedule meetings and calendar events with attendees.

Syntax

BOOK attendees, subject, duration

Parameters

Parameter	Type	Description
attendees	String/Array	Email address(es) of attendees. Can be a single email or array of emails
subject	String	Meeting subject/title
duration	String	Duration of the meeting (e.g., "30m", "1h", "90m")

Description

The BOOK keyword creates calendar events and schedules meetings with specified attendees. It integrates with the calendar engine to:

• Find available time slots for all attendees
• Create calendar invitations
• Send meeting notifications
• Handle timezone conversions
• Support recurring meetings

Examples

Single Attendee Meeting

BOOK "john@example.com", "Project Review", "30m"

Multiple Attendees

attendees = ["alice@example.com", "bob@example.com", "carol@example.com"]
BOOK attendees, "Team Standup", "15m"

Dynamic Meeting Scheduling

email = GET_USER_EMAIL()
BOOK email, "1-on-1 Discussion", "45m"

Integration Points

• Calendar Engine: Uses calendar_engine module for availability checking
• Email Notifications: Sends invitations via email integration
• User Sessions: Respects user timezone preferences
• Meeting Rooms: Can optionally reserve physical/virtual rooms

Return Value

Returns a meeting object containing:

• meeting_id: Unique identifier for the meeting
• start_time: Scheduled start time
• end_time: Scheduled end time
• meeting_link: Virtual meeting URL (if applicable)
• status: Booking status ("confirmed", "tentative", "failed")

Error Handling

• Returns error if no common availability found
• Validates email addresses before sending invites
• Checks for calendar permissions
• Handles timezone mismatches gracefully

Best Practices

1. Check Availability First: Consider using availability checks for critical meetings
2. Provide Context: Include meaningful subject lines
3. Respect Working Hours: System checks business hours by default
4. Handle Conflicts: Implement retry logic for failed bookings

See Also

• CREATE_TASK - Create tasks instead of meetings
• SET_SCHEDULE - Schedule recurring events
• SEND_MAIL - Send email notifications

Implementation

Located in src/basic/keywords/book.rs