HAhappyscribe
Bots

Create a bot

Dispatches a notetaker bot to a Zoom, Google Meet, or Microsoft Teams call. The bot records the call, creates a conversation, and generates a summary.

Returns 201 Created after the bot is dispatched. It usually joins within seconds but can take up to 3 minutes depending on availability.

A bot is one way of recording a meeting: it creates the meeting at once (meeting_id), and the meeting holds the results. The recording choices (language, recording_start, recording_mode, silence_alert, summary_language, summary_template) are written as the meeting's own policy; each one you leave out follows the member's and the workspace's policy.

Creation is deduplicated: a request matching an active bot returns the existing bot instead of dispatching a second one. When that bot was sent for another member, a request with member_id answers 409 bot_already_recording.

post/bots

Request

  • Base URL
    https://www.happyscribe.com/api/v1
  • Auth
    API key in header Authorization

Request body

workspace_idstring required

Workspace that owns the bot. The API-key user must be a member. A wks_ id; integer workspace ids are still accepted.

meeting_urlstring required

Zoom, Google Meet, or Microsoft Teams join URL. URLs without a scheme are normalized to HTTPS.

join_atstring date-time

Optional future ISO 8601 timestamp with a UTC offset at which the notetaker should join. If omitted, dispatch is immediate.

languagestring

Optional transcription language, auto or multi. See Languages.

member_idstring

Optional member whose meeting this is, beginning with mem_. The meeting is theirs (their meetings list, their policy, and they are its organizer). Without it the meeting is the workspace's.

bot_namestring

Display name of the notetaker in the call. Defaults to the workspace's brand kit.

bot_avatarstring

Base64-encoded JPEG, with or without a data: URI prefix, up to 256 KB, shown as the notetaker's picture. Defaults to the workspace's brand kit. Accepted on create, never returned.

welcome_messagestring nullable

Chat message posted when the notetaker joins. Send null to post nothing.

recording_start'on_join' | 'on_command'

When the notetaker starts recording.

  • on_join: as soon as it joins the call
  • on_command: when someone in the call asks it to
recording_mode'audio_and_video' | 'audio_only'

What the notetaker records.

  • audio_and_video: audio and video
  • audio_only: audio only
silence_alertboolean

Whether the notetaker posts an audible and chat alert after a long silence, in case it is recording nothing.

summary_languagestring

Language of the summary as a BCP-47 code. Defaults to the transcription language.

summary_templatestring

A custom summary template's tpl_ id, or the slug of a built-in template such as discovery_call.

Example request

{
  "workspace_id": "wks_01k6a2r9s8x7c2dvq3m5n6p4ab",
  "participants": [
    {
      "email": "carmen@example.com",
      "name": "Carmen"
    }
  ],
  "member_id": "mem_01k6a2r9s8x7c2dvq3m5n6p4ab"
}

Response

The bot was dispatched.

idstring

Stable typed bot ID beginning with bot_. Treat it as an opaque string.

objectstring

Always bot.

meeting_idstring

The meeting this bot records, beginning with mtg_. It exists from the moment the bot is queued; read its results with GET /meetings/{meeting_id}/results.

meeting_urlstring

Normalized URL supplied at creation. Treat as sensitive — it may contain credentials.

join_atstring date-time nullable

Requested ISO 8601 join time, or null for an immediate dispatch.

status'queued' | 'joining' | 'in_call' | 'processing' | 'completed' | 'failed' | 'cancelled'

Current lifecycle state:

  • queued: the provider accepted the bot and the notetaker is pending
  • joining: the notetaker is joining the call
  • in_call: the notetaker is in the call and recording
  • processing: the recording is being transcribed or summarized
  • completed: the transcript and summary are ready on the meeting
  • failed: the bot ended without a usable result
  • cancelled: the bot was cancelled
bot_namestring

Display name of the notetaker in the call.

welcome_messagestring nullable

Chat message the notetaker posts when it joins, or null when it posts none.

languagestring

Transcription language as a BCP-47 code, auto or multi. The meeting's effective_policy.transcription.language.

recording_start'on_join' | 'on_command'

When the notetaker starts recording. The meeting's effective_policy.recording.methods.bot.start.

  • on_join: as soon as it joins the call
  • on_command: when someone in the call asks it to
recording_mode'audio_and_video' | 'audio_only'

What the notetaker records. The meeting's effective_policy.recording.methods.bot.mode.

  • audio_and_video: audio and video
  • audio_only: audio only
silence_alertboolean

Whether the notetaker posts an audible and chat alert after a long silence, in case it is recording nothing. The meeting's effective_policy.recording.methods.bot.silence_detection.alert.

summary_languagestring nullable

Language of the summary as a BCP-47 code, or null to follow the transcription. The meeting's effective_policy.summary.language.

summary_templatestring nullable

The summary template that runs, a built-in slug or a custom template's tpl_ id. The meeting's effective_policy.summary.template.

metadataMetadata

Your own key-value pairs, for your ids and context. HappyScribe stores them, returns them on the object and in every webhook that carries it, and never acts on them. Up to 50 keys of up to 40 characters (no square brackets), values up to 500 characters. See metadata.

created_atstring date-time

When the bot was created.

ended_atstring date-time nullable

When the recording first became available. null until then, and for a bot that never recorded. Reprocessing does not change it.

reason'no_recording' | 'invalid_meeting_url' | 'bot_error' | 'transcription_failed'

Machine-readable failure reason. Present only for failed bots.

  • no_recording: the call ended without anything recorded
  • invalid_meeting_url: the meeting URL could not be joined
  • bot_error: the notetaker failed in the call
  • transcription_failed: the recording could not be transcribed
failure_messagestring nullable

Human-readable failure detail for debugging. Present only for failed bots. Do not match on its text; use reason.

Example response

{
  "id": "bot_01k0h4r9s8x7c2dvq3m5n6p4ab",
  "object": "bot",
  "meeting_id": "mtg_01k0h4r9s8x7c2dvq3m5n6p4ab",
  "meeting_url": "https://zoom.us/j/123456789",
  "join_at": "2026-07-20T14:00:00Z",
  "status": "queued",
  "bot_name": "Acme Notetaker",
  "welcome_message": "Recording this meeting for Acme",
  "language": "en",
  "recording_start": "on_join",
  "recording_mode": "audio_only",
  "silence_alert": true,
  "summary_language": "en",
  "summary_template": "discovery_call",
  "participants": [
    {
      "email": "carmen@example.com",
      "name": "Carmen"
    }
  ],
  "metadata": {
    "partner_meeting_id": "meeting-123"
  },
  "created_at": "2026-07-20T13:58:12Z",
  "ended_at": null
}

Changes

No recorded changes to this operation across all 1 revision of this API.