# Create Bot

Create a new meeting bot to join and record a meeting.

Endpoint: POST /bot
Version: v1
Security: bearerAuth

## Request fields (application/json):

  - `transcription_model` (string, required)
    The transcription model to use for transcribing the audio.
Refer to [your billing page](https://platform.skribby.io?to=billing) for cost and availability per model.
    Enum: "none", "whisper", "assembly-ai-realtime", "deepgram", "deepram-v3", "assembly-ai", "speechmatics", "rev-ai", "elevenlabs", "deepgram-realtime", "deepgram-realtime-v3", "speechmatics-realtime", "gladia", "gladia-realtime"

  - `transcription_credentials` (string)
    Optional credential identifier issued by the Skribby platform when bringing your own API key for the selected transcription model.

  - `service` (string, required)
    The service the bot needs to join:
- gmeet - Google Meet
- teams - Microsoft Teams
- zoom - Zoom
    Enum: "gmeet", "teams", "zoom"

  - `meeting_url` (string, required)
    The URL to the meeting itself which the bot will use to join
    Example: "https://meet.google.com/osk-sbwe-nff"

  - `bot_name` (string, required)
    The name of the bot that'll join the meeting
    Example: "My Meeting Bot"

  - `bot_avatar_file` (string)
    Binary image file for bot avatar. 
Ideally should be in 16:9 aspect ratio.

  - `bot_avatar_url` (string)
    URL to an image that will be used as the bot's avatar.
This will be ignored if bot_avatar_file is provided.

  - `lang` (string)
    Language of the meeting. Optional but can improve transcription accuracy.
When using deepgram-realtime, this parameter is highly recommended.

Refer to the [Bot Language](/concepts/bot-language) page for more information.
    Example: "en"

  - `video` (boolean)
    Whether video should also be recorded during the meeting.  
Refer to [your billing page](https://platform.skribby.io?to=billing) for cost implications and availability.

  - `webhook_url` (string)
    URL to receive live updates on bot status changes, participant changes, etc.

  - `store_recording_for_1_year` (boolean)
    Audio recordings are stored for 1 week by default. This addon extends storage to 1 year.  
Refer to [your billing page](https://platform.skribby.io?to=billing) for cost implications and availability.

  - `scheduled_start_time` (integer)
    Unix timestamp for when the bot should join the meeting. If not provided,
the bot will attempt to join immediately.

  - `profanity_filter` (boolean)
    Whether the transcription should censor profanity.
Only available on select models. Refer to [your billing page](https://platform.skribby.io?to=billing) for availability per model.

  - `initial_chat_message` (string)
    Whenever the bot joins the meeting, it'll send this message to the chat.

  - `stop_options` (object)
    Define if and when the bot should stop on certain conditions.

  - `stop_options.time_limit` (integer)
    Maximum time in minutes that the bot may be active. Hard limit is 4 hours (240 minutes).

  - `stop_options.waiting_room_timeout` (integer)
    Minutes the bot will wait in the meeting waiting room before stopping if it is not admitted.
> ⚠️ Charge Warning: Going beyond 10 minutes incurs charges for not admitted bots. Additional fees equal your base price * (waiting_room_timeout - 10). Refer to [your billing page](https://platform.skribby.io?to=billing) for current base pricing.

  - `stop_options.last_person_detection` (integer)
    Minimum time in minutes the bot will spent alone in the meeting (once everyone left) before the bot will stop. Setting this to 0 disables this functionality.

  - `stop_options.silence_detection` (integer)
    Minimum time in minutes the bot will wait for any sounds before the bot will stop. This is useful for when there are other bots in the call and therefor the last_person_detection fails. Setting this to 0 disables this functionality.

  - `authentication` (object)
    Authentication credentials for joining private meetings.  
Refer to the [Bot Authentication](/concepts/bot-authentication) page for more information.

  - `authentication.account_id` (string)
    ID of the authenticated account created [via the dashboard](https://platform.skribby.io?to=authenticated-accounts).
Used for Google Meet and Microsoft Teams authentication.

  - `authentication.zoom_zak_token` (string)
    ZAK Token for Zoom authentication.

  - `authentication.always_authenticate` (boolean)
    By default, bots try to join as guests first. Set to true to force authentication.

  - `custom_vocabulary` (array)
    Provide certain words or phrases to improve transcription. Only supported on certain models, refer to [your billing page](https://platform.skribby.io?to=billing) to view availability per model.

  - `time_limit` (integer)
    Use time_limit on stop_options.

## Response 200 fields (application/json):

  - `id` (string)
    Unique bot identifier
    Example: "3c09b2aa-6708-42c1-8145-aa55ee223613"

  - `status` (string)
    Current status of the bot
    Enum: "scheduled", "booting", "joining", "recording", "processing", "transcribing", "leaving", "finished", "not_admitted", "auth_required", "invalid_credentials", "failed"

  - `service` (string)
    Service the bot joined
    Enum: "gmeet", "teams", "zoom"

  - `scheduled_for` (string,null)
    When the bot is scheduled to join (for scheduled bots)

  - `stop_options` (object)
    Defined options when the bot should stop on certain conditions.

  - `stop_options.time_limit` (integer)
    Maximum time in minutes that the bot may be active. Hard limit is 4 hours (240 minutes).

  - `stop_options.waiting_room_timeout` (integer)
    Minutes the bot will wait in the meeting waiting room before stopping if it is not admitted.
> ⚠️ Charge Warning: Going beyond 10 minutes incurs charges for not admitted bots. Additional fees equal your base price * (waiting_room_timeout - 10). Refer to [your billing page](https://platform.skribby.io?to=billing) for current base pricing.

  - `stop_options.last_person_detection` (integer)
    Minimum time in minutes the bot will spent alone in the meeting (once everyone left) before the bot will stop. 0 disables this functionality.

  - `stop_options.silence_detection` (integer)
    Minimum time in minutes the bot will wait for any sounds before the bot will stop. This is useful for when there are other bots in the call and therefor the last_person_detection fails. 0 disables this functionality.

  - `bot_name` (string)
    Name of the bot in the meeting

  - `bot_avatar` (string,null)
    URL to bot avatar image

  - `meeting_url` (string)
    URL of the meeting

  - `webhook_url` (string,null)
    Webhook URL for receiving updates

  - `recording_url` (string,null)
    URL to download the recording

  - `recording_available_until` (string,null)
    When the recording will be automatically deleted

  - `websocket_url` (string,null)
    WebSocket URL for real-time transcription (realtime models only)

  - `websocket_read_only_url` (string,null)
    WebSocket URL for real-time transcription (realtime models only) - Only provides access to events, no actions.  
Useful if you want to use the websocket directly in your front-end without providing access to the user.

  - `video` (boolean)
    Whether video is recorded for this meeting

  - `lang` (string,null)
    Language specified when creating the bot

  - `detected_lang` (string,null)
    Language detected from the conversation (if supported by the model)

  - `transcript` (array)
    Array of transcript segments

  - `transcript.start` (number)
    Start time in seconds
    Example: 4

  - `transcript.end` (number)
    End time in seconds
    Example: 5.62

  - `transcript.speaker` (integer)
    Speaker ID

  - `transcript.speaker_name` (string,null)
    Name of the speaker (only available for transcription models which support speaker diarization).
This field is only present when we are confident we can link a specific participant to this speaker.
If no participant could be confidently linked to the speaker, this will be null and potential_speaker_names will be provided instead.
    Example: "John Doe"

  - `transcript.potential_speaker_names` (array,null)
    Array of potential speaker matches with confidence scores. This field is only present when we cannot confidently
link a single participant to the speaker. If speaker_name is provided, this field will be null.

  - `transcript.potential_speaker_names.name` (string)
    Name of the potential speaker
    Example: "John Doe"

  - `transcript.potential_speaker_names.confidence` (number)
    Confidence score for this speaker match
    Example: 0.64

  - `transcript.confidence` (number)
    Confidence score for transcript accuracy
    Example: 0.9980372

  - `transcript.transcript` (string)
    The transcribed text
    Example: "This is a quick test."

  - `transcript.utterances` (array)
    Detailed utterance information (model-specific)

  - `transcription_model` (string)
    Model used for transcription

  - `participants` (array)
    List of meeting participants

  - `participants.name` (string)
    Participant's display name
    Example: "John Doe"

  - `participants.avatar` (string,null)
    URL to participant's avatar
    Example: "https://picsum.photos/50"

  - `participants.first_seen_at` (string)
    When participant was first detected
    Example: "2025-06-25T03:03:15.913000Z"

  - `participants.events` (array)
    Speaker events (if with-speaker-events=true)

  - `participants.events.type` (string)
    Type of speaker event
    Enum: "started-speaking", "stopped-speaking"

  - `participants.events.timestamp` (integer)
    Unix timestamp in milliseconds
    Example: 1750820602963

  - `events` (array)
    List of bot lifecycle events

  - `events.event` (string)
    Type of event
    Example: "status_update"

  - `events.data` (object)
    Event data

  - `events.data.old_status` (string)
    Example: "joining"

  - `events.data.new_status` (string)
    Example: "recording"

  - `events.created_at` (string)
    When the event occurred

  - `profanity_filter` (boolean)
    Whether profanity filter was enabled

  - `custom_vocabulary` (array)
    Words or phrases provided when creating meeting bot for transcription model

  - `created_at` (string)
    When the bot was created

  - `finished_at` (string,null)
    When the bot finished

  - `time_limit` (integer,null)
    Use time_limit property in stop_options.

## Response 400 fields (application/json):

  - `message` (string)
    Error message
    Example: "The selected transcription model is invalid."

  - `errors` (object)
    Error code

  - `errors.transcription_model` (array)
    List of errors per parameter
    Example: ["The selected transcription model is invalid."]

## Response 401 fields (application/json):

  - `message` (string)
    Error message
    Example: "Unauthenticated."