API приложений для собраний

  • Статья

Расширяемость собраний предоставляет API-интерфейсы для улучшения взаимодействия с собраниями. С помощью перечисленных API можно выполнить следующее:

  • Создавать приложения или интегрировать существующие приложения в жизненные циклы собраний.
  • Использовать API для информирования вашего приложения о собрании.
  • Выбрать необходимые API для улучшения работы с собраниями.

Примечание.

Используйте клиентскую библиотеку Microsoft Teams JavaScript (TeamsJS) (версия 1.10 и более поздние версии) для единого входа для работы на боковой панели собрания.

В следующей таблице представлен список API, доступных в библиотеке JavaScript в Microsoft Teams и пакетах SDK Microsoft Bot Framework:

Метод Описание Источник
Получить пользовательский контекст Получите контекстную информацию для отображения соответствующего содержимого на вкладке Microsoft Teams. Библиотека TeamsJS
Получение участника Получить информацию об участнике по идентификатору собрания и идентификатору участника. Пакет SDK для Microsoft Bot Framework
Отправить уведомление о собрании Предоставляет сигналы собрания с помощью существующего API уведомлений о беседах для чата user-bot и позволяет боту уведомлять пользователя о действиях, отображающих уведомление на собрании. Пакет SDK для Microsoft Bot Framework
Получить сведения о собрании Получите статические метаданные собрания. Пакет SDK для Microsoft Bot Framework
Отправляйте субтитры в реальном времени Отправка субтитров к текущему собранию в режиме реального времени. Библиотека TeamsJS
Делитесь содержимым приложения на сцене Поделитесь определенными частями приложения на сцене собрания с боковой панели приложения в собрании. Библиотека TeamsJS
Получение событий собраний Teams в режиме реального времени Получение событий собрания в режиме реального времени, таких как начало и окончание собрания или присоединение участников и выход из собрания. Пакет SDK для Microsoft Bot Framework
Получение состояния входящего звука Позволяет приложению получить параметр состояния входящего звука для пользователя собрания. Библиотека TeamsJS
Переключение входящего звука Позволяет приложению переключать параметр состояния входящего звука для пользователя собрания с включения звука или наоборот. Библиотека TeamsJS

Получить API пользовательского контекста

Важно!

  • По умолчанию новый клиент Teams поддерживает светлую тему для приложений на собраниях Teams. app.theme Когда свойство в API getContext возвращает default значение, клиент Teams находится в светлой теме.
  • Более ранняя версия клиентов Teams поддерживала только темную и контрастную темы для приложений в собраниях Teams.

Как определить и получить контекстную информацию для содержимого вкладки, можно узнать в разделеПолучение контекста вкладки Teams. meetingId используется вкладкой, работающей в контексте собрания, и добавляется для полезных данных ответа.

Примеры

Ниже приведены ответы TeamsJS версии 2 для get user context API в зависимости от типа собрания, типа пользователя и типа вызова.

  • Тип собрания

    Ниже приведен ответ полезных данных JSON для собрания канала для пользователей в клиенте.

    {
    "app": {
    "locale": "en-us",
    "sessionId": "ff47ec00-e6a7-4dc1-a6ae-f44110f50c94",
    "theme": "default",
    "iconPositionVertical": 0,
    "osLocaleInfo": {
      "platform": "windows",
      "regionalFormat": "en-in",
      "shortDate": "dd-MM-yyyy",
      "longDate": "dd MMMM yyyy",
      "shortTime": "HH:mm",
      "longTime": "HH:mm:ss"
    },
    "parentMessageId": "1678109354022",
    "userClickTime": 1678109521159,
    "userFileOpenPreference": "inline",
    "host": {
      "name": "Teams",
      "clientType": "desktop",
      "sessionId": "c3c3c0a0-f7a1-b070-6b89-c8cd1f380042",
      "ringId": "ring1"
    },
    "appLaunchId": "7346ae66-5cac-47f9-8a0d-1228dac474cb"
    },
    "page": {
    "id": "Test",
    "frameContext": "sidePanel",
    "subPageId": "",
        "isFullScreen": false,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
        "displayName": "",
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "v-prkamble@microsoft.com",
        "userPrincipalName": "v-prkamble@microsoft.com",
        "tenant": {
         "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
         "teamsSku": "enterprise"
        }
       },
       "channel": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2",
        "displayName": undefined,
        "relativeUrl": undefined,
        "membershipType": undefined,
        "defaultOneNoteSectionId": undefined,
        "ownerGroupId": undefined,
        "ownerTenantId": undefined
       },
       "chat": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2"
       },
       "meeting": {
        "id": "MCMxOTo0OTY4MzgwN2ZmY2U0MzE4YWQ2ZDZkN2EyNGRiZGU0NUB0aHJlYWQudGFjdjIjMTY3ODEwOTM1NDAyMg=="
       },
       "sharepoint": undefined,
       "team": {
        "internalId": "19:b34aeec3f8e54240a5c283e86bfc4878@thread.tacv2",
        "displayName": undefined,
        "type": undefined,
        "groupId": undefined,
        "templateId": undefined,
        "isArchived": undefined,
        "userRole": 1
       },
       "sharePointSite": {
        "teamSiteUrl": "",
        "teamSiteDomain": "microsoft.sharepoint.com",
        "teamSitePath": "",
        "teamSiteId": "",
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

  • Тип пользователя

    Ниже приведен ответ полезных данных JSON на запланированном закрытом собрании для гостевого пользователя:

      {
        "app": {
         "locale": "en-us",
         "sessionId": "268beeb4-a52d-4ba8-b1c8-8b9f0b9b3492",
         "theme": "default",
         "iconPositionVertical": 23,
         "osLocaleInfo": {
          "platform": "windows",
          "regionalFormat": "en-in",
          "longDate": "dd MMMM yyyy",
          "shortDate": "dd-MM-yyyy",
          "longTime": "HH:mm:ss",
          "shortTime": "HH:mm"
         },
         "parentMessageId": "",
         "userClickTime": 1678023265131,
         "userFileOpenPreference": "inline",
         "host": {
          "name": "Teams",
          "clientType": "desktop",
          "sessionId": "967c980b-1e41-a2cd-eac0-a4bff8f73ce7",
          "ringId": "ring1"
         },
         "appLaunchId": "c35c4496-f28c-4107-8e6c-2dba09fb881a"
        },
        "page": {
         "id": "Test",
         "frameContext": "content",
         "subPageId": "",
         "isFullScreen": false,
         "isMultiWindow": false,
         "sourceOrigin": NULL
        },
        "user": {
         "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
         "displayName": undefined,
         "isCallingAllowed": undefined,
         "isPSTNCallingAllowed": undefined,
         "licenseType": "Unknown",
         "loginHint": "v-prkamble@microsoft.com",
         "userPrincipalName": "v-prkamble@microsoft.com",
         "tenant": {
          "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
          "teamsSku": "enterprise"
         }
        },
        "channel": undefined,
        "chat": {
         "id": "19:meeting_YmU5NWM3NGEtZjMyMi00ZDg4LTk4OGUtMjUzMGJkZjRhMDhm@thread.v2"
        },
        "meeting": {
         "id": "MCMxOTptZWV0aW5nX1ltVTVOV00zTkdFdFpqTXlNaTAwWkRnNExUazRPR1V0TWpVek1HSmtaalJoTURobUB0aHJlYWQudjIjMA=="
        },
        "sharepoint": undefined,
        "team": undefined,
        "sharePointSite": {
         "teamSiteUrl": "",
         "teamSiteDomain": "microsoft.sharepoint.com",
         "teamSitePath": "",
         "teamSiteId": undefined,
         "mySitePath": "/personal/v-prkamble_microsoft_com",
         "mySiteDomain": "microsoft-my.sharepoint.com"
        }
  }

  • Тип вызова

    Ниже приведен ответ полезных данных JSON для единого вызова пользователя в клиенте.

          {
       "app": {
        "locale": "en-us",
        "sessionId": "1b3dc47e-f6ae-4fe2-8ed6-844a505f3186",
        "theme": "dark",
        "iconPositionVertical": null,
        "osLocaleInfo": {
         "platform": "windows",
         "regionalFormat": "en-in",
         "shortDate": "dd-MM-yyyy",
         "longDate": "dd MMMM yyyy",
         "shortTime": "HH:mm",
         "longTime": "HH:mm:ss"
        },
        "parentMessageId": "",
        "userClickTime": 1678088052473,
        "userFileOpenPreference": undefined,
        "host": {
         "name": "Teams",
         "clientType": "desktop",
         "sessionId": "",
         "ringId": "general"
        },
        "appLaunchId": undefined
       },
       "page": {
        "id": "Test",
        "frameContext": "sidePanel",
        "subPageId": "",
        "isFullScreen": undefined,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "e652dd92-dd63-4fcc-b5b2-2005681e8e9f",
        "displayName": undefined,
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "admin@M365x94626565.onmicrosoft.com",
        "userPrincipalName": "admin@M365x94626565.onmicrosoft.com",
        "tenant": {
         "id": "aa923623-ae61-49ee-b401-81f414b6ad5a",
         "teamsSku": "unknown"
        }
       },
       "channel": undefined,
       "chat": {
        "id": "19:a74d8489-4455-4670-9581-7b38a8017c58_e652dd92-dd63-4fcc-b5b2-2005681e8e9f@unq.gbl.spaces"
       },
       "meeting": {
        "id": "MCMxOTphNzRkODQ4OS00NDU1LTQ2NzAtOTU4MS03YjM4YTgwMTdjNThfZTY1MmRkOTItZGQ2My00ZmNjLWI1YjItMjAwNTY4MWU4ZTlmQHVucS5nYmwuc3BhY2VzIzA="
       },
       "sharepoint": undefined,
       "team": undefined,
       "sharePointSite": {
        "teamSiteUrl": undefined,
        "teamSiteDomain": "m365x94626565.sharepoint.com",
        "teamSitePath": undefined,
        "teamSiteId": undefined,
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

Получить API участника

API GetParticipant должен иметь регистрацию бота и идентификатор для создания токенов авторизации Подробнее в разделе Регистрация и идентификатор бота..

Примечание.

  • Тип пользователя не включен в API getParticipantRole .
  • Не кэшируйте роли участников, так как организатор собрания может изменить роли в любое время.
  • Сейчас API GetParticipant поддерживается только для списков рассылки или реестров до 350 участников.

Параметры запроса

Совет

Получите идентификаторы участников и арендаторов на вкладке проверки подлинности единого входа.

API Meeting должен иметь meetingId, participantId и tenantId в качестве параметров URL-адреса. Параметры доступны как часть клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams и действия бота.

В следующей таблице приведены параметры запроса:

Значение Тип Обязательный Описание
meetingId String Да Идентификатор собрания доступен через Bot Invoke и библиотеку TeamsJS.
participantId String Да Идентификатор участника — это идентификатор пользователя. Он доступен в библиотеке Tab SSO, Bot Invoke и TeamsJS. Рекомендуется получить идентификатор участника из Tab SSO.
tenantId Строка Да Идентификатор клиента требуется для пользователей клиентов. Он доступен в библиотеке Tab SSO, Bot Invoke и TeamsJS. Рекомендуется получить идентификатор клиента из Tab SSO.

Пример

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Gets the details for the given meeting participant. 
  // This only works in Teams meeting scoped conversations.
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  // Sends a message activity to the sender of the incoming activity. 
  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}
Имя свойства Описание
user.id Идентификатор пользователя.
user.aadObjectId Microsoft Entra идентификатор объекта пользователя.
user.name Имя пользователя.
user.givenName Имя пользователя.
user.surname Фамилия пользователя.
user.email Идентификатор почты пользователя.
user.userPrincipalName Имя участника-пользователя.
user.tenantId Microsoft Entra идентификатор клиента.
user.userRole Роль пользователя. Например, "admin" или "user".
meeting.role Роль участника в собрании. Например, "Организатор", "Выступающий" или "Участник".
meeting.inMeeting Значение, указывающее, находится ли участник в собрании.
conversation.id Идентификатор чата собрания.
conversation.isGroup Логическое значение, указывающее, имеет ли беседа более двух участников.

Коды ответа

В следующей таблице приведены коды ответов:

Код ответа Описание
403 Полученные сведения об участниках не передаются приложению. Если приложение не установлено в собрании, оно вызывает ошибочный отклик 403. Если администратор клиента отключает или блокирует приложение во время динамической миграции сайта, это вызывает ошибочный отклик 403.
200 Сведения об участнике успешно извлечены.
401 Приложение отвечает недопустимым токеном
404 Срок действия собрания истек или участники недоступны.

Отправить уведомление о собрании

Все пользователи на собрании получают уведомления, отправленные с помощью полезных данных уведомлений на собрании. Полезные данные уведомлений на собрании запускают уведомление на собрании и позволяют вам предоставлять сигналы собрания, которые доставляются с использованием существующего API-интерфейса уведомления о разговоре для чата пользователя с ботом. Вы можете отправить уведомление на собрании на основе действий пользователя. Эти полезные данные доступны через службы ботов.

Вы также можете отправить целевое уведомление на собрании конкретному участнику собрания. Дополнительные сведения см. в разделе Уведомление о целевом собрании.

Примечание.

  • Когда вызывается уведомление о собрании, содержимое представляется в виде сообщения чата.
  • Вы должны вызвать функцию submitTask() для автоматического закрытия после того, как пользователь выполнит действие в веб-представлении. Это требование для отправки приложения. Подробнее в статье Модуль задач Teams SDK.
  • Если вы хотите, чтобы ваше приложение поддерживало анонимных пользователей, полезная нагрузка начального запроса на вызов должна полагаться на from.id метаданные запросаfrom в объекте, а не на from.aadObjectId метаданные запроса. from.id— идентификатор пользователя и from.aadObjectId Microsoft Entra ID пользователя. Подробнее в разделеиспользование модулей задач на вкладках и создание и отправка модуля задач..

Параметр запроса

В следующей таблице содержится параметр запроса:

Значение Тип Обязательный Описание
conversationId Строка Да Идентификатор беседы доступен как часть вызова бота.

Примеры

Bot ID объявляется в манифесте, и бот получает результирующий объект.

Примечание.

  • Параметр completionBotIdexternalResourceUrl является необязательным в запрашиваемом примере полезных данных
  • Параметры ширины и высоты externalResourceUrl должны быть в пикселях. Подробнее в правилах разработки вкладок.
  • URL-адрес — это страница, которая загружается как <iframe> в уведомлении о собрании. Домен должен быть в массиве приложений validDomains в манифесте приложения.
// Specifies the type of text data in a message attachment.
Activity activity = MessageFactory.Text("This is a meeting signal test");

// Configures the current activity to generate a notification within Teams.
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);
Имя свойства Описание
type Тип действия.
text Текстовое содержимое сообщения.
summary Сводный текст сообщения.
channelData.notification.alertInMeeting Логическое значение, указывающее, должно ли отображаться уведомление пользователю во время собрания.
channelData.notification.externalResourceUrl Значение URL-адреса внешнего ресурса уведомления.
replyToId Идентификатор родительского или корневого сообщения потока.
APP_ID Идентификатор приложения, объявленный в манифесте.
completionBotId Идентификатор приложения бота.

Коды ответа

В следующей таблице содержатся коды ответов:

Код ответа Описание
201 Действие с сигналом успешно отправлено.
401 Приложение отвечает недопустимым токеном
403 Приложению не удалось отправить сигнал. Код отклика 403 может возникать по разным причинам, например, когда администратор клиента отключает и аварийно завершает работу приложения во время динамической миграции сайта. В этом случае полезные данные содержат подробное сообщение об ошибке.
404 Чат собрания не существует.

API уведомлений о целевом собрании и значка приложения

API targetedMeetingNotification позволяет приложениям отправлять целевые уведомления на собрании и отображает значок приложения для определенных участников собрания. Приложения отправляют целевые уведомления на собрании и значок приложения в зависимости от действий пользователя. API доступен через API бота.

Предварительное условие

Необходимо настроить манифест приложения с разрешениями RSC в свойстве webApplicationInfo , чтобы отправлять целевые уведомления о собрании и отображать значки приложения для определенных участников собрания. Используйте следующие примеры для настройки манифеста:


Для манифеста приложения версии 1.12 и более поздних 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}


Для манифеста приложения версии 1.11 и более ранних версий 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

Примечание.

  • Полезные данные API разрешают только диалог с URL-адресом.
  • Форматы идентификатора пользователя aadObjectid и UPN не поддерживаются.

Получите поддерживаемый формат идентификатора пользователя для целевого уведомления о собрании и значка приложения:

Пример

Ниже приведен пример полезных данных запроса для целевого уведомления о собрании и значка приложения:

POST /v1/meetings/{meetingId}/notification

{

  "type": "targetedMeetingNotification",
  "value": {
    "recipients": [ 
"29:1I12M_iy2wTa97T6LbjTh4rJCWrtw2PZ3lxpD3yFv8j2YPnweY2lpCPPAn3RI0PP7rghfHauUz48I1t7ANhj4CA"
     ], 
    "surfaces": [ 
      { 
        "surface": "meetingStage", 
        "contentType": "task", 
        "content": { 
          "value": { 
            "height": "300", 
            "width": "400", 
            "title": "Targeted meeting Notification", 
            "url": "https://somevalidurl.com"           
}
        } 
      } 
    ] 
  },
  "channelData": { // optional if a developer doesn't want to support user attributes.
    "onBehalfOf": [ 
      { 
        "itemid": 0, 
        "mentionType": "person", 
        "mri": "29:1mDOCfGM9825lMHlwP8NjIVMJeQAbN-ojYBT5VzQfPpnst1IFQeYB1QXC8Zupn2RhgfLIW27HmynQk-4bdx_YhA", 
        "displayName": "yunny chung"      } 
    ] 
  }
}
Имя свойства Описание
meetingId Идентификатор собрания доступен через вызов бота и библиотеку TeamsJS.
type targetedMeetingNotification
recipients Список идентификаторов пользователей. Получение идентификаторов пользователей для участников собрания с помощью GET API участника. Получите весь список списка чатов с помощью API получения участников. Пустой или пустой список получателей вернет 400.
surface Тип поверхности. Поддерживаемые типы поверхностей: meetingStage и meetingTabIcon.
surfaces Список поверхностей, где можно визуализировать уведомления.
contentType Тип содержимого, отображаемого целевым уведомлением о собрании. Поддерживаемое значение — task.
content TaskModuleContinueResponse
content.value.height Необязательный; запрошенная высота уведомления.
content.value.width Необязательный; запрошенная ширина уведомления.
content.value.title Необязательный; название уведомления.
content.value.url Необязательный; URL-адрес для отображения в уведомлении. Убедитесь, что URL-адрес является частью манифеста validDomains приложения. Если пустая строка или URL-адрес не указан, ничего не будет отображаться в уведомлении о собрании.
ChannelData.OnBehalfOf Необязательный; Это предназначено для поддержки атрибутов пользователя.
onBehalfOf.itemid Описывает идентификацию элемента. Его значение должно быть 0.
onBehalfOf.mentionType personключевое слово. Описывает упоминание человека.
onBehalfOf.mri Пользователь MRI отображается как отправитель.
onBehalfOf.displayName Необязательный; имя объекта person. Используется в качестве резервного варианта, если разрешение имен недоступно.

Примечание.

Если указать недопустимые входные данные, API возвращает код состояния 400.

Код ответа

В следующей таблице содержатся коды ответов:

Код ответа Описание
202 Уведомление успешно отправлено.
207 Уведомления отправляются только нескольким участникам.
400 Сбой проверки полезных данных запроса уведомления о собрании.
401 Недопустимый маркер бота.
403 Бот не может отправлять уведомление.
404 Чат собрания не найден или никто из участников не найден в реестре.

Получить API сведений о собрании

API сведений о собрании позволяет приложению получать статические метаданные собрания. Метаданные предоставляют точки данных, которые не изменяются динамически. API доступен через службы ботов. Сейчас как частные запланированные или повторяющиеся собрания, так и запланированные или повторяющиеся собрания канала поддерживают API с различными разрешениями RSC соответственно.

API сведений о собрании должен иметь регистрацию бота и идентификатор бота. Для получения TurnContext требуется bot SDK. Чтобы использовать API сведений о собрании, необходимо получить другое разрешение RSC в зависимости от область любого собрания, например частного собрания или собрания канала.

Примечание.

API сведений о собрании поддерживается для запланированных частных собраний, собраний по расписанию, мгновенных собраний (собрание сейчас), личных звонков и групповых звонков в настольных и мобильных клиентах Teams.

Предварительное условие

Чтобы использовать API сведений о собрании, необходимо получить другое разрешение RSC в зависимости от область любого собрания, например частного собрания или собрания канала.


Для манифеста приложения версии 1.12 и более поздних

Используйте следующий пример, чтобы настроить манифест и authorization свойства манифеста webApplicationInfo приложения для любого закрытого собрания:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]
    }
}

Используйте следующий пример, чтобы настроить манифест webApplicationInfo и authorization свойства вашего приложения для любого собрания канала:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]
    }
}


Для манифеста приложения версии 1.11 и более ранних версий

Используйте следующий пример, чтобы настроить свойство webApplicationInfo манифеста приложения для любого индивидуального собрания:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

Используйте следующий пример для настройки свойства webApplicationInfo манифеста приложения для любого собрания канала:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Примечание.

  • ChannelMeeting.ReadBasic.Group Если разрешение добавлено в манифест, бот автоматически получает события начала или окончания собрания из собраний канала, созданных во всех командах, куда добавляется бот.
  • Для один-на-один вызов organizer является инициатором чата, а для групповых вызовов organizer — инициатором звонка. Для собраний в общедоступных каналах organizer — это пользователь, создавший запись канала.

Параметр запроса

В следующей таблице перечислены параметры запроса:

Значение Тип Обязательный Описание
meetingId String Да Идентификатор собрания доступен через Bot Invoke и библиотеку TeamsJS.

Пример

// Gets the information for the given meeting id.
MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));
Имя свойства Описание
details.id Идентификатор собрания, закодированный как строка BASE64.
details.msGraphResourceId MsGraphResourceId, используемый специально для вызовов MS API Graph.
details.scheduledStartTime Запланированное время начала собрания в формате UTC.
details.scheduledEndTime Запланированное время окончания собрания в формате UTC.
details.joinUrl URL-адрес, используемый для присоединения к собранию.
details.title Название собрания.
details.type Тип собрания (OneToOneCall, GroupCall, Scheduled, Повторяющийся, MeetNow, ChannelScheduled и ChannelRecurring).
conversation.isGroup Логическое значение, указывающее, имеет ли беседа более двух участников.
conversation.conversationType Тип беседы.
conversation.id Идентификатор чата собрания.
organizer.id Идентификатор пользователя организатора.
organizer.aadObjectId Идентификатор объекта Microsoft Entra организатора.
organizer.tenantId Идентификатор клиента Microsoft Entra организатора.

В случае повторяющегося типа собрания:

startDate: указывает дату начала применения шаблона. Значение startDate должно соответствовать значению даты свойства start ресурса события. Первое событие собрания может не произойти в эту дату, если оно не соответствует шаблону.

endDate: указывает дату прекращения применения шаблона. Последнее вхождение собрания может не произойти в эту дату, если оно не соответствует шаблону.

API отправки субтитров в режиме реального времени

API отправки субтитров в режиме реального времени предоставляет конечную точку POST для субтитров перевода в режиме реального времени (CART) Teams, закрытых субтитров с человеческим типом. Текстовое содержимое, отправляемое в эту конечную точку, отображается конечным пользователям в собрании Teams, если для них включены субтитры.

URL-адрес CART

ВЫ можете получить URL-адрес CART для конечной точки POST на странице Параметры собрания в собрании Teams. Подробнее в разделе Субтитры CART на собрании Microsoft Teams. Вам не нужно изменять URL-адрес CART, чтобы использовать субтитры CART.

Параметр запроса

URL-адрес CART включает следующие параметры запроса:

Значение Тип Обязательный Описание
meetingId String Да Идентификатор собрания доступен через Bot Invoke и библиотеку TeamsJS.
Например, meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d
токен String Да Токен авторизации
Например, token=04751eac

Пример

https://api.captions.office.microsoft.com/cartcaption?meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d&token=gjs44ra

Метод

Ресурс Метод Описание
/cartcaption POST Обработка субтитров для собрания, которое было начато

Примечание.

Убедитесь, что тип содержимого для всех запросов — обычный текст в кодировке UTF-8. Текст запроса содержит только субтитры.

Пример

POST /cartcaption?meetingid=04751eac-30e6-47d9-9c3f-0b4ebe8e30d9&token=04751eac&lang=en-us HTTP/1.1
Host: api.captions.office.microsoft.com
Content-Type: text/plain
Content-Length: 22
Hello I’m Cortana, welcome to my meeting.

Примечание.

Каждый запрос POST создает новую строку субтитров. Чтобы у конечного пользователя было достаточно времени для чтения содержимого, ограничьте текст каждого POST-запроса до 80–120 символов.

Коды ошибок

В следующей таблице приведены коды ошибок:

Код ошибки Описание
400 Неправильный запрос. В тексте отклика есть дополнительные сведения. Например, представлены не все необходимые параметры.
401 Недостаточно полномочий. Неверный или просроченный токен. Если вы получаете эту ошибку, создайте новый URL-адрес CART в Teams.
404 Собрание не найдено или не началось. Если вы получили эту ошибку, убедитесь, что вы начали собрание и выберите начальные субтитры. После включения субтитров на собрании вы можете начать публиковать субтитры на собрании.
500 Внутренняя ошибка сервера. Для получения дополнительной информации обратитесь в службу поддержки или оставьте отзыв.

Получение событий собраний Teams в режиме реального времени

Вы можете получать события собрания в режиме реального времени, такие как начало и окончание собрания или события присоединения и выхода участников.

Получение событий начала и окончания собрания

Примечание.

События начала и окончания собрания поддерживаются для запланированных собраний и собраний каналов.

Пользователь может получать информацию о собраниях в режиме реального времени. Как только приложение связывается с собранием, фактическое время начала и окончания собрания передается боту. Фактическое время начала и окончания собрания отличается от запланированного времени начала и окончания. API сведений о собрании предоставляет запланированное время начала и окончания. Событие предоставляет фактическое время начала и окончания.

ChannelMeeting.ReadBasic.Group Если разрешения и OnlineMeeting.ReadBasic.Chat добавлены в манифест, бот автоматически начинает получать события начала или окончания собрания для запланированных типов собраний и собраний канала.

Предварительное условие

Манифест вашего приложения должен иметь свойство webApplicationInfo для получения событий начала и окончания собрания. Используйте следующие примеры для настройки манифеста:


Для манифеста приложения версии 1.12 и более поздних 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]    
    }
}


Для манифеста приложения версии 1.11 и более ранних версий 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat",
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Пример получения событий начала или окончания собрания

Бот получает события начала и окончания собрания через обработчики OnTeamsMeetingStartAsync и OnTeamsMeetingEndAsync . Сведения, связанные с событием собрания, являются частью MeetingStartEventDetails объекта , который включает поля метаданных, такие как , meetingTypetitle, id, joinUrl, startTimeи EndTime.

Примечание.

  • Получить идентификатор собрания от turnContext.ChannelData.
  • Не используйте идентификатор беседы в качестве идентификатора собрания.
  • Не используйте идентификатор собрания из полезных данных событий turncontext.activity.value.

В следующих примерах показано, как записать события начала и окончания собрания.

Событие начала собрания

// Invoked when a Teams Meeting Start event activity is received from the connector.
protected override async Task OnTeamsMeetingStartAsync(MeetingStartEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity. 
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Событие окончания собрания

// Invoked when a Teams Meeting End event activity is received from the connector.
protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Пример полезных данных события начала собрания

В следующем коде приводится пример полезных данных события начала собрания:

{
  "name": " application/vnd.microsoft.meetingStart",
  "type": "event",
  "timestamp": "2023-02-23T19:34:07.478Z",
  "localTimestamp": "2023-02-23T11:34:07.478-8",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/teams/",
  "from": {
    "id": "user_id"
  },
  "conversation": {
    "isGroup": true,
    "conversationType": "groupchat",
    "id": "conversation_id"
  },
  "recipient": {
    "id": "28:65f50003-e15d-434a-9e14-0fcfeb3d7817"
  },
  "value": {
    "id": "meeting_id",
    "joinUrl": "join_url",
    "title": "Example meeting",
    "meetingType": "Scheduled",
    "startTime": "2023-02-23T19:34:07.478Z"
  },
  "channelData": {
    "tenant": {
      "id": "tenant_id"
    }
  }
}

Пример полезных данных события окончания собрания

В следующем коде приводится пример полезных данных события окончания собрания:

{
  "name": " application/vnd.microsoft.meetingEnd",
  "type": "event",
  "timestamp": "2023-02-23T19:34:07.478Z",
  "localTimestamp": "2023-02-23T11:34:07.478-8",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/teams/",
  "from": {
    "id": "user_id"
  },
  "conversation": {
    "isGroup": true,
    "conversationType": "groupchat",
    "id": "conversation_id"
  },
  "recipient": {
    "id": "28:65f50003-e15d-434a-9e14-0fcfeb3d7817"
  },
  "value": {
    "id": "meeting_id",
    "joinUrl": "join_url",
    "title": "Example meeting",
    "meetingType": "Scheduled",
    "EndTime": "2023-02-23T20:30:07.478Z"
  },
  "channelData": {
    "tenant": {
      "id": "tenant_id"
    }
  }
}
Имя свойства Описание
name Имя пользователя.
type Тип действия.
timestamp Локальная дата и время сообщения, выраженные в формате ISO-8601.
id Идентификатор действия.
channelId Канал, с которым связано это действие.
serviceUrl URL-адрес службы, куда должны отправляться ответы на это действие.
from.id Идентификатор пользователя, отправившего запрос.
from.aadObjectId Microsoft Entra идентификатор объекта пользователя, отправив запрос.
conversation.isGroup Логическое значение, указывающее, имеет ли беседа более двух участников.
conversation.tenantId Microsoft Entra идентификатор клиента беседы или собрания.
conversation.id Идентификатор чата собрания.
recipient.id Идентификатор пользователя, получающего запрос.
recipient.name Имя пользователя, получающего запрос.
entities.locale сущность, содержащая метаданные о языковом стандарте.
entities.country сущность, содержащая метаданные о стране.
entities.type сущность, содержащая метаданные о клиенте.
channelData.tenant.id Microsoft Entra идентификатор клиента.
channelData.source Имя источника, из которого запускается или вызывается событие.
channelData.meeting.id Идентификатор по умолчанию, связанный с собранием.
Значение. MeetingType Тип собрания.
Значение. Название Тема собрания.
Значение. Id Идентификатор по умолчанию, связанный с собранием.
Значение. JoinUrl URL-адрес присоединения собрания.
Значение. Starttime Время начала собрания в формате UTC.
Значение. EndTime Время окончания собрания в формате UTC.
locale Языковой стандарт сообщения, заданный клиентом.

Получение событий участников собрания

Бот может получать события собраний в режиме реального времени, например события присоединения участников и выхода из нее. Бот может получать события участников, только если он подписан на эти события на портале разработчика.

Примечание.

  • События участников поддерживаются только для запланированных собраний.
  • Чтобы бот получал события участников, обязательно добавьте бота в собрание, прежде чем участник присоединится к собранию или покинет его.

Чтобы подписаться на события участников, выполните следующие действия.

  1. На портале разработчика откройте приложение бота или импортируйте существующее приложение.

  2. В разделе Подписки на события собрания выберите события:

    • Присоединение к участнику
    • Выход участника

  3. Нажмите кнопку Сохранить.

    Снимок экрана: отображение событий участников на портале разработчика.

  4. Убедитесь, что OnlineMeetingParticipant.Read.Chat разрешение RSC настроено в манифесте приложения.

    Если у вашего приложения нет разрешения RSC, добавьте его в раздел Настройка>разрешений приложения на портале разработчика. Дополнительные сведения см. в разделе Разрешения RSC.

В следующих примерах показано, как записать события присоединения к участникам и выхода из нее.

Пример справочника по коду

//Invoked on participant join a meeting
protected override async Task OnTeamsMeetingParticipantsJoinAsync(MeetingParticipantsEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync("Member has joined the meeting.");
  return;
}

Ниже приведены примеры полезных данных для участия в событиях присоединения и выхода из нее.

Ниже приведен пример полезных данных события присоединения к участнику:

{ 

    "type": "event", 
    "name": "application/vnd.microsoft.meetingParticipantJoin",
    "timestamp": "2023-02-23T19:34:07.478Z", 
    "channelId": "msteams", 
    "serviceUrl": "https://smba.trafficmanager.net/amer/", 
    "from": { 
        "id": "29:id_xyz" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "conversationType": "groupchat", 
        "id": "19:meeting_threadId@thread.v2" 
    }, 
    "recipient": { 
        "id": "28:botid" 
    },  
    "value": { 
       "members": [ 
       { 
        "user": { 
            "tenantId": "tenantid", 
            "objectId": "user_object_Id", 
            "id": "29:userId ", 
            "name": "Test User", 
            "aadObjectId": " user_object_Id " 
        },   
        "meeting": { 
            "inMeeting": true, 
            "role": "Organizer" //Attendee, Organizer, Presenter 
        },  
        }], 
    }, 
    "channelData": { 
        "tenant": { 
            "id": "tenantId" 
        }, 
        "meeting": { 
            "id": "encoded_meetingId" 
        } 
    } 
}

Получение состояния входящего звука

getIncomingClientAudioState API позволяет приложению получить параметр состояния входящего звука для пользователя собрания. API доступен через библиотеку TeamsJS.

Примечание.

  • getIncomingClientAudioState API для мобильных устройств доступен в общедоступной предварительной версии для разработчиков.
  • toggleIncomingClientAudio API доступен в новом клиенте Teams.
  • Согласие на использование конкретного ресурса доступно для манифеста версии 1.12 и более поздних версий, поэтому этот API не работает для манифеста версии 1.11 и более ранних версий.

Манифест

"authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
          "type": "Delegated"
        }
      ]
    }
  }

Пример

callback = (errcode, result) => {
        if (errcode) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The getIncomingClientAudioState API shows the current audio state.
microsoftTeams.meeting.getIncomingClientAudioState(this.callback)

Параметр запроса

В следующей таблице содержится параметр запроса:

Значение Тип Обязательный Описание
callback String Да Обратный вызов содержит два параметра error и result. Ошибка может содержать тип SdkError ошибки или null при успешном получении звука. Результат может содержать значение true или false при успешном получении звука или значение NULL при сбое выборки звука. Входящий звук отключается, если результат имеет значение true, и отключается, если результат имеет значение false.

Коды ответа

В следующей таблице приведены коды ответов:

Код ответа Описание
500 Внутренняя ошибка.
501 API не поддерживается в текущем контексте.
1000 Приложение не имеет необходимых разрешений для предоставления общего доступа к этапу.

Переключение входящего звука

toggleIncomingClientAudio API позволяет приложению переключать параметр состояния входящего звука для пользователя собрания с включения звука или наоборот. API доступен через библиотеку TeamsJS.

Примечание.

  • toggleIncomingClientAudio API для мобильных устройств доступен в общедоступной предварительной версии для разработчиков.
  • Согласие на использование конкретного ресурса доступно для манифеста версии 1.12 и более поздних версий, поэтому этот API не работает для манифеста версии 1.11 и более ранних версий.

Манифест

"authorization": {
 "permissions": {
  "resourceSpecific": [
   {
    "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
    "type": "Delegated"
   }
  ]
 }
}

Пример

callback = (error, result) => {
        if (error) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The toggleIncomingClientAudio API allows an app to toggle the incoming audio state.
microsoftTeams.meeting.toggleIncomingClientAudio(this.callback)

Параметр запроса

В следующей таблице содержится параметр запроса:

Значение Тип Обязательный Описание
callback String Да Обратный вызов содержит два параметра error и result. Ошибка может содержать тип SdkError ошибки или null при успешном выполнении переключателя. Результат может содержать значение true или false при успешном выполнении переключателя или значение NULL при сбое переключателя. Входящий звук отключается, если результат имеет значение true, и отключается, если результат имеет значение false.

Код ответа

В следующей таблице приведены коды ответов:

Код ответа Описание
500 Внутренняя ошибка.
501 API не поддерживается в текущем контексте.
1000 Приложение не имеет необходимых разрешений для предоставления общего доступа к этапу.

Пример кода

Название примера Описание .NET Node.js Манифест
Расширяемость собраний Пример расширяемости собраний Teams для передачи маркеров. Просмотр Просмотр Просмотр
Уведомление на собрании Демонстрирует реализацию уведомлений на собрании с помощью бота. Просмотр Просмотр Просмотр
Боковая панель собрания Пример расширяемости собраний Teams для взаимодействия с боковой панелью в собрании. Просмотр Просмотр
Вкладка "Сведения" в собрании В этом примере приложения показана функция расширения собраний Teams, с помощью которой пользователь может создать опрос, а участники могут отвечать на опрос на собрании. Просмотр Просмотр Просмотр
Пример событий собрания В этом примере показаны события собраний Teams в режиме реального времени с помощью бота. Просмотр Просмотр Просмотр
Образец собрания для набора сотрудников В этом примере приложения показан интерфейс собрания для сценария набора с помощью приложений на собраниях. Просмотр Просмотр Просмотр

Дополнительные ресурсы