diff --git a/content/docs/api-v2/authenticated-bots/teams/index.mdx b/content/docs/api-v2/authenticated-bots/teams/index.mdx index c27022f..14ca7a3 100644 --- a/content/docs/api-v2/authenticated-bots/teams/index.mdx +++ b/content/docs/api-v2/authenticated-bots/teams/index.mdx @@ -57,7 +57,7 @@ All Teams authentication options are passed in a single `teams_config` object on ```json { - "bot_name": "Recording Bot", + "bot_name": "Guest fallback name", "meeting_url": "https://teams.microsoft.com/meet/1234567890?p=AbCdEfGhIj", "teams_config": { "email_group": "bots@acme.onmicrosoft.com", @@ -66,16 +66,32 @@ All Teams authentication options are passed in a single `teams_config` object on } ``` + +For a signed-in Teams bot, Microsoft displays the selected Microsoft 365 account's **display name and profile picture**. The `bot_name` value is ignored unless the bot joins anonymously, including through `fallback: "anonymous"`. + + | Parameter | Description | |-----------|-------------| -| `email_group` | Round-robin pool selector. The bot is assigned the **least-loaded active login** in this pool. Preferred for most use cases — **takes priority over `credential_id`**. Pass `""` to round-robin across all of the team's active logins. | -| `credential_id` | Pin one specific login (UUID) for this bot. | +| `email_group` | Round-robin pool selector. The bot is assigned the **least-loaded active login** in this pool. Use it when every account in the pool is an interchangeable display identity. It **takes priority over `credential_id`**. Pass `""` to round-robin across all of the team's active logins. | +| `credential_id` | Pin one specific login (UUID), and therefore one specific Microsoft 365 display identity, for this bot. | | `fallback` | What to do when no login slot is available: `fail` (default) fails bot creation with `TEAMS_LOGIN_UNAVAILABLE`; `anonymous` silently falls back to an anonymous join. | Leave `teams_config` `null` for anonymous Teams joins, Zoom, or Google Meet. ## Key concepts +### Visible name and profile + +Microsoft controls a signed-in participant's identity. Once `teams_config` resolves a login, Teams uses that Microsoft 365 account's display name and profile picture and ignores `bot_name`. + +For multiple brands or customer-specific notetaker names: + +1. Create one Microsoft 365 account per desired visible identity and set its display name and profile picture in Microsoft 365. +2. [Register each account as a teams login](/docs/api-v2/reference/teams-logins/createTeamsLogin). The login's `name` field is only an internal Meeting BaaS label. +3. Pass that login's `credential_id` when you [create the bot](/docs/api-v2/reference/bots/createBot). + +Use `email_group` only when any account in that pool is acceptable. If every account in a pool has the same public display name, pooling preserves the brand while distributing load. + ### Getting past the lobby Signing in is what gets the bot admitted. When the account belongs to the **organizer's organization** (or the meeting's lobby policy admits people in the org), the authenticated bot is let in automatically instead of waiting in the lobby as an anonymous guest. For meetings restricted to signed-in users, an authenticated bot is the only way in — an anonymous bot fails with `TEAMS_LOGIN_REQUIRED`. @@ -88,6 +104,8 @@ The bot types the account's password on `login.microsoftonline.com`. If the tena Each login supports up to **20 concurrent sessions**. When you dispatch bots with an `email_group`, the assigner picks the least-loaded active login and skips any login at capacity. If every login in a pool is saturated, bot creation fails with `TEAMS_LOGIN_UNAVAILABLE` (or falls back to anonymous, per your `fallback` setting). Create more logins to raise the ceiling, and configure a [utilization alert](/docs/api-v2/alerts) to stay ahead of saturation (the [utilization endpoint](/docs/api-v2/authenticated-bots/teams/sending-authenticated-bots#monitoring-pool-utilization) gives an on-demand view). +Microsoft Teams can merge participants that use the same Microsoft 365 account into one attendee when they join the same meeting. Use a distinct account for each bot that must appear separately in one call. + ### States Both workspaces and logins track health with a `state` field: @@ -133,7 +151,11 @@ Each teams login supports up to **20 concurrent sessions**, and capacity scales -Use `email_group` for round-robin load balancing across a pool (recommended — it takes priority when both are set). Use `credential_id` when you need a specific, fixed login for a bot. +Use `credential_id` when you need a specific, fixed Microsoft 365 identity for a bot. Use `email_group` for load balancing when every account in the pool is interchangeable; the selected account determines the visible name and profile. A non-empty `email_group` takes priority when both are set. + + + +No. Microsoft Teams uses the signed-in Microsoft 365 account's display name and profile picture. `bot_name` is ignored for authenticated Teams joins. Change the account in Microsoft 365, or create separate accounts and pin the intended one with `teams_config.credential_id`. @@ -154,5 +176,6 @@ No. The `password` is encrypted at rest and **never returned** in any response. - [Teams Workspaces API](/docs/api-v2/reference/teams-workspaces/createTeamsWorkspace) — manage the Microsoft 365 tenant grouping - [Teams Logins API](/docs/api-v2/reference/teams-logins/createTeamsLogin) — manage the Microsoft 365 identities bots sign in as +- [Create Bot API](/docs/api-v2/reference/bots/createBot) — select a login with `teams_config.credential_id` or `email_group` - [Error Codes](/docs/api-v2/error-codes) — `TEAMS_LOGIN_*` failure reasons - [Alerts](/docs/api-v2/alerts) — monitor pool utilization and saturation diff --git a/content/docs/api-v2/authenticated-bots/teams/sending-authenticated-bots.mdx b/content/docs/api-v2/authenticated-bots/teams/sending-authenticated-bots.mdx index 8788c4e..078c513 100644 --- a/content/docs/api-v2/authenticated-bots/teams/sending-authenticated-bots.mdx +++ b/content/docs/api-v2/authenticated-bots/teams/sending-authenticated-bots.mdx @@ -8,16 +8,20 @@ icon: Send Once you have at least one **active** teams workspace and login (see [Setup](/docs/api-v2/authenticated-bots/teams/setup)), add a `teams_config` object to your `POST /v2/bots` request to make the bot sign in before joining. + +Microsoft controls the visible identity of a signed-in Teams participant. The selected Microsoft 365 account supplies the display name and profile picture; `bot_name` is ignored for authenticated joins. + + ## Round-robin pool (recommended) -Assign the bot to the least-loaded active login in a pool by passing `email_group`. This spreads load across all logins sharing that group and is the right default for unattended recording at scale. +Assign the bot to the least-loaded active login in a pool by passing `email_group`. This spreads load across all logins sharing that group and is the right default when those accounts are interchangeable—for example, when they all use the same public display name. ```bash curl -X POST https://api.meetingbaas.com/v2/bots \ -H "x-meeting-baas-api-key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ - "bot_name": "Recording Bot", + "bot_name": "Guest fallback name", "meeting_url": "https://teams.microsoft.com/meet/1234567890?p=AbCdEfGhIj", "teams_config": { "email_group": "bots@acme.onmicrosoft.com", @@ -38,7 +42,7 @@ Use `credential_id` to force the bot to use one particular login. ```json { - "bot_name": "Recording Bot", + "bot_name": "Ignored for this authenticated join", "meeting_url": "https://teams.microsoft.com/meet/1234567890?p=AbCdEfGhIj", "teams_config": { "credential_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" @@ -50,6 +54,27 @@ Use `credential_id` to force the bot to use one particular login. If you set both `email_group` and `credential_id`, **`email_group` wins** — the pool selector takes priority. Use `credential_id` alone when you need a deterministic, fixed identity. +## Control the visible identity per bot + +Use one Microsoft 365 account per desired display identity, [register each account as a teams login](/docs/api-v2/reference/teams-logins/createTeamsLogin), then pin the intended login with `credential_id`: + +```json +{ + "bot_name": "Ignored for this authenticated join", + "meeting_url": "https://teams.microsoft.com/meet/1234567890?p=AbCdEfGhIj", + "teams_config": { + "credential_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "fallback": "fail" + } +} +``` + +The `name` stored on a teams login is an internal Meeting BaaS label. It does not change what participants see. Change the account's display name and profile picture in Microsoft 365. + +Use separate `email_group` values for separate brands, and place only interchangeable identities in each pool. Pool selection is load-based, so a pool containing different public identities cannot guarantee which one appears in a given meeting. + +Microsoft Teams can merge multiple participants using the same Microsoft 365 account into one attendee in the same meeting. Give simultaneous bots distinct accounts when each must appear separately. + ## Fallback behavior `fallback` controls what happens when no login slot is available (the whole pool is saturated, or no matching active login exists): @@ -63,6 +88,8 @@ If you set both `email_group` and `credential_id`, **`email_group` wins** — th { "teams_config": { "email_group": "bots@acme.onmicrosoft.com", "fallback": "anonymous" } } ``` +When fallback occurs, the anonymous participant uses `bot_name` instead of the Microsoft 365 account identity. + ## Getting admitted past the lobby Signing in is what gets the bot admitted. When the login account belongs to the **organizer's organization** — or the meeting's lobby policy admits people in the org — the authenticated bot is let in automatically instead of waiting as an anonymous guest. For meetings restricted to signed-in users, an authenticated bot is the only way in; an anonymous bot fails with `TEAMS_LOGIN_REQUIRED`. Use accounts in (or federated with) the organizer's tenant when you need reliable, unattended admission. @@ -132,5 +159,6 @@ See [Error Codes](/docs/api-v2/error-codes) for the full list. These appear in t ## Related resources - [Setup](/docs/api-v2/authenticated-bots/teams/setup) — one-time workspace and login configuration +- [Create a teams login](/docs/api-v2/reference/teams-logins/createTeamsLogin) — register a Microsoft 365 identity - [Create a bot](/docs/api-v2/reference/bots/createBot) — full bot creation reference - [Teams Logins utilization](/docs/api-v2/reference/teams-logins/getTeamsLoginUtilization) — pool metrics endpoint diff --git a/content/docs/api-v2/authenticated-bots/teams/setup.mdx b/content/docs/api-v2/authenticated-bots/teams/setup.mdx index 9777466..7bd38b4 100644 --- a/content/docs/api-v2/authenticated-bots/teams/setup.mdx +++ b/content/docs/api-v2/authenticated-bots/teams/setup.mdx @@ -45,7 +45,7 @@ Either way, the bot accounts must reach a password-only sign-in with no security ## Step 1 — Create the Microsoft 365 account -The simplest path is the **[Microsoft 365 admin center](https://admin.microsoft.com)** → **Users → Active users → Add a user**: set a clear username (for example `bot1@acme.onmicrosoft.com`) and a strong password you'll store with Meeting BaaS (uncheck **"Require this user to change their password"**) — this wizard can also assign the license in the same flow (next). The new account then shows up under **Active users**: +The simplest path is the **[Microsoft 365 admin center](https://admin.microsoft.com)** → **Users → Active users → Add a user**: set the **display name participants should see**, a clear username (for example `bot1@acme.onmicrosoft.com`), and a strong password you'll store with Meeting BaaS (uncheck **"Require this user to change their password"**) — this wizard can also assign the license in the same flow (next). The new account then shows up under **Active users**: +Microsoft Teams uses this account's display name and profile picture for authenticated bots. The bot request's `bot_name` cannot override them. For multiple public identities, create one Microsoft 365 account per identity and later pin the intended account with `teams_config.credential_id`. + +