---
title: "Create a bot"
method: POST
path: "/calendar/{connection_id}/bot"
tags: ["calendar", "bot"]
---

# Create a bot

`POST /calendar/{connection_id}/bot`

## Request

- Base URL: `https://api.unified.to`
- URL: `https://api.unified.to/calendar/{connection_id}/bot`
- Auth: API key in header `authorization`
- TypeScript: <https://skmtc.dev/unified/apis/unified-to-api/docs/calendar/:connection_id/bot/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a CalendarBot. Provide the unified CalendarBot fields in the request body; they are mapped to the provider's API. Returns the created CalendarBot.

## Path parameters

- `connection_id` string, required

## Query parameters

- `fields` string[]
- `raw` string

## Request body

- CalendarBot
  - `id` string
  - `created_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `updated_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `name` string: Display name for the bot in the meeting
  - `meeting_url` string: URL of the meeting to join
  - `event_id` string: Reference to calendar_event if scheduled via calendar (reference to CalendarEvent)
  - `status` 'READY' | 'JOINING_CALL' | 'IN_WAITING_ROOM' | 'IN_CALL_NOT_RECORDING' | 'RECORDING_PERMISSION_ALLOWED' | 'RECORDING_PERMISSION_DENIED' | 'IN_CALL_RECORDING' | 'CALL_ENDED' | 'DONE' | 'FATAL'
  - `status_changes` CalendarBotStatusChange[]: History of status changes
    - `status` 'READY' | 'JOINING_CALL' | 'IN_WAITING_ROOM' | 'IN_CALL_NOT_RECORDING' | 'RECORDING_PERMISSION_ALLOWED' | 'RECORDING_PERMISSION_DENIED' | 'IN_CALL_RECORDING' | 'CALL_ENDED' | 'DONE' | 'FATAL'
    - `changed_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `sub_code` string: Platform-specific status sub-code
    - `message` string: Human-readable status message
  - `join_at` string, date-time: When to join the meeting (for scheduled bots) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `started_at` string, date-time: When the bot actually joined (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `ended_at` string, date-time: When the bot left (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `recording_config` PropertyCalendarBotRecordingConfig
    - `record_video` boolean
    - `record_audio` boolean
    - `record_transcript` boolean
    - `record_chat` boolean
    - `record_screenshare` boolean
    - `transcription` PropertyCalendarBotRecordingConfigTranscription
      - `provider` 'MEETING_CAPTIONS' | 'AWS_TRANSCRIBE' | 'GOOGLE_SPEECH' | 'ASSEMBLYAI' | 'DEEPGRAM' | 'CUSTOM'
      - `mode` 'PRIORITIZE_ACCURACY' | 'PRIORITIZE_LOW_LATENCY'
      - `language` string: ISO language code (e.g., 'en-US')
      - `enable_speaker_labels` boolean: Whether to identify speakers in transcript
      - `enable_word_timestamps` boolean: Whether to include word-level timestamps
  - `automatic_leave` PropertyCalendarBotAutomaticLeave
    - `waiting_room_timeout` number: Seconds to wait in waiting room before leaving (default: 1200)
    - `no_participants_timeout` number: Seconds to wait when no other participants before leaving (default: 2)
    - `detect_bots` boolean: Whether to leave if only bots remain
  - `meeting_metadata` PropertyCalendarBotMeetingMetadata
    - `title` string
    - `platform` string: 'zoom', 'webex', 'google_meet', etc.
    - `host_name` string
    - `host_email` string
    - `meeting_identifier` string: Platform-specific meeting identifier (not a unified object ref)
    - `started_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `ended_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `participant_count` number
  - `participants` CalendarBotParticipant[]
    - `id` string
    - `name` string
    - `email` string
    - `is_host` boolean
    - `is_cohost` boolean
    - `joined_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `left_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `platform` string: Platform-specific participant identifier
    - `is_bot` boolean: Whether this participant is a bot
    - `is_self` boolean: Whether this participant is the current bot
    - `speaking` boolean: Whether participant is currently speaking
    - `webcam_on` boolean: Whether participant's webcam is on
    - `screenshare_on` boolean: Whether participant is sharing screen
    - `platform_metadata` union: Platform-specific metadata
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
  - `recording_id` string: Reference to calendar_recording when ready
  - `raw` object

## Response `200`

Successful

- CalendarBot
  - `id` string
  - `created_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `updated_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `name` string: Display name for the bot in the meeting
  - `meeting_url` string: URL of the meeting to join
  - `event_id` string: Reference to calendar_event if scheduled via calendar (reference to CalendarEvent)
  - `status` 'READY' | 'JOINING_CALL' | 'IN_WAITING_ROOM' | 'IN_CALL_NOT_RECORDING' | 'RECORDING_PERMISSION_ALLOWED' | 'RECORDING_PERMISSION_DENIED' | 'IN_CALL_RECORDING' | 'CALL_ENDED' | 'DONE' | 'FATAL'
  - `status_changes` CalendarBotStatusChange[]: History of status changes
    - `status` 'READY' | 'JOINING_CALL' | 'IN_WAITING_ROOM' | 'IN_CALL_NOT_RECORDING' | 'RECORDING_PERMISSION_ALLOWED' | 'RECORDING_PERMISSION_DENIED' | 'IN_CALL_RECORDING' | 'CALL_ENDED' | 'DONE' | 'FATAL'
    - `changed_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `sub_code` string: Platform-specific status sub-code
    - `message` string: Human-readable status message
  - `join_at` string, date-time: When to join the meeting (for scheduled bots) (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `started_at` string, date-time: When the bot actually joined (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `ended_at` string, date-time: When the bot left (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
  - `recording_config` PropertyCalendarBotRecordingConfig
    - `record_video` boolean
    - `record_audio` boolean
    - `record_transcript` boolean
    - `record_chat` boolean
    - `record_screenshare` boolean
    - `transcription` PropertyCalendarBotRecordingConfigTranscription
      - `provider` 'MEETING_CAPTIONS' | 'AWS_TRANSCRIBE' | 'GOOGLE_SPEECH' | 'ASSEMBLYAI' | 'DEEPGRAM' | 'CUSTOM'
      - `mode` 'PRIORITIZE_ACCURACY' | 'PRIORITIZE_LOW_LATENCY'
      - `language` string: ISO language code (e.g., 'en-US')
      - `enable_speaker_labels` boolean: Whether to identify speakers in transcript
      - `enable_word_timestamps` boolean: Whether to include word-level timestamps
  - `automatic_leave` PropertyCalendarBotAutomaticLeave
    - `waiting_room_timeout` number: Seconds to wait in waiting room before leaving (default: 1200)
    - `no_participants_timeout` number: Seconds to wait when no other participants before leaving (default: 2)
    - `detect_bots` boolean: Whether to leave if only bots remain
  - `meeting_metadata` PropertyCalendarBotMeetingMetadata
    - `title` string
    - `platform` string: 'zoom', 'webex', 'google_meet', etc.
    - `host_name` string
    - `host_email` string
    - `meeting_identifier` string: Platform-specific meeting identifier (not a unified object ref)
    - `started_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `ended_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `participant_count` number
  - `participants` CalendarBotParticipant[]
    - `id` string
    - `name` string
    - `email` string
    - `is_host` boolean
    - `is_cohost` boolean
    - `joined_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `left_at` string, date-time: (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
    - `platform` string: Platform-specific participant identifier
    - `is_bot` boolean: Whether this participant is a bot
    - `is_self` boolean: Whether this participant is the current bot
    - `speaking` boolean: Whether participant is currently speaking
    - `webcam_on` boolean: Whether participant's webcam is on
    - `screenshare_on` boolean: Whether participant is sharing screen
    - `platform_metadata` union: Platform-specific metadata
      - object
      - string
      - number
      - boolean
      - union[]
        - union
          - object
          - string
          - number
          - boolean
  - `recording_id` string: Reference to calendar_recording when ready
  - `raw` object

## Changes

- **2026-11-04** `955c92a9127f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unified/apis/unified-to-api/changes/calendar/:connection_id/bot/post.md)

---

[API](https://skmtc.dev/unified/apis/unified-to-api.md) - [All operations](https://skmtc.dev/unified/apis/unified-to-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unified/apis/unified-to-api/revisions/122e36e8450a?raw)