JS SDK: Events

Understanding Event Operations

The Events API provides comprehensive event management across multiple calendar providers. Whether you need to create a single event in a specific calendar or synchronize events across all connected providers, this API handles the complexity of working with Google Calendar and Microsoft Outlook.

Key Concepts:

Provider-Specific Events: Individual calendar entries created, read, updated, or deleted in a specific calendar (Google or Microsoft).

Meta Events: Unified calendar entries that are created, updated, or deleted across all connected calendar providers simultaneously, ensuring perfect synchronization.

Provider-Specific Operations

Use these methods when you need to interact with a specific calendar provider.

Note: To list/query existing events, see Calendar & Availability.

Create Event

const event = await recal.events.createEvent(
    'user_id',
    'google',
    'primary',
    {
        subject: 'Team Meeting',
        description: 'Weekly sync',
        start: '2024-01-15T10:00:00Z',
        end: '2024-01-15T11:00:00Z',
        attendees: [
            { email: 'colleague@company.com' }
        ],
        meeting: true  // Automatically creates Google Meet/Teams link
    }
)

console.log(event.id)  // Provider-specific event ID
console.log(event.meeting?.url)  // Meeting link if meeting: true

Get Event

// Get an existing event from a specific calendar
const event = await recal.events.getEvent(
    'user_id',
    'google',
    'primary',
    'event_id'
)

Update Event

// Update an existing event in a specific calendar
const updated = await recal.events.updateEvent(
    'user_id',
    'google',
    'primary',
    'event_id',
    {
        subject: 'Updated Meeting Title',
        description: 'Updated description',
        start: '2024-01-15T11:00:00Z',
        end: '2024-01-15T12:00:00Z'
    }
)

Delete Event

// Delete an event from a specific calendar
await recal.events.deleteEvent(
    'user_id',
    'google',
    'primary',
    'event_id'
)

Cross-Calendar Operations (Meta Events)

Meta events provide powerful cross-platform synchronization, ensuring events appear across all connected calendar providers simultaneously.

Create Meta Event

// Create event across ALL connected calendars (default behavior)
const metaEvent = await recal.events.createMetaEvent(
    'user_id',
    {
        subject: 'Cross-platform Meeting',
        start: '2024-01-20T15:00:00Z',
        end: '2024-01-20T16:00:00Z',
        attendees: [
            { email: 'team@example.com' }
        ],
        meeting: true
    }
)

console.log(metaEvent.metaId)  // Unique ID across all providers

// Or specify which providers to use
const metaEventSpecific = await recal.events.createMetaEvent(
    'user_id',
    {
        subject: 'Selective Sync Meeting',
        start: '2024-01-20T15:00:00Z',
        end: '2024-01-20T16:00:00Z'
    },
    {
        provider: ['google', 'microsoft'],  // Only these providers
        sendNotifications: true  // Send email notifications
    }
)

Get Meta Event

// Retrieve event data from all connected calendars
const metaEvent = await recal.events.getMetaEvent(
    'user_id',
    'meta_id_123'
)

// Or filter by provider
const metaEventFiltered = await recal.events.getMetaEvent(
    'user_id',
    'meta_id_123',
    {
        provider: ['google']
    }
)

Update Meta Event

// Update across ALL connected calendars
await recal.events.updateMetaEvent(
    'user_id',
    'meta_id_123',
    {
        subject: 'Updated Cross-Platform Title',
        start: '2024-01-20T16:00:00Z',
        end: '2024-01-20T17:00:00Z'
    }
)

// Or update with options
await recal.events.updateMetaEvent(
    'user_id',
    'meta_id_123',
    {
        subject: 'Updated Title'
    },
    {
        provider: ['microsoft'],  // Only update Microsoft calendars
        sendNotifications: false
    }
)

Delete Meta Event

// Delete from ALL connected calendars
await recal.events.deleteMetaEvent(
    'user_id',
    'meta_id_123'
)

// Or delete selectively
await recal.events.deleteMetaEvent(
    'user_id',
    'meta_id_123',
    {
        provider: ['google']  // Only delete from Google calendars
    }
)

Event Properties

All events support the following properties:

interface CreateEvent {
    subject?: string              // Event title
    description?: string          // Event description (HTML supported)
    start: string                 // ISO 8601 timestamp
    end: string                   // ISO 8601 timestamp
    location?: string             // Location or address
    attendees?: Attendee[]        // Array of { email: string }
    meeting?: boolean             // Auto-create meeting link (Google Meet/Teams)
}

Best Practices

Use Meta Events for Sync: When users have multiple calendars, use meta events to keep them synchronized
Include Meeting Links: Set meeting: true to automatically create Google Meet or Teams links
Handle Timezones: Always use ISO 8601 format with timezone information
Validate Attendees: Ensure email addresses are valid before creating events
Check OAuth Permissions: Ensure users have granted edit scope for write operations

See Error Handling for handling SDK errors
See Calendar & Availability for querying events
See OAuth for managing calendar connections

Events

On this page