API de aplicaciones de reunión

  • Artículo

La extensibilidad de la reunión proporciona API para mejorar la experiencia de reunión. Puede realizar lo siguiente con la ayuda de las API enumeradas:

  • Cree aplicaciones o integre aplicaciones existentes dentro del ciclo de vida de las reuniones.
  • Use las API para que la aplicación sea consciente de la reunión.
  • Seleccione las API necesarias para mejorar la experiencia de reunión.

Nota:

Use la biblioteca cliente de JavaScript de Microsoft Teams (TeamsJS) (versión: 1.10 y posteriores) para que el inicio de sesión único (SSO) funcione en el panel lateral de la reunión.

En la tabla siguiente se proporciona una lista de las API disponibles en la biblioteca de JavaScript de Microsoft Teams y Microsoft Bot Framework SDK:

Método Descripción Origen
Obtener el contexto de usuario Obtenga información contextual para mostrar el contenido pertinente en una pestaña de Microsoft Teams. Biblioteca teamsJS
Obtener participante Capture la información de los participantes por id. de reunión e id. de participante. SDK de Microsoft Bot Framework
Enviar notificación en la reunión Proporciona señales de reunión mediante la API de notificación de conversación existente para el chat de bot de usuario y permite al bot notificar a la acción del usuario que muestra una notificación en la reunión. SDK de Microsoft Bot Framework
Obtener detalles de la reunión Obtener los metadatos estáticos de una reunión. SDK de Microsoft Bot Framework
Enviar subtítulos en tiempo real Enviar subtítulos en tiempo real a una reunión en curso. Biblioteca teamsJS
Compartir contenido de la aplicación en la fase Comparta partes específicas de la aplicación en la fase de reunión desde el panel lateral de la aplicación en una reunión. Biblioteca teamsJS
Recepción de eventos de reunión de Teams en tiempo real Reciba eventos de reunión en tiempo real, como el inicio y el fin de la reunión o la unión y salida de participantes. SDK de Microsoft Bot Framework
Obtener el estado de audio entrante Permite que una aplicación obtenga la configuración de estado de audio entrante para el usuario de la reunión. Biblioteca teamsJS
Alternar audio entrante Permite que una aplicación alterne la configuración de estado de audio entrante para el usuario de la reunión de silenciar a unmute o viceversa. Biblioteca teamsJS

Obtener API de contexto de usuario

Importante

  • De forma predeterminada, el nuevo cliente de Teams admite el tema claro para las aplicaciones en reuniones de Teams. Cuando la propiedad de getContext app.theme API devuelve el valor, el default cliente de Teams está en un tema claro.
  • La versión anterior de los clientes de Teams solo admite el tema Oscuro y contraste para las aplicaciones en reuniones de Teams

Para identificar y recuperar información contextual del contenido de la pestaña, vea obtener contexto para la pestaña de Teams. meetingId se usa en una pestaña que se ejecuta en el contexto de la reunión y se agrega para la carga de respuesta.

Ejemplos

A continuación se muestran las respuestas de TeamsJS v2 para Obtener la API de contexto de usuario en función del tipo de reunión, el tipo de usuario y el tipo de llamada:

  • Tipo de reunión

    A continuación se muestra una respuesta de carga JSON para una reunión de canal para usuarios en el inquilino:

    {
    "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
       }
      }

  • Tipo de usuario

    A continuación se muestra una respuesta de carga JSON en una reunión privada programada para un usuario invitado:

      {
        "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"
        }
  }

  • Tipo de llamada  

    A continuación se muestra una respuesta de carga JSON para una llamada uno a uno para un usuario en el inquilino:

          {
       "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
       }
      }

Obtener API de participante

La API de GetParticipant debe tener un identificador y un registro de bot para generar tokens de autenticación. Para obtener más información, consulte el registro del bot y el identificador.

Nota:

  • El tipo de usuario no se incluye en la API getParticipantRole .
  • No almacene en caché los roles de participante, ya que el organizador de la reunión puede cambiar los roles en cualquier momento.
  • Actualmente, la GetParticipant API solo se admite para listas de distribuciones o listas con menos de 350 participantes.

Parámetros de consulta

Sugerencia

Obtenga los identificadores de participante y los identificadores de inquilino de la pestaña autenticación SSO.

La Meeting API debe tener meetingId, participantIdy tenantId como parámetros de dirección URL. Los parámetros están disponibles como parte de la biblioteca cliente JavaScript (TeamsJS) de Microsoft Teams y la actividad del bot.

En la tabla siguiente se incluyen los parámetros de consulta:

Valor Tipo Obligatorio Descripción
Id. de la reunión Cadena Sí El identificador de reunión está disponible a través de Bot Invoke y la biblioteca TeamsJS.
Id. del participante Cadena Sí El id. de participante es el identificador de usuario. Está disponible en Tab SSO, Bot Invoke y la biblioteca TeamsJS. Se recomienda obtener un ID de participante en la pestaña SSO.
tenantId Cadena Sí El identificador de inquilino es necesario para los usuarios del inquilino. Está disponible en Tab SSO, Bot Invoke y la biblioteca TeamsJS. Se recomienda obtener un identificador de inquilino desde la pestaña SSO.

Ejemplo

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);
}
Nombre de propiedad Description
user.id Identificador del usuario.
user.aadObjectId Microsoft Entra identificador de objeto del usuario.
user.name Nombre del usuario.
user.givenName Nombre del usuario.
user.surname Apellidos del usuario.
user.email Id. de correo del usuario.
user.userPrincipalName UPN del usuario.
user.tenantId Microsoft Entra identificador de inquilino.
user.userRole Rol del usuario. Por ejemplo, "admin" o "user".
meeting.role El rol del participante en la reunión. Por ejemplo, "Organizer" o "Presenter" o "Attendee".
meeting.inMeeting Valor que indica si el participante está en la reunión.
conversation.id Identificador de chat de reunión.
conversation.isGroup Boolean que indica si la conversación tiene más de dos participantes.

Códigos de respuesta

En la tabla siguiente se proporcionan los códigos de respuesta:

Código de respuesta Descripción
403 La obtención de información de participantes no se comparte con la aplicación. Si la aplicación no está instalada en la reunión, desencadena la respuesta de error 403. Si el administrador de inquilinos deshabilita o bloquea la aplicación durante la migración del sitio activo, desencadena la respuesta de error 403.
200 La información del participante se recupera correctamente.
401 La aplicación responde con un token no válido.
404 La reunión ha expirado o los participantes no están disponibles.

Enviar una notificación en la reunión

Todos los usuarios de una reunión reciben las notificaciones enviadas a través de la carga de notificación en la reunión. La carga de notificación en la reunión desencadena una notificación en la reunión y le permite proporcionar señales de reunión que se entregan mediante la API de notificación de conversación existente para el chat de bot de usuario. Puede enviar una notificación en la reunión en función de la acción del usuario. La carga está disponible a través de Bot Services.

También puede enviar una notificación dirigida en la reunión a un participante específico de una reunión. Para obtener más información, vea Notificación dirigida en la reunión.

Nota:

  • Cuando se invoca una notificación en la reunión, el contenido se presenta como un mensaje de chat.
  • Debe invocar la función submitTask() para descartarla automáticamente después de que un usuario realice una acción en la vista web. Este es un requisito para el envío de aplicaciones. Para obtener más información, vea módulo de tareas del SDK de Teams.
  • Si desea que la aplicación admita usuarios anónimos, la carga de solicitud de invocación inicial debe basarse en from.id metadatos de solicitud en from objeto, no from.aadObjectId metadatos de solicitud. from.ides el identificador de usuario y from.aadObjectId es el Microsoft Entra ID del usuario. Para obtener más información, vea usar módulos de tareas en pestañas y crear y enviar el módulo de tareas.

Parámetro de consulta

En la tabla siguiente se incluye el parámetro de consulta:

Valor Tipo Obligatorio Descripción
conversationId Cadena Sí El identificador de conversación está disponible como parte de Bot Invoke.

Ejemplos

Bot ID se declara en el manifiesto y el bot recibe un objeto de resultado.

Nota:

  • El completionBotId parámetro de externalResourceUrl es opcional en el ejemplo de carga solicitada.
  • Los externalResourceUrl parámetros de ancho y alto deben estar en píxeles. Para obtener más información, vea instrucciones de diseño.
  • La dirección URL es la página, que se carga como <iframe> en la notificación en la reunión. El dominio debe estar en la matriz validDomains de las aplicaciones en el manifiesto de la aplicación.
// 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);
Nombre de propiedad Descripción
type Tipo de actividad.
text Contenido de texto del mensaje.
summary Texto de resumen del mensaje.
channelData.notification.alertInMeeting Boolean que indica si se va a mostrar una notificación al usuario durante una reunión.
channelData.notification.externalResourceUrl Valor de la dirección URL del recurso externo de la notificación.
replyToId Identificador del mensaje primario o raíz del subproceso.
APP_ID Id. de aplicación declarado en manifiesto.
completionBotId Id. de aplicación de bot.

Códigos de respuesta

En la tabla siguiente se incluyen los códigos de respuesta:

Código de respuesta Descripción
201 La actividad con señal se ha enviado correctamente.
401 La aplicación responde con un token no válido.
403 La aplicación no puede enviar la señal. El código de respuesta 403 puede producirse debido a varias razones, como que el administrador de inquilinos deshabilite y bloquee la aplicación durante la migración del sitio en vivo. En este caso, la carga contiene un mensaje de error detallado.
404 El chat de la reunión no existe.

Api de badging de notificación de reunión y de aplicación de destino

La targetedMeetingNotification API permite a las aplicaciones enviar notificaciones en la reunión de destino y muestra el icono de la aplicación que se está descargando a participantes específicos de una reunión. Las aplicaciones envían notificaciones en la reunión de destino e icono de aplicación que se malintegre en función de la acción del usuario. La API está disponible a través de bot API.

Requisito previo

Debe configurar el manifiesto de la aplicación con permisos de RSC en la webApplicationInfo propiedad para enviar notificaciones en la reunión de destino y mostrar el icono de aplicación que se está descargando a participantes específicos de una reunión. Use los ejemplos siguientes para configurar el manifiesto:


Para la versión 1.12 y posteriores del manifiesto de la aplicación 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}


Para la versión 1.11 del manifiesto de la aplicación y versiones anteriores 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

Nota:

  • La carga de API solo permite un cuadro de diálogo con una dirección URL.
  • No se admiten los formatos de identificador de usuario aadObjectid y UPN .

Obtenga el formato de id. de usuario admitido para la notificación en la reunión de destino y el icono de la aplicación con errores:

Ejemplo

A continuación se muestra un ejemplo de carga útil de la solicitud para la notificación en la reunión de destino y el icono de la aplicación con errores:

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"      } 
    ] 
  }
}
Nombre de propiedad Description
meetingId El identificador de reunión está disponible a través de la invocación del bot y la biblioteca teamsJS.
type targetedMeetingNotification
recipients Lista de identificadores de usuario. Obtenga identificadores de usuario para los participantes de la reunión a través de Get participant API. Obtenga toda la lista de la lista de chats mediante get members API. La lista de destinatarios vacíos o null devolverá 400.
surface Tipo de superficie. Los tipos de superficie admitidos son meetingStage y meetingTabIcon.
surfaces Lista de superficies donde se pueden representar notificaciones.
contentType Tipo de contenido que representa la notificación en la reunión de destino. El valor admitido es task.
content TaskModuleContinueResponse
content.value.height Opcional; altura solicitada de la notificación.
content.value.width Opcional; ancho solicitado de la notificación.
content.value.title Opcional; título de la notificación.
content.value.url Opcional; Dirección URL que se va a representar en la notificación. Asegúrese de que la dirección URL forma parte del manifiesto de validDomains la aplicación. Si se proporciona una cadena vacía o no se proporciona ninguna dirección URL, no se representará nada en una notificación de reunión.
ChannelData.OnBehalfOf Opcional; esto es para admitir atributos de usuario.
onBehalfOf.itemid Describe la identificación del elemento. Su valor debe ser 0.
onBehalfOf.mentionType person Palabra clave. Describe la mención de una persona.
onBehalfOf.mri MrI de usuario que se muestra como remitente.
onBehalfOf.displayName Opcional; nombre de .person Se usa como reserva en caso de que la resolución de nombres no esté disponible.

Nota:

Si proporciona una entrada no válida, la API devuelve el código de estado 400.

Código de respuesta

En la tabla siguiente se incluyen los códigos de respuesta:

Código de respuesta Descripción
202 La notificación se envía correctamente.
207 Las notificaciones se envían solo a algunos participantes.
400 Error en la validación de la carga de la solicitud de notificación de reunión.
401 El token de bot no es válido.
403 El bot no puede enviar la notificación.
404 No se encontró el chat de reunión o no se encontró ninguno de los participantes en la lista.

Api de obtención de detalles de la reunión

La API de detalles de la reunión permite a la aplicación obtener los metadatos estáticos de una reunión. Los metadatos proporcionan puntos de datos que no cambian dinámicamente. La API está disponible a través de Bot Services. Actualmente, las reuniones privadas programadas o periódicas y las reuniones programadas o periódicas de canal admiten la API con diferentes permisos de RSC, respectivamente.

La API de detalles de la reunión debe tener un registro de bot y un identificador de bot. Requiere bot SDK para obtener TurnContext. Para usar la API de detalles de la reunión, debe obtener permisos de RSC diferentes en función del ámbito de cualquier reunión, como reunión privada o reunión de canal.

Nota:

La API de detalles de reunión es compatible con reuniones privadas programadas, reuniones de canal programadas, reuniones instantáneas (reunirse ahora), llamadas uno a uno y llamadas grupales en clientes móviles y de escritorio de Teams.

Requisito previo

Para usar la API de detalles de la reunión, debe obtener permisos de RSC diferentes en función del ámbito de cualquier reunión, como reunión privada o reunión de canal.


Para la versión 1.12 y posteriores del manifiesto de la aplicación

Use el ejemplo siguiente para configurar las propiedades y authorization del manifiesto de la webApplicationInfo aplicación para cualquier reunión privada:

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

Utilice el siguiente ejemplo para configurar los manifiestos webApplicationInfo y authorization propiedades de su aplicación para cualquier reunión de canal:

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


Para la versión 1.11 del manifiesto de la aplicación y versiones anteriores

Use el ejemplo siguiente para configurar la propiedad webApplicationInfo del manifiesto de la aplicación para cualquier reunión privada:

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

Use el ejemplo siguiente para configurar la propiedad webApplicationInfo del manifiesto de la aplicación para cualquier reunión de canal:

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

Nota:

  • Si se agrega el ChannelMeeting.ReadBasic.Group permiso al manifiesto, el bot recibe automáticamente los eventos de inicio o finalización de la reunión de las reuniones de canal creadas en todos los equipos donde se agrega el bot.
  • Para una llamada organizer uno a uno es el iniciador del chat y para las llamadas grupales organizer es el iniciador de llamadas. Para las organizer reuniones de canal público es la persona que creó la publicación del canal.

Parámetro de consulta

En la tabla siguiente se muestra el parámetro de consulta:

Valor Tipo Obligatorio Descripción
Id. de la reunión Cadena Sí El identificador de reunión está disponible a través de Bot Invoke y la biblioteca TeamsJS.

Ejemplo

// 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));
Nombre de propiedad Description
details.id Identificador de la reunión, codificado como una cadena BASE64.
details.msGraphResourceId MsGraphResourceId, que se usa específicamente para llamadas de Graph API de MS.
details.scheduledStartTime Hora de inicio programada de la reunión, en UTC.
details.scheduledEndTime Hora de finalización programada de la reunión, en UTC.
details.joinUrl Dirección URL usada para unirse a la reunión.
details.title El título de la reunión.
details.type Tipo de reunión (OneToOneCall, GroupCall, Scheduled, Recurring, MeetNow, ChannelScheduled y ChannelRecurring).
conversation.isGroup Boolean que indica si la conversación tiene más de dos participantes.
conversation.conversationType Tipo de conversación.
conversation.id Identificador de chat de reunión.
organizer.id Identificador de usuario del organizador.
organizer.aadObjectId Identificador de objeto Microsoft Entra del organizador.
organizer.tenantId Identificador de inquilino Microsoft Entra del organizador.

En el caso del tipo de reunión periódico:

startDate: especifica la fecha para empezar a aplicar el patrón. El valor de startDate debe corresponder al valor de fecha de la propiedad start en el recurso de evento. Es posible que la primera aparición de la reunión no se produzca en esta fecha si no se ajusta al patrón.

endDate: especifica la fecha para dejar de aplicar el patrón. Es posible que la última aparición de la reunión no se produzca en esta fecha si no se ajusta al patrón.

Enviar API de subtítulos en tiempo real

La API de envío de subtítulos en tiempo real expone un punto de conexión POST para los subtítulos de traducción en tiempo real (CART) de acceso a la comunicación de Teams, subtítulos con tipo humano. El contenido de texto enviado a este punto de conexión aparece para los usuarios finales en una reunión de Teams cuando tienen subtítulos habilitados.

DIRECCIÓN URL CART

Puede obtener la dirección URL de CART para el punto de conexión POST en la página Opciones de reunión de una reunión de Teams. Para obtener más información, vea subtítulos CART en una reunión de Microsoft Teams. No es necesario modificar la dirección URL de CART para usar subtítulos CART.

Parámetro de consulta

La dirección URL de CART incluye los siguientes parámetros de consulta:

Valor Tipo Obligatorio Descripción
Id. de la reunión Cadena Sí El identificador de reunión está disponible a través de Bot Invoke y la biblioteca TeamsJS.
Por ejemplo, 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 Cadena Sí Token de autorización.
Por ejemplo, token=04751eac

Ejemplo

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

Método

Resource Método Descripción
/cartcaption POST Controlar los subtítulos de la reunión, que se inició

Nota:

Asegúrese de que el tipo de contenido de todas las solicitudes es texto sin formato con codificación UTF-8. El cuerpo de la solicitud solo contiene subtítulos.

Ejemplo

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.

Nota:

Cada solicitud POST genera una nueva línea de títulos. Para asegurarse de que el usuario final tiene tiempo suficiente para leer el contenido, limite cada cuerpo de la solicitud POST a 80-120 caracteres.

Códigos de error

En la tabla siguiente se proporcionan los códigos de error:

Código de error Descripción
400 Solicitud incorrecta. El cuerpo de la respuesta tiene más información. Por ejemplo, no de todos los parámetros necesarios presentados.
401 No autorizado. Token incorrecto o expirado. Si recibe este error, genere una nueva dirección URL de CART en Teams.
404 Reunión no encontrada o no iniciada. Si recibe este error, asegúrese de iniciar la reunión y seleccione Iniciar subtítulos. Después de habilitar los subtítulos en la reunión, puede empezar a colocar subtítulos en la reunión.
500 Error interno del servidor. Para obtener más información, póngase en contacto con el soporte técnico o proporcione comentarios.

Recepción de eventos de reunión de Teams en tiempo real

Puede recibir eventos de reunión en tiempo real, como eventos de inicio y finalización de la reunión o de unirse a participantes y dejar eventos.

Recepción de eventos de inicio y finalización de reuniones

Nota:

Los eventos de inicio y finalización de la reunión son compatibles con las reuniones programadas y de canal.

El usuario puede recibir eventos de reunión en tiempo real. En cuanto una aplicación se asocia a una reunión, la hora real de inicio y fin de la misma se comparte con el bot. La hora de inicio y finalización real de una reunión es diferente de la hora de inicio y finalización programada. La API de detalles de la reunión proporciona la hora de inicio y finalización programada. El evento proporciona la hora de inicio y finalización real.

Si se agregan los ChannelMeeting.ReadBasic.Group permisos y OnlineMeeting.ReadBasic.Chat en el manifiesto, el bot comienza a recibir automáticamente los eventos de inicio o finalización de la reunión para los tipos de reunión programados y de canal.

Requisito previo

El manifiesto de la aplicación debe tener la propiedad webApplicationInfo para recibir los eventos de inicio y finalización de la reunión. Use los ejemplos siguientes para configurar el manifiesto:


Para la versión 1.12 y posteriores del manifiesto de la aplicación 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]    
    }
}


Para la versión 1.11 del manifiesto de la aplicación y versiones anteriores 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat",
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Ejemplo de obtención de eventos de inicio o finalización de la reunión

El bot recibe los eventos de inicio y finalización de la reunión a través de los OnTeamsMeetingStartAsync controladores y OnTeamsMeetingEndAsync . La información relacionada con el evento de reunión forma parte del MeetingStartEventDetails objeto , que incluye los campos de metadatos como, , meetingTypetitle, id, joinUrl, startTimey EndTime.

Nota:

  • Obtener id. de reunión de turnContext.ChannelData.
  • No use el identificador de conversación como id. de reunión.
  • No use el id. de reunión de la carga de eventos de reunión turncontext.activity.value.

En los ejemplos siguientes se muestra cómo capturar los eventos de inicio y finalización de la reunión:

Evento de inicio de reunión

// 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));
}

Evento de fin de reunión

// 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));
}

Ejemplo de carga del evento de inicio de reunión

El código siguiente proporciona un ejemplo de carga del evento de inicio de reunión:

{
  "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"
    }
  }
}

Ejemplo de carga del evento de finalización de la reunión

El código siguiente proporciona un ejemplo de carga del evento de finalización de la reunión:

{
  "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"
    }
  }
}
Nombre de propiedad Descripción
name Nombre del usuario.
type Tipo de actividad.
timestamp Fecha y hora locales del mensaje, expresados en formato ISO-8601.
id Identificador de la actividad.
channelId Canalizar con el que está asociada esta actividad.
serviceUrl Dirección URL del servicio donde se deben enviar respuestas a esta actividad.
from.id Id. del usuario que envió la solicitud.
from.aadObjectId Microsoft Entra identificador de objeto del usuario que envió la solicitud.
conversation.isGroup Boolean que indica si la conversación tiene más de dos participantes.
conversation.tenantId Microsoft Entra identificador de inquilino de la conversación o reunión.
conversation.id Identificador de chat de reunión.
recipient.id Identificador del usuario que recibe la solicitud.
recipient.name Nombre del usuario que recibe la solicitud.
entities.locale entidad que contiene metadatos sobre la configuración regional.
entities.country entidad que contiene metadatos sobre el país.
entities.type entidad que contiene metadatos sobre el cliente.
channelData.tenant.id Microsoft Entra identificador de inquilino.
channelData.source Nombre de origen desde el que se desencadena o se invoca el evento.
channelData.meeting.id Identificador predeterminado asociado a la reunión.
Valor. MeetingType Tipo de reunión.
Valor. Título El tema de la reunión.
Valor. Id Identificador predeterminado asociado a la reunión.
Valor. JoinUrl Dirección URL de unión de la reunión.
Valor. Starttime Hora de inicio de la reunión en UTC.
Valor. Endtime Hora de finalización de la reunión en UTC.
locale Configuración regional del mensaje establecido por el cliente.

Recepción de eventos de participantes en la reunión

El bot puede recibir eventos de reunión en tiempo real, como unirse a participantes y dejar eventos. Un bot solo puede recibir los eventos de los participantes si está suscrito a estos eventos en el Portal para desarrolladores.

Nota:

  • Los eventos de participantes solo se admiten para las reuniones programadas.
  • Para que un bot reciba eventos de participantes, asegúrese de agregar el bot a la reunión antes de que un participante se una o salga de la reunión.

Para suscribirse a eventos de participantes, siga estos pasos:

  1. En el Portal para desarrolladores , abra la aplicación de bot o importe una aplicación existente.

  2. En la sección Suscripciones a eventos de reunión , seleccione los eventos:

    • Unirse a los participantes
    • Salida del participante

  3. Seleccione Guardar.

    Captura de pantalla que muestra cómo se muestra el portal para desarrolladores para los eventos de participantes.

  4. Asegúrese de que el permiso RSC está configurado en el OnlineMeetingParticipant.Read.Chat manifiesto de la aplicación.

    Si la aplicación no tiene el permiso RSC, agréguelo a través de la sección Configurar>permisos de la aplicación en el Portal para desarrolladores. Para obtener más información, consulte Permisos de RSC.

En los ejemplos siguientes se muestra cómo capturar los eventos de unión y salida de participantes:

Referencia de código de ejemplo

//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;
}

A continuación se muestran los ejemplos de las cargas de eventos de unión y salida de participantes:

A continuación se muestra un ejemplo de la carga del evento de combinación de participantes:

{ 

    "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" 
        } 
    } 
}

Obtener el estado de audio entrante

La getIncomingClientAudioState API permite a una aplicación obtener la configuración de estado de audio entrante para el usuario de la reunión. La API está disponible a través de la biblioteca TeamsJS.

Nota:

  • La getIncomingClientAudioState API para dispositivos móviles está disponible en versión preliminar para desarrolladores públicos.
  • La toggleIncomingClientAudio API está disponible en el nuevo cliente de Teams.
  • El consentimiento específico del recurso está disponible para la versión de manifiesto 1.12 y versiones posteriores, por lo que esta API no funciona para la versión de manifiesto 1.11 y versiones anteriores.

Manifiesto

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

Ejemplo

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)

Parámetro de consulta

En la tabla siguiente se incluye el parámetro de consulta:

Valor Tipo Obligatorio Descripción
callback Cadena Sí La devolución de llamada contiene dos parámetros error y result. El error puede contener un tipo SdkError de error o null cuando la captura de audio se realiza correctamente. El resultado puede contener un valor true o false cuando la captura de audio es correcta o null cuando se produce un error en la captura de audio. El audio entrante se silencia si el resultado es true y no semuta si el resultado es false.

Códigos de respuesta

En la tabla siguiente se proporcionan los códigos de respuesta:

Código de respuesta Descripción
500 Error interno.
501 La API no se admite en el contexto actual.
1 000 La aplicación no tiene los permisos adecuados para permitir que el recurso compartido se almacene en fase.

Alternar audio entrante

La toggleIncomingClientAudio API permite que una aplicación alterne la configuración de estado de audio entrante para el usuario de la reunión de silenciar a unmute o viceversa. La API está disponible a través de la biblioteca TeamsJS.

Nota:

  • La toggleIncomingClientAudio API para dispositivos móviles está disponible en versión preliminar para desarrolladores públicos.
  • El consentimiento específico del recurso está disponible para la versión de manifiesto 1.12 y versiones posteriores, por lo que esta API no funciona para la versión de manifiesto 1.11 y versiones anteriores.

Manifiesto

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

Ejemplo

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)

Parámetro de consulta

En la tabla siguiente se incluye el parámetro de consulta:

Valor Tipo Obligatorio Descripción
callback Cadena Sí La devolución de llamada contiene dos parámetros error y result. El error puede contener un tipo SdkError de error o null cuando el botón de alternancia se realiza correctamente. El resultado puede contener un valor true o false, cuando el botón de alternancia es correcto o null cuando se produce un error en la alternancia. El audio entrante se silencia si el resultado es true y no semuta si el resultado es false.

Código de respuesta

En la tabla siguiente se proporcionan los códigos de respuesta:

Código de respuesta Descripción
500 Error interno.
501 La API no se admite en el contexto actual.
1 000 La aplicación no tiene los permisos adecuados para permitir que el recurso compartido se almacene en fase.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Extensibilidad de reuniones Ejemplo de extensibilidad de reuniones de Teams para pasar tokens. View View View
Notificación en la reunión Muestra cómo implementar la notificación en la reunión mediante el bot. View View View
Panel lateral de la reunión Ejemplo de extensibilidad de reuniones de Teams para interactuar con el panel lateral en la reunión. View View
Pestaña Detalles de la reunión Esta aplicación de ejemplo muestra la característica de extensibilidad de reuniones de Teams, donde el usuario puede crear un sondeo y los miembros pueden responder al sondeo en la reunión. View View View
Ejemplo de eventos de reunión En este ejemplo se muestran eventos de reunión de Teams en tiempo real mediante bot. View View View
Muestra de contratación de reuniones Esta aplicación de ejemplo muestra una experiencia de reunión para el escenario de contratación mediante aplicaciones en reuniones. View View Ver

Consulte también