Skip to main content

​
Endpoint

POST /api/v1/bots

​
Authentication

Requires API key authentication via the Authorization header.
​
Authorization
string
required
Your API key in the format: Token YOUR_API_KEY_HERE
​
Content-Type
string
required
Must be application/json

​
Request Body

​
meeting_url
string
required
The URL of the meeting to join.Example: https://zoom.us/j/123?pwd=456
​
bot_name
string
required
The name of the bot.Example: My Bot
​
bot_image
object
The image for the bot’s profile picture.
​
type
string
required
Image content type. Currently only image/png is supported.
​
data
string
required
Base64 encoded PNG image data.
​
metadata
object
JSON object containing custom metadata to associate with the bot.Example: {"customer_id": "abc123", "user": "john_doe"}
​
bot_chat_message
object
Chat message the bot will send after joining the meeting.
​
to
string
Who to send the message to: everyone, specific_user, or everyone_but_host
​
to_user_uuid
string
The UUID of the user to send the message to. Required if to is specific_user.
​
message
string
required
The message text to send.
​
join_at
string
The time the bot should join the meeting. If not specified, the bot will attempt to join immediately.Format: ISO 8601 datetime (e.g., 2025-06-13T12:00:00Z)
​
calendar_event_id
string
The ID of the calendar event the bot should join.
​
deduplication_key
string
Optional key for deduplicating bots. If a bot with this key already exists in a non-terminal state, the new bot will not be created and an error will be returned.
​
webhooks
array
List of webhook subscriptions to create for this bot.Each item should have:
  • url (string): The webhook URL (must be HTTPS)
  • triggers (array): List of trigger types (e.g., bot.state_change, transcript.update)
​
transcription_settings
object
The transcription settings for the bot.Example: {"deepgram": {"language": "en"}}
​
recording_settings
object
The settings for the bot’s recording.
​
format
string
Format: mp4, mp3, or none. Defaults to mp4.
​
view
string
View: speaker_view, gallery_view, or speaker_view_no_sidebar. Defaults to speaker_view.
​
resolution
string
Resolution: 1080p or 720p. Defaults to 1080p.
​
voice_agent_settings
object
Settings for the voice agent that the bot should load.
​
url
string
URL of a website containing a voice agent.
​
screenshare_url
string
URL of a website to display via screenshare instead of webcam.
​
reserve_resources
boolean
Whether to reserve resources for starting a voice agent mid-meeting. Defaults to false.

​
Response

Returns the created bot object.
​
id
string
Unique identifier for the bot (e.g., bot_weIAju4OXNZkDTpZ)
​
meeting_url
string
The URL of the meeting the bot will join.
​
state
string
Current state of the bot (typically joining or scheduled).
​
events
array
Array of events that have occurred for this bot.
​
transcription_state
string
Current transcription state (typically not_started for new bots).
​
recording_state
string
Current recording state (typically not_started for new bots).
​
join_at
string
ISO 8601 timestamp when the bot will join the meeting.
​
deduplication_key
string
Deduplication key for the bot, if provided.
​
metadata
object
Custom metadata associated with the bot.

​
Example Request

curl -X POST 'https://api.attendee.dev/api/v1/bots' \
  -H 'Authorization: Token YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "meeting_url": "https://zoom.us/j/123?pwd=456",
    "bot_name": "My Bot",
    "metadata": {
      "customer_id": "abc123"
    },
    "transcription_settings": {
      "deepgram": {
        "language": "en"
      }
    }
  }'

​
Example Response

{
  "id": "bot_weIAju4OXNZkDTpZ",
  "meeting_url": "https://zoom.us/j/123?pwd=456",
  "state": "joining",
  "events": [
    {
      "type": "join_requested",
      "sub_type": null,
      "created_at": "2024-01-18T12:34:56Z"
    }
  ],
  "transcription_state": "not_started",
  "recording_state": "not_started",
  "join_at": "2024-01-18T12:34:56Z",
  "deduplication_key": null,
  "metadata": {
    "customer_id": "abc123"
  }
}

​
Error Codes

  • 201 - Bot created successfully
  • 400 - Invalid input (e.g., invalid meeting URL, missing required fields, bot with same deduplication key already exists)
  • 401 - Invalid or missing API key

Build docs developers (and LLMs) love

Get started for freeTalk to us