Schedule Bot for Event

Overview

Schedules a bot to join a calendar event. Creates an EventBridge schedule that triggers 3 minutes before the meeting start time. Supports deduplication, bot sharing, and recurring event scheduling.

Request

Endpoint: POST /calendar/schedule/{event_id} Headers:

Authorization: Token <api_key>

Path Parameters:

Parameter	Type	Required	Description
`event_id`	string	Yes	The EventID of the calendar event

Request Body:

{
  "deduplication_key": "unique_key",
  "bot_config": {
    "bot_name": "MeetStream Bot",
    "bot_message": "Bot joining your meeting",
    "audio_required": true,
    "video_required": false,
    "meeting_url": "optional_override_url",
    "join_at": "optional_override_time_iso8601",
    "transcription": {},
    "callback_url": "https://your-webhook.com",
    "automatic_leave": {},
    "recording_config": {}
  },
  "occurrence_date": "2024-12-20T10:00:00Z",
  "schedule_all_occurrences": false,
  "occurrence_limit": 52
}

Request Body Parameters

Parameter	Type	Required	Description
`deduplication_key`	string	Yes	Unique key for deduplication and bot sharing
`bot_config`	object	Yes	Bot configuration
`bot_config.bot_name`	string	No	Display name for the bot
`bot_config.bot_message`	string	No	Message to display when bot joins
`bot_config.audio_required`	boolean	No	Whether audio is required (default: true)
`bot_config.video_required`	boolean	No	Whether video is required (default: false)
`bot_config.meeting_url`	string	No	Override meeting URL (uses event URL if not provided)
`bot_config.join_at`	ISO 8601	No	Override join time (defaults to 3 minutes before event)
`bot_config.transcription`	object	No	Transcription configuration
`bot_config.callback_url`	string	No	Webhook URL for bot status updates
`bot_config.automatic_leave`	object	No	Automatic leave configuration
`bot_config.recording_config`	object	No	Recording configuration
`occurrence_date`	ISO 8601	No	For recurring events: specific occurrence date to schedule
`schedule_all_occurrences`	boolean	No	For recurring events: schedule all future occurrences
`occurrence_limit`	integer	No	Maximum number of occurrences to schedule (default: 52)

Response

Success Response - Single Event (200)

{
  "scheduled": true,
  "schedule_id": "bot-abc12345-xyz789012",
  "schedule_group": "google_meet",
  "event_id": "evt_abc123",
  "scheduled_time": "2024-12-20T09:57:00+00:00",
  "bot_id": "uuid",
  "bot_config": {
    "bot_name": "MeetStream Bot",
    "audio_required": true,
    "video_required": false
  },
  "message": "Bot scheduled successfully. Updated existing schedule with deduplication key.",
  "updated_existing": true
}

Success Response - Recurring Series (200)

{
  "scheduled": true,
  "master_event_id": "master_event_id",
  "occurrences_scheduled": 10,
  "occurrences_failed": 0,
  "total_occurrences": 10,
  "schedules_created": [
    {
      "schedule_id": "bot-abc12345-xyz789012",
      "event_id": "evt_occurrence_1",
      "scheduled_time": "2024-12-20T09:57:00+00:00",
      "bot_id": "uuid"
    }
  ],
  "failed_occurrences": [],
  "bot_config": {
    "bot_name": "MeetStream Bot",
    "audio_required": true
  }
}

Response Fields

Field	Type	Description
`scheduled`	boolean	Whether scheduling was successful
`schedule_id`	string	EventBridge schedule ID
`schedule_group`	string	Schedule group (zoom, google_meet, microsoft_teams, default)
`event_id`	string	Event ID that was scheduled
`scheduled_time`	ISO 8601	When the bot will join (3 minutes before event start)
`bot_id`	string	Bot ID created for this schedule
`bot_config`	object	Applied bot configuration
`message`	string	Success message
`updated_existing`	boolean	Whether an existing schedule was updated
`master_event_id`	string	(Recurring) Master event ID
`occurrences_scheduled`	integer	(Recurring) Number of occurrences scheduled
`occurrences_failed`	integer	(Recurring) Number of occurrences that failed
`total_occurrences`	integer	(Recurring) Total occurrences found
`schedules_created`	array	(Recurring) List of created schedules
`failed_occurrences`	array	(Recurring) List of failed occurrences

Error Responses

400 Bad Request

Missing deduplication_key
Event has no meeting link
Event time has already passed
Invalid occurrence_date format
Invalid occurrence_limit

401 Unauthorized

Missing user_id in token or invalid authentication.

404 Not Found

Event not found
User not found

500 Internal Server Error

An error occurred while scheduling the bot.

Features

Deduplication

Using the same deduplication_key on the same event will update the existing bot configuration instead of creating a new schedule. Using the same deduplication_key across different events will reuse the bot schedule, allowing you to share bot configurations across multiple events.

Recurring Events

For recurring events, you have two options:

Single Occurrence: Use occurrence_date to schedule a specific occurrence
All Occurrences: Set schedule_all_occurrences: true to schedule all future occurrences (up to occurrence_limit)

You cannot schedule the master event directly. You must schedule specific occurrences using occurrence_date or use schedule_all_occurrences for bulk scheduling.

Schedule Groups

Schedule groups are automatically determined by the meeting platform:

zoom - For Zoom meetings
google_meet - For Google Meet meetings
microsoft_teams - For Microsoft Teams meetings
default - For other platforms

Join Time

By default, bots are scheduled to join 3 minutes before the meeting start time. You can override this using bot_config.join_at.

Authorizations

Authorization

string

header

required

All API endpoints are authenticated using API Keys. The key should be included in the 'Authorization' header, prefixed with 'Token '. Example: 'Authorization: Token YOUR_API_KEY'.

Path Parameters

event_id

string

required

The EventID of the calendar event.

Body

application/json

deduplication_key

string

required

Unique key for deduplication and bot sharing

bot_config

object

required

Bot configuration

Show child attributes

occurrence_date

string<date-time>

For recurring events: specific occurrence date to schedule

schedule_all_occurrences

boolean

For recurring events: schedule all future occurrences

occurrence_limit

integer

Maximum number of occurrences to schedule (default: 52)

Response

Bot scheduled successfully.

scheduled

boolean

required

Whether scheduling was successful

schedule_id

string

EventBridge schedule ID

schedule_group

string

Schedule group (zoom, google_meet, microsoft_teams, default)

event_id

string

Event ID that was scheduled

scheduled_time

string<date-time>

When the bot will join (3 minutes before event start)

bot_id

string

Bot ID created for this schedule

bot_config

object

Applied bot configuration

message

string

Success message

updated_existing

boolean

Whether an existing schedule was updated

master_event_id

string

Master event ID (for recurring events)

occurrences_scheduled

integer

Number of occurrences scheduled (for recurring events)

occurrences_failed

integer

Number of occurrences that failed (for recurring events)

total_occurrences

integer

Total occurrences found (for recurring events)

schedules_created

array

List of created schedules (for recurring events)

failed_occurrences

array

List of failed occurrences (for recurring events)

API Documentation

Bot Endpoints

Calendar Endpoints

Webhook & Sockets

Overview

Request

Request Body Parameters

Response

Success Response - Single Event (200)

Success Response - Recurring Series (200)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Features

Deduplication

Recurring Events

Schedule Groups

Join Time

Authorizations

Path Parameters

Body

Response

API Documentation

Bot Endpoints

Calendar Endpoints

Webhook & Sockets

​Overview

​Request

​Request Body Parameters

​Response

​Success Response - Single Event (200)

​Success Response - Recurring Series (200)

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

​Features

​Deduplication

​Bot Sharing

​Recurring Events

​Schedule Groups

​Join Time

Authorizations

Path Parameters

Body

Response

Overview

Request

Request Body Parameters

Response

Success Response - Single Event (200)

Success Response - Recurring Series (200)

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Features

Deduplication

Bot Sharing

Recurring Events

Schedule Groups

Join Time