Compartilhar via

APIs de aplicações de reunião

  • Artigo

A extensibilidade da reunião fornece APIs para melhorar a experiência de reunião. Você pode executar o seguinte com a ajuda das APIs listadas:

  • Crie aplicativos ou integre aplicativos existentes no ciclo de vida da reunião.
  • Use APIs para tornar seu aplicativo ciente da reunião.
  • Selecione as APIs necessárias para melhorar a experiência de reunião.

Observação

Utilize a biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS) (Versão: 1.10 e posterior) para que o início de sessão único (SSO) funcione no painel do lado da reunião.

A tabela seguinte fornece uma lista de APIs disponíveis na biblioteca JavaScript do Microsoft Teams e nos SDKs do Microsoft Bot Framework:

Método Descrição Source
Get contexto do usuário Obtenha informações contextuais para apresentar conteúdos relevantes num separador do Microsoft Teams. Biblioteca do TeamsJS
Obter participante Buscar informações do participante por ID de reunião e ID do participante. SDK do Microsoft Bot Framework
Enviar notificação na reunião Fornece sinais de reunião através da API de notificação de conversação existente para o chat user-bot e permite que o bot notifique a ação do utilizador que mostra uma notificação em reunião. SDK do Microsoft Bot Framework
Get meeting details Obter metadados estáticos de uma reunião. SDK do Microsoft Bot Framework
Enviar legendas em tempo real Envie legendas em tempo real para uma reunião em andamento. Biblioteca do TeamsJS
Compartilhar Conteúdo do Aplicativo na Janela de Conteúdo Compartilhado Compartilhe partes específicas do aplicativo para o estágio de reunião no painel lateral do aplicativo em uma reunião. Biblioteca do TeamsJS
Receber eventos de reunião do Teams em tempo real Receba eventos de reunião em tempo real, como o início e o fim da reunião ou a participação e saída do participante. SDK do Microsoft Bot Framework
Obter estado de áudio recebido Permite que uma aplicação obtenha a definição de estado de áudio recebido para o utilizador da reunião. Biblioteca do TeamsJS
Ativar/desativar áudio recebido Permite que uma aplicação alterne a definição de estado de áudio recebido para o utilizador da reunião de desativar o som para ativar o som ou vice-versa. Biblioteca do TeamsJS

Obter API de contexto do usuário

Importante

  • Por predefinição, o novo cliente do Teams suporta um tema claro para aplicações em reuniões do Teams. Quando a app.theme propriedade na API getContext devolve o valor, o default cliente do Teams está no tema claro.
  • A versão anterior dos clientes do Teams só suporta o tema Escuro e Contraste para aplicações em reuniões do Teams

Para identificar e recuperar informações contextuais para o conteúdo da guia, consulte obter contexto para a guia Teams. meetingId é usado por uma guia em execução no contexto da reunião e é adicionado à carga útil de resposta.

Exemplos

Seguem-se as respostas do TeamsJS v2 para Obter API de contexto de utilizador com base no tipo de reunião, tipo de utilizador e tipo de chamada:

  • Tipo de reunião

    Segue-se uma resposta de payload JSON para uma reunião de canal para utilizadores no 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": "user@microsoft.com",
        "userPrincipalName": "user@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 usuário

    Segue-se uma resposta de payload JSON numa reunião privada agendada para um utilizador convidado:

      {
        "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": "user@microsoft.com",
         "userPrincipalName": "user@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/user_microsoft_com",
         "mySiteDomain": "microsoft-my.sharepoint.com"
        }
  }

  • Tipo de chamada

    Segue-se uma resposta de payload JSON para uma chamada individual para um utilizador no 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": "user@microsoft.com",
        "userPrincipalName": "user@microsoft.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": "microsoft.sharepoint.com",
        "teamSitePath": undefined,
        "teamSiteId": undefined,
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

Obter API de participante

A API GetParticipant deve ter um registro de bot e uma ID para gerar tokens de autenticação. Para obter mais informações, consulte registro e ID do bot.

Observação

  • O tipo de utilizador não está incluído na API getParticipantRole .
  • Não armazene em cache as funções de participante, pois o organizador da reunião pode alterar as funções a qualquer momento.
  • A GetParticipant API só é suportada para listas de distribuição ou listas com menos de 350 participantes.

Parâmetros de consulta

Dica

Obtenha IDs de participantes e IDs de locatários na guia Autenticação SSO.

A API Meeting deve ter meetingId, participantId e tenantId como parâmetros de URL. Os parâmetros estão disponíveis como parte da biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS) e da atividade do bot.

A tabela a seguir inclui os parâmetros de consulta:

Valor Tipo Obrigatório Descrição
meetingId Cadeia de caracteres Sim O identificador da reunião está disponível através da biblioteca Bot Invoke e TeamsJS.
participantId Cadeia de caracteres Sim A ID do participante é a ID de usuário. Está disponível na biblioteca SSO de Separadores, Bot Invoke e TeamsJS. É recomendável obter uma ID de participante do SSO da guia.
tenantId Cadeia de caracteres Sim A ID do locatário é necessária para os usuários do locatário. Está disponível na biblioteca SSO de Separadores, Bot Invoke e TeamsJS. É recomendável obter uma ID de locatário do SSO da guia.

Exemplo

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);
}
Nome da propriedade Descrição
user.id ID do utilizador.
user.aadObjectId ID de objeto do Microsoft Entra do utilizador.
user.name Nome do utilizador.
user.givenName Nome Próprio do utilizador.
user.surname Apelido do utilizador.
user.email ID de Correio do utilizador.
user.userPrincipalName UPN do utilizador.
user.tenantId ID do inquilino do Microsoft Entra.
user.userRole Função do utilizador. Por exemplo, "administrador" ou "utilizador".
meeting.role O papel do participante na reunião. Por exemplo, "Organizador", "Apresentador" ou "Participante".
meeting.inMeeting O valor que indica se o participante está na reunião.
conversation.id O ID do chat da reunião.
conversation.isGroup Valor booleano que indica se a conversação tem mais de dois participantes.

Códigos de resposta

A tabela a seguir fornece os códigos de resposta:

Código da resposta Descrição
403 Obter informações do participante não é compartilhado com o aplicativo. Se o aplicativo não estiver instalado na reunião, ele disparará a resposta de erro 403. Se o administrador do locatário desabilitar ou bloquear o aplicativo durante a migração ao vivo do site, ele disparará a resposta de erro 403.
200 As informações do participante são recuperadas com êxito.
401 O aplicativo responde com um token inválido.
404 A reunião expirou ou os participantes não estão disponíveis.

Enviar uma notificação na reunião

Todos os usuários em uma reunião recebem as notificações enviadas por meio da carga de notificação na reunião. A carga de notificação na reunião dispara uma notificação na reunião e permite que você forneça sinais de reunião que são entregues usando a API de notificação de conversa existente para chat de bot do usuário. Você pode enviar uma notificação na reunião com base na ação do usuário. A carga está disponível por meio dos Serviços de Bot.

Também pode enviar uma notificação em reunião direcionada a um participante específico numa reunião. Para obter mais informações, veja Notificação direcionada na reunião.

Observação

  • Quando uma notificação na reunião é invocada, o conteúdo é apresentado como uma mensagem de chat.
  • Você deve invocar a função submitTask() para ignorar automaticamente depois que um usuário executar uma ação no modo de exibição da Web. Esse é um requisito para o envio do aplicativo. Para obter mais informações, consulte Módulo de tarefas do SDK do Teams.
  • Se você quiser que seu aplicativo seja compatível com usuários anônimos, o conteúdo da solicitação de invocação inicial deverá depender do objeto from.id para solicitar metadados em from e não nos metadados de solicitação from.aadObjectId. from.id é o ID de utilizador e from.aadObjectId é o ID do Microsoft Entra do utilizador. Para obter mais informações, consulte usando módulos de tarefa em guias e criar e enviar o módulo de tarefa.

Parâmetro de consulta

A tabela seguinte inclui o parâmetro de consulta:

Valor Tipo Obrigatório Descrição
conversationId String Sim O identificador de conversa está disponível como parte do Bot Invoke.

Exemplos

Bot ID é declarado no manifesto e o bot recebe um objeto de resultado.

Observação

  • O parâmetro completionBotId do externalResourceUrl é opcional no exemplo de carga solicitado.
  • Os externalResourceUrl largura e altura devem estar em pixels. Para obter mais informações, consulte diretrizes de design.
  • A URL é a página, que é carregada como <iframe> na notificação na reunião. O domínio deve estar na matriz validDomains no manifesto do aplicativo.
// 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);
Nome da propriedade Descrição
type Tipo de atividade.
text O conteúdo de texto da mensagem.
resumo O texto de resumo da mensagem.
channelData.notification.alertInMeeting Valor booleano que indica se uma notificação deve ser apresentada ao utilizador durante uma reunião.
channelData.notification.externalResourceUrl O valor do URL de recurso externo da notificação.
replyToId O ID da mensagem principal ou raiz do thread.
APP_ID ID da aplicação declarado no manifesto.
completionBotId ID da aplicação de bot.

Códigos de resposta

A tabela a seguir inclui os códigos de resposta:

Código da resposta Descrição
201 A atividade com sinal foi enviada com êxito.
401 O aplicativo responde com um token inválido.
403 O aplicativo não pode enviar o sinal. O código de resposta 403 pode ocorrer devido a vários motivos, como o administrador de locatários desabilita e bloqueia o aplicativo durante a migração ao vivo do site. Nesse caso, a carga contém uma mensagem de erro detalhada.
404 O chat da reunião não existe.

Notificação de reunião direcionada e ícone de aplicação a desativar API

A targetedMeetingNotification API permite que as aplicações enviem notificações direcionadas em reuniões e mostra o ícone da aplicação a fazer mal aos participantes específicos numa reunião. As aplicações enviam notificações direcionadas na reunião e o ícone da aplicação está a fazer a má gestão com base na ação do utilizador. A API está disponível através da API do bot.

Pré-requisito

Tem de configurar o manifesto da aplicação com permissões RSC na webApplicationInfo propriedade para enviar notificações direcionadas na reunião e mostra o ícone da aplicação a fazer a má gestão a participantes específicos numa reunião. Use os exemplos a seguir para configurar o manifesto:


Para a versão 1.12 e posterior do manifesto da aplicação 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}


Para a versão 1.11 e anterior do manifesto da aplicação 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

Observação

  • O payload da API só permite uma caixa de diálogo com um URL.
  • Os formatos de ID de utilizador aadObjectid e UPN não são suportados.

Obtenha o formato de ID de utilizador suportado para a notificação direcionada na reunião e o ícone da aplicação:

Exemplo

Segue-se um exemplo de payload de pedidos para notificações direcionadas na reunião e o ícone de aplicação em mau estado de funcionamento:

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"      } 
    ] 
  }
}
Nome da propriedade Descrição
meetingId O ID da reunião está disponível através da invocação do bot e da biblioteca do TeamsJS.
type targetedMeetingNotification
recipients Lista de IDs de utilizador. Obtenha IDs de utilizador para os participantes da reunião através da API Obter participante. Obtenha a lista completa da lista de conversas com a API Obter membros. Uma lista de destinatários vazios ou nulos devolve 400.
surface Um tipo de superfície. Os tipos de superfície suportados são meetingStage e meetingTabIcon.
surfaces Lista de superfícies onde as notificações podem ser compostas.
contentType Tipo de conteúdo que a notificação na reunião de destino compõe. O valor suportado é task.
content TaskModuleContinueResponse
content.value.height Opcional; altura pedida da notificação.
content.value.width Opcional; pedida largura da notificação.
content.value.title Opcional; título da notificação.
content.value.url Opcional; URL a ser composto na notificação. Certifique-se de que o URL faz parte do manifesto da validDomains aplicação. Se for fornecida uma cadeia vazia ou nenhum URL, nada será composto numa notificação de reunião.
ChannelData.OnBehalfOf Opcional; isto destina-se a suportar atributos de Utilizador.
onBehalfOf.itemid Descreve a identificação do item. O respetivo valor tem de ser 0.
onBehalfOf.mentionType person palavra-chave. Descreve a menção de uma pessoa.
onBehalfOf.mri A ressonância magnética do utilizador é apresentada como remetente.
onBehalfOf.displayName Opcional; nome do person. Utilizado como contingência caso a resolução de nomes esteja indisponível.

Observação

Se fornecer uma entrada inválida, a API devolve o código de estado 400.

Código da resposta

A tabela a seguir inclui os códigos de resposta:

Código da resposta Descrição
202 A notificação é enviada com êxito.
207 As notificações são enviadas apenas para alguns participantes.
400 Falha na validação do payload do pedido de notificação de reunião.
401 O token do bot é inválido.
403 O bot não tem permissão para enviar a notificação.
404 A conversa da reunião não foi encontrada ou nenhum dos participantes foi encontrado na lista.

Obter API de detalhes da reunião

A API de detalhes da reunião permite que a sua aplicação obtenha os metadados estáticos de uma reunião. Os metadados fornecem pontos de dados que não são alterados dinamicamente. A API está disponível por meio dos Serviços de Bot. As reuniões agendadas ou periódicas privadas e as reuniões agendadas ou periódicas de canal suportam a API com diferentes permissões de RSC, respetivamente.

A API de detalhes da reunião tem de ter um registo de bot e um ID de bot. Ele requer que o SDK do Bot obtenha TurnContext. Para utilizar a API de detalhes da reunião, tem de obter permissões RSC diferentes com base no âmbito de qualquer reunião, como reunião privada ou reunião de canal.

Observação

A API de detalhes da reunião é suportada para reuniões privadas agendadas, reunião de canal agendada, reuniões instantâneas (Reunir agora), chamadas um-para-um e chamadas de grupo em clientes móveis e de ambiente de trabalho do Teams.

Pré-requisito

Para utilizar a API de detalhes da reunião, tem de obter permissões RSC diferentes com base no âmbito de qualquer reunião, como reunião privada ou reunião de canal.


Para a versão 1.12 e posterior do manifesto da aplicação

Utilize o exemplo seguinte para configurar as propriedades e authorization o manifesto da webApplicationInfo aplicação para qualquer reunião privada:

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

Use o exemplo a seguir para configurar as propriedades webApplicationInfo e authorization para qualquer reunião de canal:

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


Para a versão 1.11 e anterior do manifesto da aplicação

Use o exemplo a seguir para configurar a propriedade webApplicationInfo do manifesto do aplicativo para qualquer reunião privada:

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

Use o exemplo a seguir para configurar a propriedade webApplicationInfo do manifesto do aplicativo para qualquer reunião de canal:

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

Observação

  • Se a ChannelMeeting.ReadBasic.Group permissão for adicionada ao manifesto, o bot recebe automaticamente os eventos de início ou de fim da reunião a partir das reuniões de canal criadas em todas as equipas onde o bot é adicionado.
  • Para uma chamada organizer um-para-um é o iniciador do chat e para chamadas organizer de grupo é o iniciador de chamadas. Para reuniões organizer de canal público é a pessoa que criou a publicação do canal.

Parâmetro de consulta

A tabela a seguir lista o parâmetro de consulta:

Valor Tipo Obrigatório Descrição
meetingId Cadeia de caracteres Sim O identificador da reunião está disponível através do Bot Invoke e da biblioteca do TeamsJS.

Exemplo

// 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));
Nome da propriedade Descrição
details.id O ID da reunião, codificado como uma cadeia BASE64.
details.msGraphResourceId O MsGraphResourceId, utilizado especificamente para chamadas à MS Graph API.
details.scheduledStartTime A hora de início agendada da reunião, em UTC.
details.scheduledEndTime A hora de fim agendada da reunião, em UTC.
details.joinUrl O URL utilizado para participar na reunião.
details.title O título da reunião.
details.type O tipo da reunião (OneToOneCall, GroupCall, Agendado, Recorrente, MeetNow, ChannelScheduled e ChannelRecurring).
conversation.isGroup Valor booleano que indica se a conversação tem mais de dois participantes.
conversation.conversationType O tipo de conversação.
conversation.id O ID do chat da reunião.
organizer.id O ID de utilizador do Organizador.
organizer.aadObjectId O ID de objeto do Microsoft Entra do Organizador.
organizer.tenantId O ID de inquilino do Microsoft Entra do Organizador.

Em caso de tipo de reunião periódica:

startDate: especifica a data para começar a aplicar o padrão. O valor de startDate tem de corresponder ao valor de data da propriedade start no recurso do evento. A primeira ocorrência da reunião poderá não ocorrer nesta data se não se ajustar ao padrão.

endDate: especifica a data para parar de aplicar o padrão. A última ocorrência da reunião poderá não ocorrer nesta data se não se ajustar ao padrão.

API de envio de legendas em tempo real

A API enviar legendas em tempo real expõe um ponto final POST para legendas de tradução em tempo real (CART) de acesso de comunicação do Teams, legendas de áudio escritas por humanos. Os conteúdos de texto enviados para este ponto final são apresentados aos utilizadores finais numa reunião do Teams quando têm legendas ativadas.

URL DO CART

Pode obter o URL do CART para o ponto final POST a partir da página Opções da reunião numa reunião do Teams. Para obter mais informações, consulte legendas CART em uma reunião do Microsoft Teams. Você não precisa modificar a URL do CART para usar legendas CART.

Parâmetro de Consulta

A URL do CART inclui os seguintes parâmetros de consulta:

Valor Tipo Obrigatório Descrição
meetingId Cadeia de caracteres Sim O identificador da reunião está disponível através do Bot Invoke e da biblioteca do TeamsJS.
Por exemplo, 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 Cadeia de caracteres Sim Token de autorização.
Por exemplo, token=04751eac

Exemplo

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 Descrição
/cartcaption POSTAR Manipular legendas para a reunião, que foi iniciada

Observação

Verifique se o tipo de conteúdo para todas as solicitações é texto sem formatação com codificação UTF-8. O corpo da solicitação contém apenas legendas.

Exemplo

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.

Observação

Cada solicitação POST gera uma nova linha de legendas. Para garantir que o usuário final tenha tempo suficiente para ler o conteúdo, limite cada corpo da solicitação POST a 80 a 120 caracteres.

Códigos de erro

A tabela a seguir fornece os códigos de erro:

Código de erro Descrição
400 Solicitação incorreta. O corpo da resposta tem mais informações. Por exemplo, não de todos os parâmetros necessários apresentados.
401 Não autorizado. Token inválido ou expirado. Se você receber esse erro, gere uma nova URL do CART no Teams.
404 Reunião não encontrada ou não iniciada. Se você receber esse erro, certifique-se de iniciar a reunião e selecione iniciar legendas. Depois que as legendas forem habilitadas na reunião, você poderá começar a POSTing de legendas na reunião.
500 Erro de servidor interno. Para obter mais informações, contate o suporte ou forneça comentários.

Receber eventos de reunião do Teams em tempo real

Pode receber eventos de reunião em tempo real, como o início e o fim da reunião ou a participação do participante e sair dos eventos.

Receber eventos de início e de fim da reunião

Observação

Os eventos de início e de fim da reunião são suportados para reuniões agendadas e de canal.

O usuário pode receber eventos de reunião em tempo real. Assim que qualquer aplicativo é associado a uma reunião, a hora real de início e término da reunião é compartilhada com o bot. A hora real de início e término de uma reunião é diferente da hora de início e término agendada. A API de detalhes da reunião fornece a hora de início e de fim agendada. O evento fornece a hora real de início e término.

Se as ChannelMeeting.ReadBasic.Group permissões e OnlineMeeting.ReadBasic.Chat forem adicionadas no manifesto, o bot começa automaticamente a receber os eventos de início ou de fim da reunião para os tipos de reuniões agendadas e de canal.

Pré-requisito

O manifesto do aplicativo deve ter a propriedade webApplicationInfo para receber os eventos de início e término da reunião. Use os exemplos a seguir para configurar o manifesto:


Para a versão 1.12 e posterior do manifesto da aplicação 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]    
    }
}


Para a versão 1.11 e anterior do manifesto da aplicação 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat",
      "ChannelMeeting.ReadBasic.Group"
    ]
}

Exemplo de como obter eventos de início ou de fim da reunião

O bot recebe os eventos de início e de fim da reunião através dos OnTeamsMeetingStartAsync processadores e OnTeamsMeetingEndAsync . As informações relacionadas com o evento de reunião fazem parte do MeetingStartEventDetails objeto, que inclui os campos de metadados, tais como , meetingTypetitle, , id, joinUrl, e startTimeEndTime.

Observação

  • Obtenha a ID da reunião turnContext.ChannelData.
  • Não use a ID da conversa como ID da reunião.
  • Não use a ID de reunião do conteúdo de eventos de reunião turncontext.activity.value.

Os exemplos seguintes mostram como capturar os eventos de início e de fim da reunião:

Evento de Início da Reunião

// 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 Término da Reunião

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

Exemplo de conteúdo do evento de início da reunião

O código a seguir fornece um exemplo de conteúdo do evento de início da reunião:

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

Exemplo de conteúdo do evento final da reunião

O código a seguir fornece um exemplo de conteúdo de evento final de reunião:

{
  "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"
    }
  }
}
Nome da propriedade Descrição
name Nome do utilizador.
type Tipo de atividade.
timestamp Data e hora locais da mensagem, expressas no formato ISO-8601.
id ID da atividade.
channelId Canal a que esta atividade está associada.
serviceUrl URL do serviço para onde as respostas a esta atividade devem ser enviadas.
from.id ID do usuário que enviou a solicitação.
from.aadObjectId ID de objeto do Microsoft Entra do utilizador que enviou o pedido.
conversation.isGroup Valor booleano que indica se a conversação tem mais de dois participantes.
conversation.tenantId ID do inquilino do Microsoft Entra da conversação ou reunião.
conversation.id O ID do chat da reunião.
recipient.id ID do utilizador que recebe o pedido.
recipient.name Nome do utilizador que recebe o pedido.
entities.locale entidade que contém metadados sobre a região.
entities.country entidade que contém metadados sobre o país/região.
entities.type entidade que contém metadados sobre o cliente.
channelData.tenant.id ID do inquilino do Microsoft Entra.
channelData.source O nome de origem de onde o evento é acionado ou invocado.
channelData.meeting.id O ID predefinido associado à reunião.
valor. Tipo de Reunião O tipo de reunião.
valor. Título O assunto da reunião.
valor. ID O ID predefinido associado à reunião.
valor. JoinUrl O URL de participação da reunião.
valor. StartTime A hora de início da reunião em UTC.
valor. EndTime A hora de fim da reunião em UTC.
locale A região da mensagem definida pelo cliente.

Receber eventos de participantes da reunião

O bot pode receber eventos de reunião em tempo real, como participar e sair de eventos. Um bot só pode receber os eventos dos participantes se tiver subscrito estes eventos no Portal do Programador.

Observação

  • Os eventos dos participantes são suportados apenas para reuniões agendadas.
  • Para que um bot receba eventos de participantes, certifique-se de que adiciona o bot à reunião antes de um participante participar ou sair da reunião.

Para subscrever eventos de participantes, siga estes passos:

  1. No Portal do Programador , abra a aplicação bot ou importe uma aplicação existente.

  2. Na secção Subscrições de eventos de reunião , selecione os eventos:

    • Participação do participante
    • Saída do participante

  3. Selecione Salvar

    Captura de ecrã a mostrar como o portal do programador apresenta os eventos dos participantes.

  4. Certifique-se de que a OnlineMeetingParticipant.Read.Chat permissão RSC está configurada no manifesto da aplicação.

    Se a sua aplicação não tiver a permissão RSC, adicione-a através da secção Configurar>Permissões da sua aplicação no Portal do Programador. Para obter mais informações, veja Permissões RSC.

Os exemplos seguintes mostram como capturar os eventos de participação e saída do participante:

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

Seguem-se os exemplos de payloads de participação e saída de eventos:

Segue-se um exemplo do payload do evento de adesão do participante:

{ 

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

Obter estado de áudio recebido

A getIncomingClientAudioState API permite que uma aplicação obtenha a definição de estado de áudio recebido para o utilizador da reunião. A API está disponível através da biblioteca do TeamsJS.

Observação

  • A getIncomingClientAudioState API para dispositivos móveis está disponível na Pré-visualização do Programador Público.
  • A toggleIncomingClientAudio API está disponível no novo cliente do Teams.
  • O consentimento específico do recurso está disponível para a versão de manifesto 1.12 e versões posteriores, pelo que esta API não funciona para a versão de manifesto 1.11 e versões anteriores.

Manifesto

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

Exemplo

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

A tabela seguinte inclui o parâmetro de consulta:

Valor Tipo Obrigatório Descrição
callback Cadeia de caracteres Sim A chamada de retorno contém dois parâmetros error e result. O erro pode conter um tipo SdkError de erro ou null quando a obtenção de áudio é efetuada com êxito. O resultado pode conter um valor verdadeiro ou falso quando a obtenção de áudio é bem-sucedida ou nula quando a obtenção de áudio falha. O áudio recebido será desativado se o resultado for verdadeiro e não estiver ativado se o resultado for falso.

Códigos de resposta

A tabela a seguir fornece os códigos de resposta:

Código da resposta Descrição
500 Erro interno.
501 A API não é suportada no contexto atual.
1.000 A aplicação não tem as permissões adequadas para permitir a partilha em fase.

Ativar/desativar áudio recebido

A toggleIncomingClientAudio API permite que uma aplicação alterne a definição de estado de áudio recebido para o utilizador da reunião de desativar o som para ativar o som ou vice-versa. A API está disponível através da biblioteca do TeamsJS.

Observação

  • A toggleIncomingClientAudio API para dispositivos móveis está disponível na Pré-visualização do Programador Público.
  • O consentimento específico do recurso está disponível para a versão de manifesto 1.12 e versões posteriores, pelo que esta API não funciona para a versão de manifesto 1.11 e versões anteriores.

Manifesto

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

Exemplo

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

A tabela seguinte inclui o parâmetro de consulta:

Valor Tipo Obrigatório Descrição
callback Cadeia de caracteres Sim A chamada de retorno contém dois parâmetros error e result. O erro pode conter um tipo SdkError de erro ou null quando o botão de alternar é efetuado com êxito. O resultado pode conter um valor verdadeiro ou falso, quando o botão de alternar for bem-sucedido ou nulo quando o botão de alternar falhar. O áudio recebido será desativado se o resultado for verdadeiro e não estiver ativado se o resultado for falso.

Código da resposta

A tabela a seguir fornece os códigos de resposta:

Código da resposta Descrição
500 Erro interno.
501 A API não é suportada no contexto atual.
1.000 A aplicação não tem as permissões adequadas para permitir a partilha em fase.

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto
Extensibilidade de reuniões Exemplo de extensibilidade de reuniões do Teams para transmitir tokens. View View View
Notificação na reunião Demonstra como implementar a notificação em reunião com o bot. View View View
Painel lateral da reunião Exemplo de extensibilidade de reuniões do Teams para interagir com o painel lateral na reunião. View Exibir
Guia Detalhes na Reunião Esta aplicação de exemplo mostra a funcionalidade de extensibilidade de reuniões do Teams, onde o utilizador pode criar um inquérito e os membros podem responder ao inquérito em reunião. View View Exibir
Exemplo de eventos de reunião Este exemplo mostra eventos de reunião do Teams em tempo real com o bot. View View View
Exemplo de convite de reunião Esta aplicação de exemplo mostra uma experiência de reunião para cenários de recrutamento através de Aplicações em Reuniões. View View Exibir

Confira também