Referencias API de aplicaciones de reuniones

Las extensibilidades de la reunión proporcionan API para transformar la experiencia de la reunión:

  • Cree aplicaciones o integre aplicaciones existentes en el ciclo de vida de la reunión.
  • Usa las API para que la aplicación conozca la reunión.
  • Seleccione las API que desea usar para mejorar la experiencia de reunión.

En la tabla siguiente se proporciona una lista de API:

API Descripción Solicitud Origen
GetUserContext Esta API le permite obtener información contextual para mostrar contenido relevante en una Teams pestaña. microsoftTeams.getContext( ( ) => { /... / } ) Microsoft Teams SDK de cliente
GetParticipant Esta API permite que un bot obtenga información de los participantes mediante el identificador de reunión y el identificador de participante. GET /v1/meetings/{meetingId}/participants/{participantId}?tenantId={tenantId} Microsoft Bot Framework SDK
NotificationSignal Esta API 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 bots de usuario. Le permite señalar en función de la acción del usuario que muestra un cuadro de diálogo en la reunión. POST /v3/conversations/{conversationId}/activities Microsoft Bot Framework SDK
Detalles de la reunión Esta API le permite obtener metadatos estáticos de reunión. GET /v1/meetings/{meetingId} Bot SDK

En la tabla siguiente se proporcionan los métodos del SDK de Bot Framework para las API:

API Bot Framework SDK (método)
GetParticipant GetMeetingParticipantAsync (Microsoft.Bot.Builder.ITurnContext turnContext, string meetingId = default, string participantId = default, string tenantId = default, System.Threading.CancellationToken cancellationToken = default);
NotificationSignal activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=&height=&width=&title=<title>&completionBotId=BOT_APP_ID");
Detalles de la reunión TeamsMeetingInfo (string id = default);

GetUserContext API

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

GetParticipant API

Nota

  • No almacenar en caché los roles de los participantes, ya que el organizador de la reunión puede cambiar los roles en cualquier momento.
  • Teams actualmente no admite listas de distribución grandes ni tamaños de lista de más de 350 participantes GetParticipant API.

La GetParticipant API permite que un bot obtenga información de los participantes mediante el identificador de reunión y el identificador de participante. La API incluye parámetros de consulta, ejemplos y códigos de respuesta.

Parámetros de consulta

La GetParticipant API incluye los siguientes parámetros de consulta:

Valor Tipo Necesario Descripción
meetingId Cadena El identificador de reunión está disponible a través de Bot Invoke y Teams CLIENT SDK.
participantId Cadena El identificador de participante es el identificador de usuario. Está disponible en TAB SSO, Bot Invoke y Teams Client SDK. Se recomienda obtener un identificador de participante del SSO de la pestaña.
tenantId Cadena El identificador de inquilino es necesario para los usuarios del espacio empresarial. Está disponible en TAB SSO, Bot Invoke y Teams Client SDK. Se recomienda obtener un identificador de inquilino del SSO de la pestaña.

Ejemplo

La GetParticipant API incluye los siguientes ejemplos:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}

El cuerpo de la respuesta JSON GetParticipant para la API es:

{
   "user":{
      "id":"29:1JKiJGPAX9TTxtGxhVo0wLx_zwzo-gG8Z-X03306vBwi9p-xMTEbDXsT6KH7-0kkTS8cD-2zkrsoV6f5WJ6_aYw",
      "aadObjectId":"e236c4bf-88b1-4f3a-b1d7-8891dfc332b5",
      "name":"Bob Young",
      "givenName":"Bob",
      "surname":"Young",
      "email":"Bob.young@microsoft.com",
      "userPrincipalName":"Bob.young@microsoft.com",
      "tenantId":"2fe477ab-0efc-4dfd-bde2-484374e2c373",
      "userRole":"user"
   },
   "meeting":{
      "role ":"Presenter",
      "inMeeting":true
   },
   "conversation":{
      "id":"<conversation id>",
      "isGroup":true
   }
}

Códigos de respuesta

La GetParticipant API devuelve los siguientes códigos de respuesta:

Código de respuesta Descripción
403 Obtener información de participante no se comparte con la aplicación. Si la aplicación no está instalada en la reunión, desencadena la respuesta de error 403 más común. Si el administrador del espacio empresarial deshabilita o bloquea la aplicación durante la migración del sitio en directo, se 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 no se encuentra el participante.

NotificationSignal API

Todos los usuarios de una reunión reciben las notificaciones enviadas a través de la NotificationSignal API.

Nota

  • Cuando se invoca un cuadro de diálogo en la reunión, el contenido se presenta como un mensaje de chat.
  • Actualmente, no se admite el envío de notificaciones dirigidas.

NotificationSignal La API 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 bots de usuario. Esta API le permite señalar en función de la acción del usuario que muestra un cuadro de diálogo en la reunión. La API incluye parámetros de consulta, ejemplos y códigos de respuesta.

Parámetro de consulta

La NotificationSignal API incluye el siguiente parámetro de consulta:

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

Ejemplos

Se Bot ID declara en el manifiesto y el bot recibe un objeto result.

Nota

  • El completionBotId parámetro de la es opcional en el ejemplo de carga externalResourceUrl solicitada. Bot ID se declara en el manifiesto y el bot recibe un objeto result.
  • Los externalResourceUrl parámetros de ancho y alto deben estar en píxeles. Para asegurarse de que las dimensiones están dentro de los límites permitidos, vea directrices de diseño.
  • La dirección URL es la página cargada como una en el cuadro de diálogo <iframe> en la reunión. El dominio debe estar en la matriz de la aplicación validDomains en el manifiesto de la aplicación.

La NotificationSignal API incluye los siguientes ejemplos:

Activity activity = MessageFactory.Text("This is a meeting signal test");
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);

Códigos de respuesta

La NotificationSignal API incluye los siguientes códigos de respuesta:

Código de respuesta Descripción
201 La actividad con señal se envía 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 diversos motivos, como que el administrador de inquilinos deshabilita y bloquea la aplicación durante la migración de sitios en directo. En este caso, la carga contiene un mensaje de error detallado.
404 El chat de reunión no existe.

API de detalles de reunión

Nota

Esta característica está disponible actualmente solo en la versión preliminar del desarrollador público.

La API de detalles de la reunión permite a la aplicación obtener metadatos estáticos de la reunión. Los metadatos proporcionan puntos de datos que no cambian dinámicamente. La API está disponible a través de Bot Services.

Requisito previo

Para usar la API de detalles de reunión, debe obtener permisos de RSC. Use el siguiente ejemplo para configurar la propiedad del manifiesto de la webApplicationInfo aplicación:

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

Parámetro de consulta

La API de detalles de reunión incluye el siguiente parámetro de consulta:

Valor Tipo Necesario Descripción
meetingId Cadena El identificador de reunión está disponible a través de Bot Invoke y Teams CLIENT SDK.

Ejemplo

La API de detalles de la reunión incluye los siguientes ejemplos:

MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));

El cuerpo de la respuesta JSON para la API de detalles de reunión es el siguiente:

{ 
   "details": { 
        "id": "meeting ID", 
        "msGraphResourceId": "", 
        "scheduledStartTime": "2020-08-21T02:30:00+00:00", 
        "scheduledEndTime": "2020-08-21T03:00:00+00:00", 
        "joinUrl": "https://teams.microsoft.com/l/xx", 
        "title": "All Hands", 
        "type": "Scheduled" 
    }, 
    "conversation": { 
            "isGroup": true, 
            “conversationType”: “groupchat”, 
            "id": "meeting chat ID" 
    }, 
    "organizer": { 
        "id": "<organizer user ID>", 
        "aadObjectId": "<AAD ID>", 
        "tenantId": "<Tenant ID>" 
    }
} 

Eventos de reuniones Teams en tiempo real

El usuario puede recibir eventos de reunión en tiempo real. Tan pronto como cualquier aplicación está asociada a una reunión, la hora real de inicio y finalización de la reunión se comparten con el bot.

La hora real de inicio y finalización de una reunión es diferente de la hora de inicio y finalización programadas. La API de detalles de la reunión proporciona la hora de inicio y finalización programadas. El evento proporciona la hora de inicio y finalización reales.

Requisito previo

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

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

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": "2021-04-29T16:10:41.1252256Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "userID", 
        "aadObjectId": "aadOnjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user Id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event", 
        "Id": "meeting id", 
        "JoinUrl": "url" 
        "StartTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

Ejemplo de carga del evento de fin de reunión

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

{ 
    "name": "application/vnd.microsoft.meetingEnd", 
    "type": "event", 
    "timestamp": "2021-04-29T16:17:17.4388966Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "user id", 
        "aadObjectId": "aadObjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting Id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event in Canary", 
        "Id": "19:meeting_NTM3ZDJjOTUtZGRhOS00MzYxLTk5NDAtMzY4M2IzZWFjZGE1@thread.v2", 
        "JoinUrl": "url", 
        "EndTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

Ejemplo de obtener metadatos de una reunión

El bot recibe el evento a través del OnEventActivityAsync controlador.

Para deserializar la carga json, se introduce un objeto de modelo para obtener los metadatos de una reunión. Los metadatos de una reunión se encuentra en la value propiedad de la carga del evento. Se MeetingStartEndEventvalue crea el objeto model, cuyas variables de miembro corresponden a las claves de la propiedad en la carga del value evento.

Nota

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

El código siguiente muestra cómo capturar los metadatos de una reunión que es , , , , y desde un evento de inicio y finalización de MeetingType Title la Id JoinUrl StartTime EndTime reunión:

Evento Inicio de reunión

protected override async Task OnTeamsMeetingStartAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Evento de fin de reunión

protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Ejemplo de código

Ejemplo de nombre Descripción C# Node.js
Extensibilidad de reuniones Microsoft Teams extensibilidad de reunión para pasar tokens. View View
Bot de burbuja de contenido de reunión Microsoft Teams de extensibilidad de reuniones para interactuar con el bot de burbujas de contenido en una reunión. View View
MeetingSidePanel Microsoft Teams extensibilidad de reuniones para interactuar con el panel lateral en la reunión. View View
Ficha Detalles en reunión Microsoft Teams extensibilidad de reuniones para interactuar con la pestaña Detalles en la reunión. View View
Ejemplo de eventos de reunión Aplicación de ejemplo para mostrar eventos de reunión Teams en tiempo real View View
Ejemplo de contratación de reuniones Aplicación de ejemplo para mostrar la experiencia de reunión para el escenario de contratación. View View
Instalación de aplicaciones con código QR Aplicación de ejemplo que genera el código QR e instala la aplicación con el código QR View Ver

Consulte también