Create Bot

post https://us-east-1.recall.ai/api/v1/bot/

Create a new bot.

For more info on configuring bots:

⚠️
Meeting URL response shape
Meeting URL's are currently improperly reflected in the API spec for meeting URL's in responses. For proper meeting URL shapes in API responses, please see Meeting URL's.
meeting_url's that are provided as a parameter to the API are reflected accurately in the API spec as strings.

Body Params

meeting_url

string

required

The url of the meeting. For example, https://zoom.us/j/123?pwd=456. This field will be cleared a few days after the bot has joined a call.

bot_name

string

length ≤ 100

Defaults to Meeting Notetaker

The name of the bot that will be displayed in the call.
(Note: Authenticated Google Meet bots will use the Google account name and this field will be ignored.)

join_at

date-time | null

The time at which the bot will join the call, formatted in ISO 8601. This field can only be read from scheduled bots that have not yet joined a call. Once a bot has joined a call, it's join_at will be cleared.

real_time_transcription

object | null

The settings for real-time transcription.

real_time_media

object | null

The settings for real-time media output.

transcription_options

object | null

recording_mode

string

Defaults to speaker_view

speaker_view - speaker_view
gallery_view - gallery_view
gallery_view_v2 - gallery_view_v2
audio_only - audio_only

recording_mode_options

object | null

Additional options for recording mode.

include_bot_in_recording

object

output_media

object | null

Settings for the bot output media.

automatic_video_output

object | null

Settings for the bot to output video. Image should be 16:9. Recommended resolution is 640x360.

automatic_audio_output

object | null

(BETA) Settings for the bot to output audio.

chat

object | null

(BETA) Settings for the bot to send chat messages.
(Note: Chat functionality is only supported for Zoom, Google Meet and Microsoft Teams currently.)

automatic_leave

object | null

variant

object | null

Configure bot variants per meeting platforms, e.g. {"zoom": "web_4_core"}.

zoom

object | null

Zoom specific parameters

google_meet

object | null

Google Meet specific parameters

metadata

object

Responses

Response body

object

uuid

required

meeting_url

string

required

The url of the meeting. For example, https://zoom.us/j/123?pwd=456. This field will be cleared a few days after the bot has joined a call.

bot_name

string

length ≤ 100

Defaults to Meeting Notetaker

The name of the bot that will be displayed in the call.
(Note: Authenticated Google Meet bots will use the Google account name and this field will be ignored.)

join_at

date-time | null

video_url

uri

required

A URL where the video recorded by the bot can be downloaded. This is null while the recording is in progress, and will be populated when the recording is completed. The returned URL is valid for 6 hours from the API call. A fresh URL can be obtained at any point by calling the API again.

media_retention_end

date-time

required

After this date the video and transcript will be deleted. This date is 7 days from when the recording ended.

status_changes

array of objects

required

status_changes*

object

code

string

required

message

string

required

created_at

date-time

required

sub_code

string

required

meeting_metadata

object | null

required

title

string

required

The title of the meeting the bot has joined.

zoom_meeting_uuid

string | null

required

The Zoom-formatted UUID of the Zoom meeting the bot has joined. This field is Zoom-only.

slack_channel_id

string | null

required

The Slack channel ID of the Slack channel the bot has joined. This field is Slack-only.

slack_huddle_id

string | null

required

The Slack huddle ID of the Slack huddle the bot has joined. This field is Slack-only.

meeting_participants

array of objects

required

meeting_participants*

object

integer

required

name

string

required

events

array of objects

required

events*

object

code

string

required

created_at

date-time

required

is_host

boolean

required

platform

string

required

extra_data

object

required

real_time_transcription

object | null

The settings for real-time transcription.

destination_url

uri

required

partial_results

boolean

Defaults to false

enhanced_diarization

boolean

Defaults to false

real_time_media

object | null

The settings for real-time media output.

rtmp_destination_url

string

websocket_video_destination_url

string

websocket_audio_destination_url

string

websocket_speaker_timeline_destination_url

string

websocket_speaker_timeline_exclude_null_speaker

boolean

Defaults to true

Set to false to include null active speaker events in the speaker timeline websocket. Defaults to true.

webhook_call_events_destination_url

string

Receive webhooks for in call events('bot.participant_join'/'bot.participant_leave'/'bot.active_speaker_notify')

webhook_chat_messages_destination_url

string

Receive webhooks for chat messages read by the bot in the meeting(only Zoom & Google Meet supported)

transcription_options

object | null

provider

string

required

deepgram - Deepgram
assembly_ai_async_chunked - Assemblyai Async Chunked
assembly_ai - Assemblyai
rev - Rev
aws_transcribe - Aws Transcribe
speechmatics - Speechmatics
gladia - Gladia
gladia_v2 - Gladia V2
meeting_captions - Meeting Captions
none - None

deepgram assembly_ai_async_chunked assembly_ai rev aws_transcribe speechmatics gladia gladia_v2 meeting_captions none

assembly_ai_async_chunked

object

Docs: https://www.assemblyai.com/docs/api-reference/transcripts/submit

assembly_ai

object

Docs: https://www.assemblyai.com/docs/api-reference/streaming/realtime

deepgram

object

Docs: https://developers.deepgram.com/reference/streaming

gladia

object

Docs: https://docs.gladia.io/reference/live-audio

gladia_v2

object

Docs: https://docs.gladia.io/api-reference/v2/live/init

rev

object

Docs: https://docs.rev.ai/api/streaming/requests/

aws_transcribe

object

You must specify either:

language_code(e.g en-US) OR
Set language_identification to true AND specify language_options(e.g en-US,fr-FR,es-US,de-DE,it-IT).
Docs: https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartStreamTranscription.html

speechmatics

object

You must specify language (e.g en)
Docs: https://docs.speechmatics.com/rt-api-ref#transcription-config

recording_mode

string

Defaults to speaker_view

speaker_view - speaker_view
gallery_view - gallery_view
gallery_view_v2 - gallery_view_v2
audio_only - audio_only

speaker_view gallery_view gallery_view_v2 audio_only

recording_mode_options

object | null

Additional options for recording mode.

participant_video_when_screenshare

string

Defaults to overlap

hide - hide
beside - beside
overlap - overlap

hide beside overlap

start_recording_on

string

Defaults to call_join

call_join - call_join
participant_join - participant_join
participant_speak - participant_speak
manual - manual

call_join participant_join participant_speak manual

include_bot_in_recording

object

audio

boolean

Defaults to false

Whether to record audio from the bot.

recordings

array of objects

required

recordings*

object

uuid

required

created_at

date-time

required

started_at

date-time | null

completed_at

date-time | null

output_media

object | null

Settings for the bot output media.

camera

screenshare

automatic_video_output

object | null

Settings for the bot to output video. Image should be 16:9. Recommended resolution is 640x360.

in_call_recording

object

The video that will be automatically output when the bot is in the in_call_recording state.

in_call_not_recording

object

The video that will be automatically output when the bot is in the in_call_not_recording state. If not specified the bot will fallback to in_call_recording output if available.

automatic_audio_output

object | null

(BETA) Settings for the bot to output audio.

in_call_recording

object

required

chat

object | null

(BETA) Settings for the bot to send chat messages.
(Note: Chat functionality is only supported for Zoom, Google Meet and Microsoft Teams currently.)

on_bot_join

object

on_participant_join

object

automatic_leave

object | null

waiting_room_timeout

integer

≥ 30

Defaults to 1200

The number of seconds after which the bot will automatically leave the call, if it has not been let in from the waiting room.Note that this has a max value of 600 seconds for Google Meet and 1800 for Microsoft Teams.

noone_joined_timeout

integer

≥ 30

Defaults to 1200

The number of seconds after which the bot will automatically leave the call, if it has joined the meeting but no other participant has joined.

everyone_left_timeout

integer

≥ 1

Defaults to 2

The number of seconds after which the bot will automatically leave the call, if there were other participants in the call who have all left.

in_call_not_recording_timeout

integer

≥ 1

Defaults to 3600

The number of seconds after which the bot will automatically leave the call, if it has joined the call and is not recording.This includes all periods when the bot is not recording, even if the bot has recorded previously.

in_call_recording_timeout

integer

≥ 1

The number of seconds after which the bot will automatically leave the call, if it has joined the call and started recording it. This can be used to enforce a maximum recording time limit for a bot. There is no default value for this parameter, meaning a bot will continue to record for as long as the meeting lasts.

recording_permission_denied_timeout

integer

≥ 1

Defaults to 30

The number of seconds after which the bot will automatically leave the call, if it has joined the call but has not started recording. For e.g This can occur due to bot being denied permission to record(Zoom meetings).

silence_detection

object

bot_detection

object

variant

object | null

Configure bot variants per meeting platforms, e.g. {"zoom": "web_4_core"}.

zoom

string

web - web
web_4_core - web_4_core
native - native

web web_4_core native

google_meet

string

web - web
web_4_core - web_4_core

web web_4_core

microsoft_teams

string

web - web
web_4_core - web_4_core

web web_4_core

calendar_meetings

array of objects

required

The calendar meetings associated with this bot. This field is populated only for bots that are dispatched via Calendar V1 API integration.

calendar_meetings*

object

uuid

required

start_time

date-time

required

end_time

date-time

required

calendar_user

object

required

zoom

object | null

Zoom specific parameters

join_token_url

uri

A URL which Recall will make a GET request to, in order to retrieve the Zoom Join Token for Local Recording, which the Zoom bot uses to automatically record. This token can be generated through the Zoom API. Docs: https://marketplace.zoom.us/docs/api-reference/zoom-api/methods/#operation/meetingLocalRecordingJoinToken

zak_url

uri

A URL which Recall will make GET request to, in order to retrieve the ZAK. The V1 Zoom bot uses this to join meetings that require authentication to join.This token can be generated through the Zoom API. Docs: https://marketplace.zoom.us/docs/api-reference/zoom-api/methods/#operation/userZak

user_email

string

This is only required for registration-required webinars. This should be the email address registered for the webinar.

google_meet

object | null

Google Meet specific parameters

login_required

boolean | null

Specify if the bot should always login to Google before joining the meeting. This value will override the default value set on bot's Google Meet login credentials on the account. When set to 'false', the bot will only login if required by the meeting.

google_login_group_id

uuid | null

The ID of the google login group to use for this meeting. If specified, the 'login_required' field value will be ignored and bot will use the 'login_mode' value on the login group.

slack_team

object | null

required

uuid

required

metadata

object

required

Has additional fields

metadata

object

Has additional fields

recording

string

required

Language

Credentials

Header

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://us-east-1.recall.ai/api/v1/bot/ \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

⚠️Meeting URL response shape

201

507

⚠️
Meeting URL response shape