diff --git a/content/docs/api-v2/reference/bots/batchCreateBots.mdx b/content/docs/api-v2/reference/bots/batchCreateBots.mdx index b9275543..4abb4acc 100644 --- a/content/docs/api-v2/reference/bots/batchCreateBots.mdx +++ b/content/docs/api-v2/reference/bots/batchCreateBots.mdx @@ -12,7 +12,7 @@ _openapi: Processes each bot creation request sequentially (index 0, 1, 2...). Each item is validated and processed independently. If some bots fail to create, the request still returns 201 with a `data` array containing successful creations and an `errors` array containing failures. Each error includes the `index` of the failed item in the original request array. - **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, BYOK transcription check, daily bot cap check, token availability check, and deduplication lock acquisition. + **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, transcription key availability, daily bot cap check, token availability check, and deduplication lock acquisition. **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully created bots with their `bot_id` and preserved `extra` metadata. The `errors` array contains failed items with `index`, `code`, `message`, `details`, and preserved `extra` metadata. @@ -54,7 +54,7 @@ Create multiple bots in a single request with partial success support. Processes each bot creation request sequentially (index 0, 1, 2...). Each item is validated and processed independently. If some bots fail to create, the request still returns 201 with a `data` array containing successful creations and an `errors` array containing failures. Each error includes the `index` of the failed item in the original request array. - **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, BYOK transcription check, daily bot cap check, token availability check, and deduplication lock acquisition. + **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, transcription key availability, daily bot cap check, token availability check, and deduplication lock acquisition. **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully created bots with their `bot_id` and preserved `extra` metadata. The `errors` array contains failed items with `index`, `code`, `message`, `details`, and preserved `extra` metadata. diff --git a/content/docs/api-v2/reference/bots/batchCreateScheduledBots.mdx b/content/docs/api-v2/reference/bots/batchCreateScheduledBots.mdx index d2a2bca4..fcabf083 100644 --- a/content/docs/api-v2/reference/bots/batchCreateScheduledBots.mdx +++ b/content/docs/api-v2/reference/bots/batchCreateScheduledBots.mdx @@ -13,7 +13,7 @@ _openapi: Processes each scheduled bot creation request sequentially. Each item is validated and processed independently. Token reservation and daily bot cap checks are NOT performed at creation time - they are performed when each bot actually joins the meeting. - **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, BYOK transcription check, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time. + **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, transcription key availability, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time. **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully scheduled bots with their `bot_id` and preserved `extra` metadata. @@ -22,7 +22,6 @@ _openapi: **Error Scenarios:** - Validation errors: Invalid join time, invalid meeting URL, invalid configuration - Platform detection failures: `INVALID_MEETING_PLATFORM` - - BYOK not enabled: `BYOK_TRANSCRIPTION_NOT_ENABLED_ON_PLAN` - System failures: `BOT_CREATE_FAILED` **Note:** Daily bot cap and token availability are checked when each bot joins, not at creation time. If these checks fail at join time, the bot will transition to `failed` status and send a failure webhook. @@ -59,7 +58,7 @@ Create multiple scheduled bots in a single request with partial success support. Processes each scheduled bot creation request sequentially. Each item is validated and processed independently. Token reservation and daily bot cap checks are NOT performed at creation time - they are performed when each bot actually joins the meeting. - **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, BYOK transcription check, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time. + **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, transcription key availability, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time. **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully scheduled bots with their `bot_id` and preserved `extra` metadata. @@ -68,7 +67,6 @@ Create multiple scheduled bots in a single request with partial success support. **Error Scenarios:** - Validation errors: Invalid join time, invalid meeting URL, invalid configuration - Platform detection failures: `INVALID_MEETING_PLATFORM` - - BYOK not enabled: `BYOK_TRANSCRIPTION_NOT_ENABLED_ON_PLAN` - System failures: `BOT_CREATE_FAILED` **Note:** Daily bot cap and token availability are checked when each bot joins, not at creation time. If these checks fail at join time, the bot will transition to `failed` status and send a failure webhook. diff --git a/content/docs/api-v2/reference/bots/createBot.mdx b/content/docs/api-v2/reference/bots/createBot.mdx index f7ddfe62..3a9cc7fb 100644 --- a/content/docs/api-v2/reference/bots/createBot.mdx +++ b/content/docs/api-v2/reference/bots/createBot.mdx @@ -50,10 +50,22 @@ _openapi: bot_image_config: Configuration for how bot avatar images are displayed. Only relevant when multiple images are provided in bot_image. - - content: |- - bot_name: The name of the bot. + - content: >- + bot_name: The name requested for the bot. + + + This name is displayed for anonymous joins. For an authenticated + Microsoft Teams join using `teams_config`, Microsoft Teams ignores + this value and displays the signed-in Microsoft 365 account's display + name and profile instead. + - This name will be displayed as the bot's name in the meeting. + For a Microsoft Teams meeting the name must be one Teams accepts for a + guest, or the request is rejected: at most 50 characters; only + letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; + and no leading, trailing or consecutive periods. This applies to + authenticated joins too, because a failed sign-in falls back to + joining as a guest under this name. - content: callback_config - content: >- callback_enabled: Enable callback for this bot. When enabled, the @@ -151,9 +163,13 @@ _openapi: signed-in Microsoft account. - - credential_id: pin a specific login. + Microsoft Teams displays the selected account's Microsoft 365 name and + profile; `bot_name` is ignored for the authenticated join. - - email_group: pool selector (preferred — takes priority). + + - credential_id: pin a specific login and display identity. + + - email_group: least-loaded pool selector (takes priority). - fallback: 'fail' (default) or 'anonymous' on saturation. @@ -166,7 +182,7 @@ _openapi: participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard - cap on total recording time (up to 6 hours). + cap on total recording time (up to 12 hours). - content: >- timeout_config.grace_period: The grace period in seconds at the start of the meeting during which no timeout conditions (waiting room, no @@ -183,7 +199,7 @@ _openapi: When null, the default 4-hour internal timeout applies. - Range: 7200–21600 seconds (2–6 hours) + Range: 7200–43200 seconds (2–12 hours) - content: >- timeout_config.no_one_joined_timeout: The timeout in seconds for the bot to wait for participants to join before leaving the meeting. diff --git a/content/docs/api-v2/reference/bots/createScheduledBot.mdx b/content/docs/api-v2/reference/bots/createScheduledBot.mdx index aeae8f05..b63fa579 100644 --- a/content/docs/api-v2/reference/bots/createScheduledBot.mdx +++ b/content/docs/api-v2/reference/bots/createScheduledBot.mdx @@ -49,10 +49,22 @@ _openapi: bot_image_config: Configuration for how bot avatar images are displayed. Only relevant when multiple images are provided in bot_image. - - content: |- - bot_name: The name of the bot. + - content: >- + bot_name: The name requested for the bot. + + + This name is displayed for anonymous joins. For an authenticated + Microsoft Teams join using `teams_config`, Microsoft Teams ignores + this value and displays the signed-in Microsoft 365 account's display + name and profile instead. + - This name will be displayed as the bot's name in the meeting. + For a Microsoft Teams meeting the name must be one Teams accepts for a + guest, or the request is rejected: at most 50 characters; only + letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; + and no leading, trailing or consecutive periods. This applies to + authenticated joins too, because a failed sign-in falls back to + joining as a guest under this name. - content: callback_config - content: >- callback_enabled: Enable callback for this bot. When enabled, the @@ -150,9 +162,13 @@ _openapi: signed-in Microsoft account. - - credential_id: pin a specific login. + Microsoft Teams displays the selected account's Microsoft 365 name and + profile; `bot_name` is ignored for the authenticated join. - - email_group: pool selector (preferred — takes priority). + + - credential_id: pin a specific login and display identity. + + - email_group: least-loaded pool selector (takes priority). - fallback: 'fail' (default) or 'anonymous' on saturation. @@ -165,7 +181,7 @@ _openapi: participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard - cap on total recording time (up to 6 hours). + cap on total recording time (up to 12 hours). - content: >- timeout_config.grace_period: The grace period in seconds at the start of the meeting during which no timeout conditions (waiting room, no @@ -182,7 +198,7 @@ _openapi: When null, the default 4-hour internal timeout applies. - Range: 7200–21600 seconds (2–6 hours) + Range: 7200–43200 seconds (2–12 hours) - content: >- timeout_config.no_one_joined_timeout: The timeout in seconds for the bot to wait for participants to join before leaving the meeting. diff --git a/content/docs/api-v2/reference/bots/updateScheduledBot.mdx b/content/docs/api-v2/reference/bots/updateScheduledBot.mdx index 36da45c8..a72332ba 100644 --- a/content/docs/api-v2/reference/bots/updateScheduledBot.mdx +++ b/content/docs/api-v2/reference/bots/updateScheduledBot.mdx @@ -51,10 +51,22 @@ _openapi: bot_image_config: Configuration for how bot avatar images are displayed. Only relevant when multiple images are provided in bot_image. - - content: |- - bot_name: The name of the bot. + - content: >- + bot_name: The name requested for the bot. + + + This name is displayed for anonymous joins. For an authenticated + Microsoft Teams join using `teams_config`, Microsoft Teams ignores + this value and displays the signed-in Microsoft 365 account's display + name and profile instead. + - This name will be displayed as the bot's name in the meeting. + For a Microsoft Teams meeting the name must be one Teams accepts for a + guest, or the request is rejected: at most 50 characters; only + letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; + and no leading, trailing or consecutive periods. This applies to + authenticated joins too, because a failed sign-in falls back to + joining as a guest under this name. - content: callback_config - content: >- callback_enabled: Enable callback for this bot. When enabled, the @@ -161,9 +173,13 @@ _openapi: signed-in Microsoft account. - - credential_id: pin a specific login. + Microsoft Teams displays the selected account's Microsoft 365 name and + profile; `bot_name` is ignored for the authenticated join. - - email_group: pool selector (preferred — takes priority). + + - credential_id: pin a specific login and display identity. + + - email_group: least-loaded pool selector (takes priority). - fallback: 'fail' (default) or 'anonymous' on saturation. @@ -176,7 +192,7 @@ _openapi: participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard - cap on total recording time (up to 6 hours). + cap on total recording time (up to 12 hours). - content: >- timeout_config.grace_period: The grace period in seconds at the start of the meeting during which no timeout conditions (waiting room, no @@ -193,7 +209,7 @@ _openapi: When null, the default 4-hour internal timeout applies. - Range: 7200–21600 seconds (2–6 hours) + Range: 7200–43200 seconds (2–12 hours) - content: >- timeout_config.no_one_joined_timeout: The timeout in seconds for the bot to wait for participants to join before leaving the meeting. diff --git a/content/docs/api-v2/reference/calendars/createCalendarBot.mdx b/content/docs/api-v2/reference/calendars/createCalendarBot.mdx index 11cd01e9..c58a085c 100644 --- a/content/docs/api-v2/reference/calendars/createCalendarBot.mdx +++ b/content/docs/api-v2/reference/calendars/createCalendarBot.mdx @@ -39,10 +39,22 @@ _openapi: bot_image_config: Configuration for how bot avatar images are displayed. Only relevant when multiple images are provided in bot_image. - - content: |- - bot_name: The name of the bot. + - content: >- + bot_name: The name requested for the bot. + + + This name is displayed for anonymous joins. For an authenticated + Microsoft Teams join using `teams_config`, Microsoft Teams ignores + this value and displays the signed-in Microsoft 365 account's display + name and profile instead. + - This name will be displayed as the bot's name in the meeting. + For a Microsoft Teams meeting the name must be one Teams accepts for a + guest, or the request is rejected: at most 50 characters; only + letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; + and no leading, trailing or consecutive periods. This applies to + authenticated joins too, because a failed sign-in falls back to + joining as a guest under this name. - content: callback_config - content: >- callback_enabled: Enable callback for this bot. When enabled, the @@ -130,9 +142,13 @@ _openapi: signed-in Microsoft account. - - credential_id: pin a specific login. + Microsoft Teams displays the selected account's Microsoft 365 name and + profile; `bot_name` is ignored for the authenticated join. - - email_group: pool selector (preferred — takes priority). + + - credential_id: pin a specific login and display identity. + + - email_group: least-loaded pool selector (takes priority). - fallback: 'fail' (default) or 'anonymous' on saturation. @@ -145,7 +161,7 @@ _openapi: participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard - cap on total recording time (up to 6 hours). + cap on total recording time (up to 12 hours). - content: >- timeout_config.grace_period: The grace period in seconds at the start of the meeting during which no timeout conditions (waiting room, no @@ -162,7 +178,7 @@ _openapi: When null, the default 4-hour internal timeout applies. - Range: 7200–21600 seconds (2–6 hours) + Range: 7200–43200 seconds (2–12 hours) - content: >- timeout_config.no_one_joined_timeout: The timeout in seconds for the bot to wait for participants to join before leaving the meeting. diff --git a/content/docs/api-v2/reference/calendars/updateCalendarBot.mdx b/content/docs/api-v2/reference/calendars/updateCalendarBot.mdx index f7e39a85..9ac72226 100644 --- a/content/docs/api-v2/reference/calendars/updateCalendarBot.mdx +++ b/content/docs/api-v2/reference/calendars/updateCalendarBot.mdx @@ -62,10 +62,22 @@ _openapi: bot_image_config: Configuration for how bot avatar images are displayed. Only relevant when multiple images are provided in bot_image. - - content: |- - bot_name: The name of the bot. + - content: >- + bot_name: The name requested for the bot. + + + This name is displayed for anonymous joins. For an authenticated + Microsoft Teams join using `teams_config`, Microsoft Teams ignores + this value and displays the signed-in Microsoft 365 account's display + name and profile instead. + - This name will be displayed as the bot's name in the meeting. + For a Microsoft Teams meeting the name must be one Teams accepts for a + guest, or the request is rejected: at most 50 characters; only + letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; + and no leading, trailing or consecutive periods. This applies to + authenticated joins too, because a failed sign-in falls back to + joining as a guest under this name. - content: >- callback_config: The callback configuration for the bot. @@ -242,9 +254,13 @@ _openapi: signed-in Microsoft account. - - credential_id: pin a specific login. + Microsoft Teams displays the selected account's Microsoft 365 name and + profile; `bot_name` is ignored for the authenticated join. - - email_group: pool selector (preferred — takes priority). + + - credential_id: pin a specific login and display identity. + + - email_group: least-loaded pool selector (takes priority). - fallback: 'fail' (default) or 'anonymous' on saturation. @@ -257,7 +273,7 @@ _openapi: participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard - cap on total recording time (up to 6 hours). + cap on total recording time (up to 12 hours). - content: >- timeout_config.grace_period: The grace period in seconds at the start of the meeting during which no timeout conditions (waiting room, no @@ -274,7 +290,7 @@ _openapi: When null, the default 4-hour internal timeout applies. - Range: 7200–21600 seconds (2–6 hours) + Range: 7200–43200 seconds (2–12 hours) - content: >- timeout_config.no_one_joined_timeout: The timeout in seconds for the bot to wait for participants to join before leaving the meeting. @@ -337,7 +353,7 @@ _openapi: gladia, deepgram, assemblyai, speechmatics, soniox - `api_key`: Your own API key for the provider (BYOK - available on - Pro plans and above) + all plans) - `region`: Provider region (e.g. "eu", "us"). Required for some providers like Speechmatics diff --git a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx index 298be72c..ef42743d 100644 --- a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx +++ b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx @@ -24,11 +24,10 @@ _openapi: **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. - 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". - 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. - 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. + 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". + 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. @@ -115,11 +114,10 @@ Create a meet workspace — the parent resource that holds your SAML cert + priv **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. - 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". - 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. - 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. + 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". + 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. diff --git a/content/docs/api-v2/reference/webhooks/botwebhookchatstatus.mdx b/content/docs/api-v2/reference/webhooks/botwebhookchatstatus.mdx new file mode 100644 index 00000000..d3a39e1f --- /dev/null +++ b/content/docs/api-v2/reference/webhooks/botwebhookchatstatus.mdx @@ -0,0 +1,58 @@ +--- +title: Bot Chat Status +description: Bot Chat Status payload structure +--- + + + +## Payload Structure + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `data` | object | Yes | | +| `event` | string | Yes | The webhook event type | +| `extra` | object | null | Yes | Additional metadata provided when creating the bot. This is user-defined data that can be used for correlation or tracking | + +## Field Details + +- **`data`** (object) **Required** + + Properties: + - **`available`** (boolean) **Required** + Whether the bot can send and receive chat in this meeting + + - **`bot_id`** (string) **Required** + The UUID of the bot this chat status refers to + + - **`event_id`** (string (uuid) | null) **Required** + The UUID of the calendar event series. Null when the bot was not created from a calendar event + + - **`reason`** ("organizer_disabled" | "panel_not_attached" | "send_failed" | null) **Required** + Why chat is unavailable. Null when available is true + + - **`sent_at`** (string (date-time)) **Required** + ISO 8601 timestamp when this webhook was sent + + +- **`event`** (string) **Required** + The webhook event type + +- **`extra`** (object | null) **Required** + Additional metadata provided when creating the bot. This is user-defined data that can be used for correlation or tracking + + +## Example + +```json +{ + "data": { + "available": true, + "bot_id": "examplebot_id", + "event_id": null, + "reason": null, + "sent_at": "examplesent_at" + }, + "event": "exampleevent", + "extra": null +} +``` diff --git a/content/docs/api-v2/reference/webhooks/index.mdx b/content/docs/api-v2/reference/webhooks/index.mdx index 6e18d317..c5176d4c 100644 --- a/content/docs/api-v2/reference/webhooks/index.mdx +++ b/content/docs/api-v2/reference/webhooks/index.mdx @@ -9,6 +9,7 @@ This section contains reference documentation for all webhook payload structures ## Bot Webhooks - [Bot Webhook Chat Message](/docs/api-v2/reference/webhooks/botwebhookchatmessage) +- [Bot Webhook Chat Status](/docs/api-v2/reference/webhooks/botwebhookchatstatus) - [Bot Webhook Completed](/docs/api-v2/reference/webhooks/botwebhookcompleted) - [Bot Webhook Failed](/docs/api-v2/reference/webhooks/botwebhookfailed) - [Bot Webhook Status Change](/docs/api-v2/reference/webhooks/botwebhookstatuschange) diff --git a/content/docs/api-v2/reference/webhooks/meta.json b/content/docs/api-v2/reference/webhooks/meta.json index fd7cd3d8..2e2efd70 100644 --- a/content/docs/api-v2/reference/webhooks/meta.json +++ b/content/docs/api-v2/reference/webhooks/meta.json @@ -2,6 +2,7 @@ "title": "Webhooks", "pages": [ "botwebhookchatmessage", + "botwebhookchatstatus", "botwebhookcompleted", "botwebhookfailed", "botwebhookstatuschange", diff --git a/content/docs/api/reference/webhooks/bot_webhook_documentation.mdx b/content/docs/api/reference/webhooks/bot_webhook_documentation.mdx index 21a6d6d6..b22af109 100644 --- a/content/docs/api/reference/webhooks/bot_webhook_documentation.mdx +++ b/content/docs/api/reference/webhooks/bot_webhook_documentation.mdx @@ -50,8 +50,8 @@ _openapi: } ], \"speakers\": [ - \"John Doe\", - \"Jane Smith\" + \"Jane Smith\", + \"John Doe\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", @@ -236,8 +236,8 @@ Sent when a bot successfully completes recording a meeting. } ], \"speakers\": [ - \"John Doe\", - \"Jane Smith\" + \"Jane Smith\", + \"John Doe\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", diff --git a/content/docs/api/reference/webhooks/webhook_documentation.mdx b/content/docs/api/reference/webhooks/webhook_documentation.mdx index 85386183..7516ccb4 100644 --- a/content/docs/api/reference/webhooks/webhook_documentation.mdx +++ b/content/docs/api/reference/webhooks/webhook_documentation.mdx @@ -48,8 +48,8 @@ _openapi: } ], \"speakers\": [ - \"Jane Smith\", - \"John Doe\" + \"John Doe\", + \"Jane Smith\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", @@ -291,8 +291,8 @@ Sent when a bot successfully completes recording a meeting. Contains full transc } ], \"speakers\": [ - \"Jane Smith\", - \"John Doe\" + \"John Doe\", + \"Jane Smith\" ], \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\", \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\", diff --git a/openapi-v2.json b/openapi-v2.json index e8458688..5efc15d4 100644 --- a/openapi-v2.json +++ b/openapi-v2.json @@ -693,6 +693,182 @@ ], "type": "object" }, + "BotWebhookChatStatus": { + "$id": "#/components/schemas/BotWebhookChatStatus", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "additionalProperties": false, + "properties": { + "data": { + "additionalProperties": false, + "properties": { + "available": { + "description": "Whether the bot can send and receive chat in this meeting", + "type": "boolean" + }, + "bot_id": { + "description": "The UUID of the bot this chat status refers to", + "type": "string" + }, + "event_id": { + "anyOf": [ + { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The UUID of the calendar event series. Null when the bot was not created from a calendar event" + }, + "reason": { + "anyOf": [ + { + "enum": [ + "organizer_disabled", + "panel_not_attached", + "send_failed" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why chat is unavailable. Null when available is true" + }, + "sent_at": { + "description": "ISO 8601 timestamp when this webhook was sent", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", + "type": "string" + } + }, + "required": [ + "bot_id", + "event_id", + "available", + "reason", + "sent_at" + ], + "type": "object" + }, + "event": { + "const": "bot.chat_status", + "description": "The webhook event type", + "type": "string" + }, + "extra": { + "anyOf": [ + { + "additionalProperties": {}, + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "description": "Additional metadata provided when creating the bot. This is user-defined data that can be used for correlation or tracking" + } + }, + "required": [ + "event", + "data", + "extra" + ], + "type": "object" + }, + "BotWebhookChatStatusInput": { + "$id": "#/components/schemas/BotWebhookChatStatusInput", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "properties": { + "data": { + "properties": { + "available": { + "description": "Whether the bot can send and receive chat in this meeting", + "type": "boolean" + }, + "bot_id": { + "description": "The UUID of the bot this chat status refers to", + "type": "string" + }, + "event_id": { + "anyOf": [ + { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The UUID of the calendar event series. Null when the bot was not created from a calendar event" + }, + "reason": { + "anyOf": [ + { + "enum": [ + "organizer_disabled", + "panel_not_attached", + "send_failed" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why chat is unavailable. Null when available is true" + }, + "sent_at": { + "description": "ISO 8601 timestamp when this webhook was sent", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", + "type": "string" + } + }, + "required": [ + "bot_id", + "event_id", + "available", + "reason", + "sent_at" + ], + "type": "object" + }, + "event": { + "const": "bot.chat_status", + "description": "The webhook event type", + "type": "string" + }, + "extra": { + "anyOf": [ + { + "additionalProperties": {}, + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "description": "Additional metadata provided when creating the bot. This is user-defined data that can be used for correlation or tracking" + } + }, + "required": [ + "event", + "data", + "extra" + ], + "type": "object" + }, "BotWebhookCompleted": { "$id": "#/components/schemas/CallbackCompleted", "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -4044,7 +4220,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -4288,6 +4464,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -4385,7 +4562,7 @@ { "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -4403,7 +4580,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -4421,7 +4598,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -4432,7 +4609,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -4445,7 +4622,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -4454,7 +4631,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -4497,6 +4674,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -4740,7 +4918,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -4984,6 +5162,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -5095,7 +5274,7 @@ "additionalProperties": false, "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -5113,7 +5292,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -5131,7 +5310,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -5143,7 +5322,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -5156,7 +5335,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -5165,7 +5344,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -5216,6 +5395,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -5445,7 +5625,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -5683,6 +5863,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -5780,7 +5961,7 @@ { "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -5798,7 +5979,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -5816,7 +5997,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -5827,7 +6008,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -5840,7 +6021,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -5849,7 +6030,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -5892,6 +6073,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -13169,7 +13351,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -13404,6 +13586,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -13508,7 +13691,7 @@ "additionalProperties": false, "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -13526,7 +13709,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -13544,7 +13727,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -13556,7 +13739,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -13569,7 +13752,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -13578,7 +13761,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -13617,7 +13800,7 @@ }, "transcription_config": { "additionalProperties": false, - "description": "The transcription configuration for the bot.\n\nRequired when `transcription_enabled` is `true`. Must not be provided when `transcription_enabled` is `false`.\n\n- `provider`: Speech-to-text provider (default: \"gladia\"). Supported: gladia, deepgram, assemblyai, speechmatics, soniox\n- `api_key`: Your own API key for the provider (BYOK - available on Pro plans and above)\n- `region`: Provider region (e.g. \"eu\", \"us\"). Required for some providers like Speechmatics\n- `custom_params`: Custom parameters for the transcription provider\n\nOmit this field to leave transcription configuration unchanged.", + "description": "The transcription configuration for the bot.\n\nRequired when `transcription_enabled` is `true`. Must not be provided when `transcription_enabled` is `false`.\n\n- `provider`: Speech-to-text provider (default: \"gladia\"). Supported: gladia, deepgram, assemblyai, speechmatics, soniox\n- `api_key`: Your own API key for the provider (BYOK - available on all plans)\n- `region`: Provider region (e.g. \"eu\", \"us\"). Required for some providers like Speechmatics\n- `custom_params`: Custom parameters for the transcription provider\n\nOmit this field to leave transcription configuration unchanged.", "example": { "api_key": null, "custom_params": null, @@ -13628,6 +13811,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -13831,7 +14015,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -14060,6 +14244,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -14150,7 +14335,7 @@ { "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -14168,7 +14353,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -14186,7 +14371,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -14197,7 +14382,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -14210,7 +14395,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -14219,7 +14404,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -14250,7 +14435,7 @@ "type": "object" }, "transcription_config": { - "description": "The transcription configuration for the bot.\n\nRequired when `transcription_enabled` is `true`. Must not be provided when `transcription_enabled` is `false`.\n\n- `provider`: Speech-to-text provider (default: \"gladia\"). Supported: gladia, deepgram, assemblyai, speechmatics, soniox\n- `api_key`: Your own API key for the provider (BYOK - available on Pro plans and above)\n- `region`: Provider region (e.g. \"eu\", \"us\"). Required for some providers like Speechmatics\n- `custom_params`: Custom parameters for the transcription provider\n\nOmit this field to leave transcription configuration unchanged.", + "description": "The transcription configuration for the bot.\n\nRequired when `transcription_enabled` is `true`. Must not be provided when `transcription_enabled` is `false`.\n\n- `provider`: Speech-to-text provider (default: \"gladia\"). Supported: gladia, deepgram, assemblyai, speechmatics, soniox\n- `api_key`: Your own API key for the provider (BYOK - available on all plans)\n- `region`: Provider region (e.g. \"eu\", \"us\"). Required for some providers like Speechmatics\n- `custom_params`: Custom parameters for the transcription provider\n\nOmit this field to leave transcription configuration unchanged.", "example": { "api_key": null, "custom_params": null, @@ -14261,6 +14446,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -14780,7 +14966,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -15036,6 +15222,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -15147,7 +15334,7 @@ "additionalProperties": false, "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -15165,7 +15352,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -15183,7 +15370,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -15195,7 +15382,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -15208,7 +15395,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -15217,7 +15404,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -15268,6 +15455,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -15452,7 +15640,7 @@ "example": null }, "bot_name": { - "description": "The name of the bot.\n\nThis name will be displayed as the bot's name in the meeting.", + "description": "The name requested for the bot.\n\nThis name is displayed for anonymous joins. For an authenticated Microsoft Teams join using `teams_config`, Microsoft Teams ignores this value and displays the signed-in Microsoft 365 account's display name and profile instead.\n\nFor a Microsoft Teams meeting the name must be one Teams accepts for a guest, or the request is rejected: at most 50 characters; only letters, numbers, spaces and ' ’ . _ @ - · ・; no consecutive spaces; and no leading, trailing or consecutive periods. This applies to authenticated joins too, because a failed sign-in falls back to joining as a guest under this name.", "example": "Meeting BaaS Bot", "maxLength": 255, "minLength": 1, @@ -15702,6 +15890,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -15799,7 +15988,7 @@ { "properties": { "credential_id": { - "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login for this bot.", + "description": "UUID of a stored teams login (created via /v2/teams-logins). Pin a specific login—and therefore a specific Microsoft 365 display identity—for this bot. `bot_name` cannot override the signed-in account's display name.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" @@ -15817,7 +16006,7 @@ "type": "string" } ], - "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group." + "description": "Round-robin pool selector. Bot will be assigned to the least-loaded active teams_login with this email_group value. Takes priority over credential_id when both are set. Pass an empty string (\"\") to round-robin across all active logins for the team without filtering by group. The selected account controls the bot's visible Teams name and profile, so use interchangeable identities in a pool when display identity matters." }, "fallback": { "description": "What to do if no teams_login slot is available.\n- 'fail' (default): bot creation fails with teams_login_unavailable.\n- 'anonymous': silently fall back to an anonymous (non-authenticated) bot.", @@ -15835,7 +16024,7 @@ } ], "default": null, - "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\n- credential_id: pin a specific login.\n- email_group: pool selector (preferred — takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", + "description": "Teams-only configuration for authenticated bots via a signed-in Microsoft account.\n\nMicrosoft Teams displays the selected account's Microsoft 365 name and profile; `bot_name` is ignored for the authenticated join.\n\n- credential_id: pin a specific login and display identity.\n- email_group: least-loaded pool selector (takes priority).\n- fallback: 'fail' (default) or 'anonymous' on saturation.\n\nLeave null for anonymous Teams joins, Zoom, or Google Meet.", "example": null }, "timeout_config": { @@ -15846,7 +16035,7 @@ "silence_timeout": 600, "waiting_room_timeout": 600 }, - "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 6 hours).", + "description": "Configuration for automatic meeting exit behavior. For Google Meet and Microsoft Teams, the bot uses waiting_room_timeout to wait in the waiting room, then no_one_joined_timeout to wait for participants when first joining the meeting, and finally switches to silence_timeout monitoring once participants are detected. Zoom only uses waiting_room_timeout. Optional max_recording_duration sets a hard cap on total recording time (up to 12 hours).", "properties": { "grace_period": { "default": 0, @@ -15859,7 +16048,7 @@ "max_recording_duration": { "anyOf": [ { - "maximum": 21600, + "maximum": 43200, "minimum": 7200, "type": "integer" }, @@ -15868,7 +16057,7 @@ } ], "default": null, - "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–21600 seconds (2–6 hours)", + "description": "The maximum recording duration in seconds. When set, the bot will automatically end the recording after this duration regardless of silence or participant activity. When null, the default 4-hour internal timeout applies.\n\nRange: 7200–43200 seconds (2–12 hours)", "example": null }, "no_one_joined_timeout": { @@ -15911,6 +16100,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -16738,7 +16928,7 @@ }, "/v2/bots/batch": { "post": { - "description": "Create multiple bots in a single request with partial success support.\n \n Processes each bot creation request sequentially (index 0, 1, 2...). Each item is validated and processed independently. If some bots fail to create, the request still returns 201 with a `data` array containing successful creations and an `errors` array containing failures. Each error includes the `index` of the failed item in the original request array.\n \n **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, BYOK transcription check, daily bot cap check, token availability check, and deduplication lock acquisition.\n \n **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully created bots with their `bot_id` and preserved `extra` metadata. The `errors` array contains failed items with `index`, `code`, `message`, `details`, and preserved `extra` metadata.\n \n **Daily Bot Cap:** The daily bot cap is checked per item, not per batch. If the cap is reached mid-batch, subsequent items will fail with `DAILY_BOT_CAP_REACHED` error. The cap is based on bots created in the last 24 hours.\n \n **Token Reservation:** Tokens are reserved individually for each successful bot creation (0.5 tokens per bot). If token availability becomes insufficient mid-batch, subsequent items will fail with `INSUFFICIENT_TOKENS`.\n \n **Error Index Mapping:** Each error includes an `index` field (0-based) that corresponds to the item's position in the request array. Use this to correlate errors with your original request. Validation errors include detailed validation issues in the `details` field.\n \n **Error Isolation:** Each bot creation is processed independently. If one bot creation fails, it does not affect other bots in the batch. Failed items are included in the `errors` array while successful items are in the `data` array.\n \n Returns 201 with partial success response. All items may succeed, all may fail, or any combination. Always check both `data` and `errors` arrays.", + "description": "Create multiple bots in a single request with partial success support.\n \n Processes each bot creation request sequentially (index 0, 1, 2...). Each item is validated and processed independently. If some bots fail to create, the request still returns 201 with a `data` array containing successful creations and an `errors` array containing failures. Each error includes the `index` of the failed item in the original request array.\n \n **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through the same validation and checks as a single bot creation: platform detection, transcription key availability, daily bot cap check, token availability check, and deduplication lock acquisition.\n \n **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully created bots with their `bot_id` and preserved `extra` metadata. The `errors` array contains failed items with `index`, `code`, `message`, `details`, and preserved `extra` metadata.\n \n **Daily Bot Cap:** The daily bot cap is checked per item, not per batch. If the cap is reached mid-batch, subsequent items will fail with `DAILY_BOT_CAP_REACHED` error. The cap is based on bots created in the last 24 hours.\n \n **Token Reservation:** Tokens are reserved individually for each successful bot creation (0.5 tokens per bot). If token availability becomes insufficient mid-batch, subsequent items will fail with `INSUFFICIENT_TOKENS`.\n \n **Error Index Mapping:** Each error includes an `index` field (0-based) that corresponds to the item's position in the request array. Use this to correlate errors with your original request. Validation errors include detailed validation issues in the `details` field.\n \n **Error Isolation:** Each bot creation is processed independently. If one bot creation fails, it does not affect other bots in the batch. Failed items are included in the `errors` array while successful items are in the `data` array.\n \n Returns 201 with partial success response. All items may succeed, all may fail, or any combination. Always check both `data` and `errors` arrays.", "operationId": "batchCreateBots", "requestBody": { "content": { @@ -17281,7 +17471,7 @@ }, "/v2/bots/scheduled/batch": { "post": { - "description": "Create multiple scheduled bots in a single request with partial success support.\n \n Processes each scheduled bot creation request sequentially. Each item is validated and processed independently. Token reservation and daily bot cap checks are NOT performed at creation time - they are performed when each bot actually joins the meeting.\n \n **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, BYOK transcription check, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time.\n \n **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully scheduled bots with their `bot_id` and preserved `extra` metadata.\n \n **Join Time Validation:** Each scheduled bot's `join_at` time must be in the future (at least 1 minute ahead). If a join time is invalid, that item will fail with a validation error, but other items will continue processing.\n \n **Error Scenarios:** \n - Validation errors: Invalid join time, invalid meeting URL, invalid configuration\n - Platform detection failures: `INVALID_MEETING_PLATFORM`\n - BYOK not enabled: `BYOK_TRANSCRIPTION_NOT_ENABLED_ON_PLAN`\n - System failures: `BOT_CREATE_FAILED`\n \n **Note:** Daily bot cap and token availability are checked when each bot joins, not at creation time. If these checks fail at join time, the bot will transition to `failed` status and send a failure webhook.\n \n Returns 201 with partial success response. All items may succeed, all may fail, or any combination.", + "description": "Create multiple scheduled bots in a single request with partial success support.\n \n Processes each scheduled bot creation request sequentially. Each item is validated and processed independently. Token reservation and daily bot cap checks are NOT performed at creation time - they are performed when each bot actually joins the meeting.\n \n **Processing Order:** Items are processed in the order they appear in the request array. Each item goes through validation: platform detection, transcription key availability, and join time validation. Unlike immediate bot creation, daily bot cap and token availability are not checked at creation time.\n \n **Partial Success:** The response always has `success: true`, even if all items fail. Check the `errors` array to identify failed items. The `data` array contains successfully scheduled bots with their `bot_id` and preserved `extra` metadata.\n \n **Join Time Validation:** Each scheduled bot's `join_at` time must be in the future (at least 1 minute ahead). If a join time is invalid, that item will fail with a validation error, but other items will continue processing.\n \n **Error Scenarios:** \n - Validation errors: Invalid join time, invalid meeting URL, invalid configuration\n - Platform detection failures: `INVALID_MEETING_PLATFORM`\n - System failures: `BOT_CREATE_FAILED`\n \n **Note:** Daily bot cap and token availability are checked when each bot joins, not at creation time. If these checks fail at join time, the bot will transition to `failed` status and send a failure webhook.\n \n Returns 201 with partial success response. All items may succeed, all may fail, or any combination.", "operationId": "batchCreateScheduledBots", "requestBody": { "content": { @@ -18818,6 +19008,7 @@ "api_key": { "anyOf": [ { + "minLength": 1, "type": "string" }, { @@ -23963,7 +24154,7 @@ ] }, "post": { - "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\". Do not assign the profile yet.\n 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the \"Welcome to Workspace\" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to \"English (United States)\".\n 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow.\n 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", + "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\" and assign the SSO profile to all users.\n 3. Create one or more Workspace users that bots will sign in as, complete the \"Welcome to Workspace\" interactive login for each, and set language to \"English (United States)\".\n 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", "operationId": "createMeetWorkspace", "requestBody": { "content": { diff --git a/openapi.json b/openapi.json index 27baec6e..2e0c435d 100644 --- a/openapi.json +++ b/openapi.json @@ -378,7 +378,7 @@ "Webhooks" ], "summary": "Webhook Events Documentation", - "description": "Meeting BaaS sends webhook events to your configured webhook URL when specific events occur.\n\n## Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting. Contains full transcription data and a link to the recording.\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"Jane Smith\\\",\n \\\"John Doe\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `complete` event includes:\n- **bot_id**: Unique identifier for the bot that completed recording\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **speakers**: A set of speaker names identified in the meeting\n- **transcript**: Full transcript data with speaker identification and word timing\n- **mp4**: URL to the recording file (valid for 24 hours by default)\n- **event**: Event type identifier (\"complete\")\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting. Contains error details.\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `failed` event includes:\n- **bot_id**: Unique identifier for the bot that failed\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **error**: Error code identifying the type of failure\n- **message**: Detailed human-readable error message\n\nCommon error types include:\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n### 3. `calendar.sync_events`\nSent when calendar events are synced. Contains information about which events were updated.\n```json\n{\n \\\"event\\\": \\\"calendar.sync_events\\\",\n \\\"data\\\": {\n \\\"calendar_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"last_updated_ts\\\": \\\"2023-05-01T12:00:00Z\\\",\n \\\"affected_event_uuids\\\": [\n \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"123e4567-e89b-12d3-a456-426614174002\\\"\n ]\n }\n}\n```\n\nThe `calendar.sync_events` event includes:\n- **calendar_id**: UUID of the calendar that was synced\n- **last_updated_ts**: ISO-8601 timestamp of when the sync occurred\n- **affected_event_uuids**: Array of UUIDs for calendar events that were added, updated, or deleted\n\nThis event is triggered when:\n- Calendar data is synced with the external provider (Google, Microsoft)\n- Multiple events may be created, updated, or deleted in a single sync operation\n- Use this event to update your local cache of calendar events\n\n### 4. `transcription_complete`\nSent when transcription is completed separately from recording (e.g., after retranscribing).\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\nThe `transcription_complete` event includes:\n- **bot_id**: Unique identifier for the bot with the completed transcription\n\nThis event is sent when:\n- You request a retranscription via the `/bots/retranscribe` endpoint\n- An asynchronous transcription process completes after the recording has ended\n\n## Setting Up Webhooks\n\nYou can configure webhooks in two ways:\n1. **Account-level webhook URL**: Set a default webhook URL for all bots in your account using the `/accounts/webhook_url` endpoint\n2. **Bot-specific webhook URL**: Provide a `webhook_url` parameter when creating a bot with the `/bots` endpoint\n\nYour webhook endpoint must:\n- Accept POST requests with JSON payload\n- Return a 2xx status code to acknowledge receipt\n- Process requests within 10 seconds to avoid timeouts\n- Handle each event type appropriately based on the event type\n\nAll webhook requests include:\n- `x-meeting-baas-api-key` header with your API key for verification\n- `content-type: application/json` header\n- JSON body containing the event details\n\n## Webhook Reliability\n\nIf your endpoint fails to respond or returns an error, the system will attempt to retry the webhook delivery. For critical events, we recommend implementing:\n\n- Idempotency handling to prevent duplicate processing of the same event\n- Proper logging of webhook receipts for audit purposes\n- Asynchronous processing to quickly acknowledge receipt before handling the event data\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", + "description": "Meeting BaaS sends webhook events to your configured webhook URL when specific events occur.\n\n## Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting. Contains full transcription data and a link to the recording.\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"John Doe\\\",\n \\\"Jane Smith\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `complete` event includes:\n- **bot_id**: Unique identifier for the bot that completed recording\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **speakers**: A set of speaker names identified in the meeting\n- **transcript**: Full transcript data with speaker identification and word timing\n- **mp4**: URL to the recording file (valid for 24 hours by default)\n- **event**: Event type identifier (\"complete\")\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting. Contains error details.\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\nThe `failed` event includes:\n- **bot_id**: Unique identifier for the bot that failed\n- **event_uuid**: UUID of the calendar event (if this bot was created from an event)\n- **error**: Error code identifying the type of failure\n- **message**: Detailed human-readable error message\n\nCommon error types include:\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n### 3. `calendar.sync_events`\nSent when calendar events are synced. Contains information about which events were updated.\n```json\n{\n \\\"event\\\": \\\"calendar.sync_events\\\",\n \\\"data\\\": {\n \\\"calendar_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"last_updated_ts\\\": \\\"2023-05-01T12:00:00Z\\\",\n \\\"affected_event_uuids\\\": [\n \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"123e4567-e89b-12d3-a456-426614174002\\\"\n ]\n }\n}\n```\n\nThe `calendar.sync_events` event includes:\n- **calendar_id**: UUID of the calendar that was synced\n- **last_updated_ts**: ISO-8601 timestamp of when the sync occurred\n- **affected_event_uuids**: Array of UUIDs for calendar events that were added, updated, or deleted\n\nThis event is triggered when:\n- Calendar data is synced with the external provider (Google, Microsoft)\n- Multiple events may be created, updated, or deleted in a single sync operation\n- Use this event to update your local cache of calendar events\n\n### 4. `transcription_complete`\nSent when transcription is completed separately from recording (e.g., after retranscribing).\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\nThe `transcription_complete` event includes:\n- **bot_id**: Unique identifier for the bot with the completed transcription\n\nThis event is sent when:\n- You request a retranscription via the `/bots/retranscribe` endpoint\n- An asynchronous transcription process completes after the recording has ended\n\n## Setting Up Webhooks\n\nYou can configure webhooks in two ways:\n1. **Account-level webhook URL**: Set a default webhook URL for all bots in your account using the `/accounts/webhook_url` endpoint\n2. **Bot-specific webhook URL**: Provide a `webhook_url` parameter when creating a bot with the `/bots` endpoint\n\nYour webhook endpoint must:\n- Accept POST requests with JSON payload\n- Return a 2xx status code to acknowledge receipt\n- Process requests within 10 seconds to avoid timeouts\n- Handle each event type appropriately based on the event type\n\nAll webhook requests include:\n- `x-meeting-baas-api-key` header with your API key for verification\n- `content-type: application/json` header\n- JSON body containing the event details\n\n## Webhook Reliability\n\nIf your endpoint fails to respond or returns an error, the system will attempt to retry the webhook delivery. For critical events, we recommend implementing:\n\n- Idempotency handling to prevent duplicate processing of the same event\n- Proper logging of webhook receipts for audit purposes\n- Asynchronous processing to quickly acknowledge receipt before handling the event data\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", "operationId": "webhook_documentation", "responses": { "200": { @@ -398,7 +398,7 @@ "Webhooks" ], "summary": "Bot Webhook Events Documentation", - "description": "Meeting BaaS sends the following webhook events related to bot recordings.\n\n## Bot Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"John Doe\\\",\n \\\"Jane Smith\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\n**When it's triggered:**\n- After a bot successfully records and processes a meeting\n- After the recording is uploaded and made available\n- When all processing of the meeting recording is complete\n\n**What to do with it:**\n- Download the MP4 recording for storage in your system\n- Store the transcript data in your database\n- Update meeting status in your application\n- Notify users that the recording is available\n- Use `event_uuid` to correlate with calendar events (if applicable)\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\n**Common error types:**\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n**What to do with it:**\n- Log the failure for troubleshooting\n- Notify administrators or users about the failed recording\n- Attempt to reschedule if appropriate\n- Update meeting status in your system\n- Use `event_uuid` to correlate with calendar events (if applicable)\n\n### 3. `transcription_complete`\nSent when transcription is completed separately from recording.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\n**When it's triggered:**\n- After requesting retranscription via the API\n- When an asynchronous transcription job completes\n- When a higher quality or different language transcription becomes available\n\n**What to do with it:**\n- Update the transcript data in your system\n- Notify users that improved transcription is available\n- Run any post-processing on the new transcript data\n\n## Webhook Usage Tips\n\n- Each event includes the `bot_id` so you can correlate with your internal data\n- The `event_uuid` field is included when the bot was created from a calendar event (null for direct bots or scheduled bots)\n- The complete event includes speaker identification and full transcript data\n- For downloading recordings, the mp4 URL is valid for 24 hours\n- Handle the webhook asynchronously and return 200 OK quickly to prevent timeouts\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", + "description": "Meeting BaaS sends the following webhook events related to bot recordings.\n\n## Bot Webhook Event Types\n\n### 1. `complete`\nSent when a bot successfully completes recording a meeting.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"transcript\\\": [\n {\n \\\"speaker\\\": \\\"John Doe\\\",\n \\\"offset\\\": 1.5,\n \\\"start_time\\\": 1.5,\n \\\"end_time\\\": 2.4,\n \\\"words\\\": [\n {\n \\\"start\\\": 1.5,\n \\\"end\\\": 1.9,\n \\\"word\\\": \\\"Hello\\\"\n },\n {\n \\\"start\\\": 2.0,\n \\\"end\\\": 2.4,\n \\\"word\\\": \\\"everyone\\\"\n }\n ]\n }\n ],\n \\\"speakers\\\": [\n \\\"Jane Smith\\\",\n \\\"John Doe\\\"\n ],\n \\\"mp4\\\": \\\"https://storage.example.com/recordings/video123.mp4?token=abc\\\",\n \\\"audio\\\": \\\"https://storage.example.com/recordings/audio123.wav?token=abc\\\",\n \\\"event\\\": \\\"complete\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\n**When it's triggered:**\n- After a bot successfully records and processes a meeting\n- After the recording is uploaded and made available\n- When all processing of the meeting recording is complete\n\n**What to do with it:**\n- Download the MP4 recording for storage in your system\n- Store the transcript data in your database\n- Update meeting status in your application\n- Notify users that the recording is available\n- Use `event_uuid` to correlate with calendar events (if applicable)\n\n### 2. `failed`\nSent when a bot fails to join or record a meeting.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"failed\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\",\n \\\"event_uuid\\\": \\\"123e4567-e89b-12d3-a456-426614174001\\\",\n \\\"error\\\": \\\"meeting_not_found\\\",\n \\\"message\\\": \\\"Could not join meeting: The meeting ID was not found or has expired\\\",\n \\\"extra\\\": {\n \\\"foo\\\": \\\"bar\\\"\n }\n }\n}\n```\n\n**Common error types:**\n- `meeting_not_found`: The meeting ID or link was invalid or expired\n- `access_denied`: The bot was denied access to the meeting\n- `authentication_error`: Failed to authenticate with the meeting platform\n- `network_error`: Network connectivity issues during recording\n- `internal_error`: Internal server error\n\n**What to do with it:**\n- Log the failure for troubleshooting\n- Notify administrators or users about the failed recording\n- Attempt to reschedule if appropriate\n- Update meeting status in your system\n- Use `event_uuid` to correlate with calendar events (if applicable)\n\n### 3. `transcription_complete`\nSent when transcription is completed separately from recording.\n\n**Payload Structure:**\n```json\n{\n \\\"event\\\": \\\"transcription_complete\\\",\n \\\"data\\\": {\n \\\"bot_id\\\": \\\"123e4567-e89b-12d3-a456-426614174000\\\"\n }\n}\n```\n\n**When it's triggered:**\n- After requesting retranscription via the API\n- When an asynchronous transcription job completes\n- When a higher quality or different language transcription becomes available\n\n**What to do with it:**\n- Update the transcript data in your system\n- Notify users that improved transcription is available\n- Run any post-processing on the new transcript data\n\n## Webhook Usage Tips\n\n- Each event includes the `bot_id` so you can correlate with your internal data\n- The `event_uuid` field is included when the bot was created from a calendar event (null for direct bots or scheduled bots)\n- The complete event includes speaker identification and full transcript data\n- For downloading recordings, the mp4 URL is valid for 24 hours\n- Handle the webhook asynchronously and return 200 OK quickly to prevent timeouts\n\nFor security, always validate the API key in the `x-meeting-baas-api-key` header matches your API key.", "operationId": "bot_webhook_documentation", "responses": { "200": { @@ -3502,7 +3502,7 @@ }, "last_updated": { "description": "Timestamp of when this data was generated (in ISO-8601 format)\n\nThis field is maintained for backwards compatibility. It is automatically set to the current time when the response is created.", - "default": "2026-05-27T02:27:30.735912107+00:00", + "default": "2026-08-18T09:35:55.189434712+00:00", "type": "string", "format": "date-time" },