Bot Types

​

Overview

​

Core Types

​

BotStatus

type BotStatus = 
  | "ready"
  | "joining_call"
  | "in_waiting_room"
  | "in_call_not_recording"
  | "recording_permission_allowed"
  | "recording_permission_denied"
  | "in_call_recording"
  | "recording_done"
  | "call_ended"
  | "done"
  | "fatal"
  | "media_expired"
  | "analysis_done"
  | "analysis_failed";

1. ready - Bot is initialized and ready to join a meeting
2. joining_call - Bot is attempting to join the meeting
3. in_waiting_room - Bot is in the meeting’s waiting room (if enabled)
4. in_call_not_recording - Bot has joined but is not yet recording
5. recording_permission_allowed - Host has granted recording permission
6. recording_permission_denied - Host has denied recording permission
7. in_call_recording - Bot is actively recording the meeting
8. recording_done - Recording has completed
9. call_ended - The meeting has ended
10. done - Bot has finished all processing
11. fatal - An unrecoverable error occurred
12. media_expired - Recorded media has expired
13. analysis_done - Post-meeting analysis is complete
14. analysis_failed - Post-meeting analysis failed

​

Request Parameters

​

CreateParams

interface CreateParams extends MeetingConfigurationParams {
  meeting_url: string;
  [key: string]: any;
}

• meeting_url (required): The URL of the meeting the bot should join
• Inherits all properties from MeetingConfigurationParams

​

MeetingConfigurationParams

interface MeetingConfigurationParams {
  bot_name?: string;
  join_at?: Date;
  real_time_transcription?: RealTimeTranscription;
  real_time_media?: RealTimeMedia;
  transcription_options?: TranscriptionOptions;
  recording_mode?: string;
  recording_mode_options?: RecordingModeOptions;
  automatic_video_output?: AutomaticVideoOutput;
  [key: string]: any;
}

• bot_name: Display name for the bot in the meeting
• join_at: Scheduled time for the bot to join (if not immediate)
• real_time_transcription: Configuration for live transcription streaming
• real_time_media: Configuration for real-time media streaming
• transcription_options: Provider-specific transcription settings
• recording_mode: Recording behavior mode
• recording_mode_options: Additional recording mode configuration
• automatic_video_output: Visual display settings for the bot

​

UpdateScheduledParams

interface UpdateScheduledParams extends MeetingConfigurationParams {
  id: string;
  meeting_url?: string;
}

• id (required): The bot’s unique identifier
• meeting_url: Updated meeting URL (optional)
• Inherits all properties from MeetingConfigurationParams

​

BaseBotParams

interface BaseBotParams {
  id: string;
}

​

ListQueryParams

interface ListQueryParams {
  join_at_after?: Date;
  join_at_before?: Date;
  meeting_url?: string;
  page?: number;
  status?: BotStatus;
}

• join_at_after: Filter bots that joined after this date
• join_at_before: Filter bots that joined before this date
• meeting_url: Filter bots by meeting URL
• page: Page number for pagination
• status: Filter bots by their current status

​

GetTranscriptParams

interface GetTranscriptParams extends BaseBotParams {
  enhanced_diarization?: boolean;
}

• id: Bot identifier (inherited from BaseBotParams)
• enhanced_diarization: Enable enhanced speaker identification (optional)

​

ListChatMessagesParams

interface ListChatMessagesParams extends BaseBotParams {
  cursor?: string;
  ordering?: string;
}

• id: Bot identifier (inherited from BaseBotParams)
• cursor: Pagination cursor for fetching next page
• ordering: Sort order for messages

​

OutputAudioParams

interface OutputAudioParams extends BaseBotParams {
  kind: string;
  b64_data: string;
}

• id: Bot identifier (inherited from BaseBotParams)
• kind: Type of audio output
• b64_data: Base64-encoded audio data

​

Response Types

​

CreateResponse

interface CreateResponse {
  id: string;
  meeting_url: {
    meeting_id: string;
    meeting_password: string | undefined;
    platform: string;
  };
  join_at: string;
}

• id: Unique identifier for the created bot
• meeting_url: Parsed meeting information
  • meeting_id: The platform-specific meeting identifier
  • meeting_password: Meeting password if required
  • platform: Meeting platform (e.g., “zoom”, “google_meet”, “teams”)
• join_at: ISO timestamp when the bot will/did join

​

Real-Time Configuration

​

RealTimeTranscription

interface RealTimeTranscription {
  destination_url?: string;
  partial_results?: boolean;
  enhanced_diarization?: boolean;
}

• destination_url: Webhook URL to receive transcription events
• partial_results: Include partial/interim transcription results
• enhanced_diarization: Enable advanced speaker identification

​

RealTimeMedia

interface RealTimeMedia {
  rtmp_destination_url?: string;
  websocket_video_destination_url?: string;
  websocket_audio_destination_url?: string;
  websocket_speaker_timeline_destionation_url?: string;
  websocket_speaker_timeline_exclude_null_speaker?: boolean;
  webhook_call_events_destination_url?: string;
  webhook_chat_messages_destination_url?: string;
}

• rtmp_destination_url: RTMP endpoint for video streaming
• websocket_video_destination_url: WebSocket endpoint for video frames
• websocket_audio_destination_url: WebSocket endpoint for audio streams
• websocket_speaker_timeline_destionation_url: WebSocket endpoint for speaker timeline events
• websocket_speaker_timeline_exclude_null_speaker: Filter out unknown speakers from timeline
• webhook_call_events_destination_url: Webhook URL for call events (join, leave, etc.)
• webhook_chat_messages_destination_url: Webhook URL for chat messages

​

Recording Configuration

​

TranscriptionOptions

interface TranscriptionOptions {
  provider: string;
  [key: string]: any;
}

• provider: Transcription provider identifier
• Additional provider-specific options can be included

​

RecordingModeOptions

interface RecordingModeOptions {
  participant_video_when_screenshare?: string;
  start_recording_on?: string;
}

• participant_video_when_screenshare: How to handle participant video during screen sharing
• start_recording_on: Event or condition to trigger recording start

​

Visual Configuration

​

AutomaticVideoOutput

interface AutomaticVideoOutput {
  in_call_recording?: InCallDisplay;
  in_call_not_recording?: InCallDisplay;
}

• in_call_recording: Display configuration when actively recording
• in_call_not_recording: Display configuration when not recording

​

InCallDisplay

interface InCallDisplay {
  kind: string;
  b64_data: string;
}

• kind: Type of display (e.g., “image”)
• b64_data: Base64-encoded image or display data

​

Example Usage

​

Creating a Bot with Full Configuration

import { RecallAI } from '@recall-ai/sdk';
import type { CreateParams } from '@recall-ai/sdk';

const recall = new RecallAI({ apiKey: 'your-api-key' });

const params: CreateParams = {
  meeting_url: 'https://zoom.us/j/123456789',
  bot_name: 'Meeting Recorder',
  recording_mode: 'speaker_view',
  real_time_transcription: {
    destination_url: 'https://your-app.com/transcription-webhook',
    partial_results: true,
    enhanced_diarization: true
  },
  transcription_options: {
    provider: 'assembly_ai'
  }
};

const bot = await recall.bot.create(params);
console.log('Bot created:', bot.id);

​

Listing Bots with Filters

import type { ListQueryParams, BotStatus } from '@recall-ai/sdk';

const filters: ListQueryParams = {
  status: 'in_call_recording',
  join_at_after: new Date('2024-01-01'),
  page: 1
};

const bots = await recall.bot.list(filters);

​

Getting Transcript with Enhanced Diarization

import type { GetTranscriptParams } from '@recall-ai/sdk';

const params: GetTranscriptParams = {
  id: 'bot-123',
  enhanced_diarization: true
};

const transcript = await recall.bot.getTranscript(params);