Skribby

A meeting bot is an ephemeral worker that moves through a well-defined set of states. Understanding these states and why they transition is the key to building a robust integration.

State Machine Overview

The following diagram represents the typical path of a bot:

scheduled → booting → joining → recording → leaving → processing → transcribing → finished

Standard Statuses

Status	Description
`scheduled`	The bot has been created with a `scheduled_start_time` in the future.
`booting`	Skribby is spinning up a dedicated worker instance and initializing the browser environment.
`joining`	The bot is navigating to the meeting URL and attempting to enter. This includes the "Waiting Room" phase.
`recording`	The bot is inside the meeting, capturing audio/video and streaming transcription (if enabled).
`leaving`	The bot is exiting the meeting (brief transitional state).
`processing`	The meeting has ended. The bot is uploading raw assets and preparing for transcription.
`transcribing`	The audio is being processed by the selected AI model (e.g., Whisper, Deepgram).
`finished`	All data is ready. Transcript and Recording URLs are available.

Terminal "Failed" Statuses

If a bot cannot reach the finished state, it will land in one of these terminal error states:

Status	Description
`not_admitted`	The bot reached the meeting but was never allowed inside. See Stop Reasons for details.
`bot_detected`	The platform blocked the bot. Note: This is not always terminal. Skribby automatically retries up to 3 times with new credentials/IPs. You may see the status toggle between `bot_detected` and `booting` during this process.
`auth_required`	The meeting is locked to specific users and the bot was not provided with Authentication.
`invalid_credentials`	Authentication was provided, but the platform rejected the email/password or ZAK token.
`invalid_api_key`	Transcription credentials (BYOK) were provided, but the transcription provider rejected the API key. See Transcription Credentials.
`failed`	A rare internal error occurred. Our team is automatically notified of these.

Stop Reasons

When a bot's status becomes finished or not_admitted, the stop_reason field provides the "Why."

Reasons for `not_admitted`

invalid_meeting_url: The URL provided doesn't point to a valid meeting.
call_already_finished: The meeting had already ended before the bot could join.
waiting_room_timeout: No one admitted the bot within the configured timeout (see waiting_room_timeout in stop_options).
request_denied: A human in the meeting explicitly clicked "Deny" when the bot asked to join.
host_in_another_meeting: The host is currently in another meeting and has not started this one yet (common in Zoom).
manually_stopped: You called the POST /bot/{id}/stop endpoint while the bot was in the waiting room.

Reasons for `finished`

kicked: A participant explicitly removed the bot from the active meeting.
meeting_ended: The host ended the meeting or everyone left.
last_person_detected: The bot left because it was the only participant remaining (configured in stop_options).
manually_stopped: You called the POST /bot/{id}/stop endpoint while the bot was in the meeting.
silence_detection_triggered: No one spoke for the configured duration.

Handling State Changes

We recommend using Webhooks to react to these changes. Specifically, listen for the status_update event to drive your UI:

// Example: Nudge user if bot is waiting
if (webhook.type === 'status_update' && webhook.data.new_status === 'joining') {
    sendUserPushNotification('Your bot is waiting to be admitted!');
}