Partilhar via

Ligação avançada a um fluxo de trabalho no Teams

  • Artigo

Pode criar uma ligação avançada para efetuar uma tarefa específica no Teams, como criar uma nova conversa, abrir uma caixa de diálogo de agendamento e navegar para chamada de áudio-vídeo.

Neste artigo, irá aprender a criar uma ligação avançada:

As aplicações podem iniciar uma nova conversa com uma lista de utilizadores e fornecer informações adicionais, como o nome do chat e a mensagem de rascunho, utilizando o seguinte formato:

https://teams.microsoft.com/l/chat/0/0?users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

Exemplo: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

Os parâmetros de consulta são:

  • users: A lista separada por vírgulas de IDs de usuário que representam os participantes do chat. O usuário que executa a ação é sempre incluído como um participante. O campo ID de utilizador suporta o Microsoft Entra UserPrincipalName, como apenas um endereço de e-mail.
  • topicName: um campo opcional para o nome a apresentar do chat se uma conversa tiver três ou mais utilizadores. Se este campo não for especificado, o nome de exibição do chat será baseado nos nomes dos participantes.
  • message: Um campo opcional para o texto da mensagem que você deseja inserir na caixa de redação do usuário atual enquanto o chat está em um estado de rascunho.

Para utilizar esta ligação avançada com o bot, especifique a ligação avançada como o destino do URL no botão do card ou toque em ação através do tipo de açãoopenUrl. As aplicações também podem utilizar a biblioteca de cliente JavaScript do Teams (TeamsJS) v.2.0 ou posterior para criar isto sem ter de preparar manualmente a ligação avançada. O exemplo seguinte utiliza o TeamsJS para marcar se a capacidade de chat for suportada:

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["joe@contoso.com","bob@contoso.com"], topic: "Prep For Meeting Tomorrow", message: "Hi folks kicking off chat about our meeting tomorrow"});
    chatPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Observação

Se uma conversa já existir, será aberta uma ligação avançada nesse chat.

Pode criar uma ligação avançada nas suas aplicações do Teams para abrir uma caixa de diálogo de agendamento de reuniões e fornecer informações, tais como o título da reunião e os participantes através dos seguintes métodos:

Embora recomendemos a utilização de APIs digitadas do TeamsJS, é possível criar manualmente ligações avançadas para a caixa de diálogo de agendamento incorporado do Teams.

Utilize o seguinte formato para configurar uma ligação avançada que pode utilizar num bot, conector ou extensão de mensagem card:

https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

Observação

Os parâmetros de pesquisa não dão suporte ao sinal + no lugar do espaço em branco (``). Certifique-se de que o código de codificação do URI devolve %20 espaços. Por exemplo, ?subject=test%20subject é bom, mas ?subject=test+subject é mau.

Os parâmetros de consulta são:

  • attendees: uma lista opcional separada por vírgulas de IDs de utilizador que representam os participantes da reunião. O usuário que executa a ação é o organizador da reunião. O campo ID de utilizador suporta apenas o Microsoft Entra UserPrincipalName, normalmente um endereço de e-mail.
  • startTime: o parâmetro opcional para a hora de início do evento. A hora de início deve estar no formato ISO 8601 longo, por exemplo 2018-03-12T23:55:25+02:00.
  • endTime: um parâmetro opcional para a hora de fim do evento, também no formato ISO 8601.
  • subject: um parâmetro opcional para o assunto da reunião.
  • content: um parâmetro opcional para o campo de detalhes da reunião.

Observação

Não pode especificar a localização, uma vez que não é suportada. Tem de especificar o desvio utc, que inclui fusos horários, ao gerar as horas de início e de fim.

Para utilizar esta ligação avançada com o bot, pode especificar a ligação avançada como o destino do URL no botão do card ou como uma ação de toque através do tipo de açãoopenUrl.

Exemplo: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=​​​​​​​test%3Acontent​​​​​​​​​​​​​​

Também pode utilizar o TeamsJS v.2.0 ou posterior na sua aplicação Teams para abrir a caixa de diálogo de agendamento da reunião sem ter de preparar manualmente a ligação. Para abrir a caixa de diálogo de agendamento no Teams, tem de continuar a utilizar o método original baseado no URL de ligação profunda, uma vez que o Teams ainda não suporta a capacidade de calendário:

// Open a scheduling dialog from your tab
if(calendar.isSupported()) {
   const calendarPromise = calendar.composeMeeting({
      attendees: ["joe@contoso.com", "bob@contoso.com"],
      content: "test content",
      endTime: "2018-10-24T10:30:00-07:00",
      startTime: "2018-10-24T10:00:00-07:00",
      subject: "test subject"});
   calendarPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Para obter mais informações sobre como trabalhar com o calendário, consulte o namespace calendário na documentação de referência da API.

Pode configurar as suas aplicações do Teams para preparar uma ligação avançada para os utilizadores iniciarem uma chamada um-para-um, uma chamada de grupo ou uma chamada de vídeo. Pode invocar apenas chamadas de áudio ou de áudio-vídeo para um único utilizador ou um grupo de utilizadores ao especificar o tipo de chamada e os participantes. Antes de o Teams efetuar a chamada, o cliente pede uma confirmação. Se existir uma chamada de grupo, pode chamar um conjunto de utilizadores VoIP e RTPC na mesma invocação de ligação avançada.

Numa chamada de vídeo, o cliente do Teams pede confirmação antes de ativar o vídeo do autor da chamada para a chamada. O receptor da chamada tem a opção de responder somente por áudio ou áudio e vídeo, por meio da janela de notificação de chamada do Teams.

Observação

Este método não pode ser utilizado para invocar uma reunião.

Pode configurar ligações avançadas de uma das seguintes duas formas:

Embora recomendemos a utilização das APIs digitadas do TeamsJS v.2.0 ou posterior, também pode utilizar uma ligação avançada configurada manualmente para iniciar uma chamada. Veja os seguintes formatos:

Link profundo Formatar Exemplo
Fazer uma chamada de áudio https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com
Fazer uma chamada de áudio e vídeo https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true
Fazer uma chamada de áudio e vídeo com uma fonte de parâmetro opcional https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true&source=demoApp https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true&source=demoApp
Fazer uma chamada de áudio e vídeo para uma combinação de usuários VoIP e PSTN https://teams.microsoft.com/l/call/0/0?users=<user1>,4:<phonenumber> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com,4:9876543210

Estes são os parâmetros de consulta:

  • users: uma lista separada por vírgulas de IDs de utilizador que representam os participantes da chamada. O campo ID de utilizador suporta o Microsoft Entra UserPrincipalName, normalmente um endereço de e-mail ou, numa chamada RTPC, suporta uma RM RTPC 4:<phonenumber>.
  • withVideo: um parâmetro opcional, que pode utilizar para efetuar uma chamada de vídeo. Definir este parâmetro apenas ativa a câmara do autor da chamada. O recetor da chamada tem a opção de atender através de uma chamada de áudio ou de áudio e vídeo através da janela de notificação de chamada do Teams.

As aplicações também podem utilizar o TeamsJS v.2.0 ou posterior para iniciar chamadas sem ter de preparar manualmente estas ligações avançadas. O código seguinte demonstra a utilização do TeamsJS para iniciar uma chamada:

if(call.isSupported()) {
    const callPromise = call.startCall({ targets: ["joe@contoso.com","bob@contoso.com","4:9876543210"], requestedModalities: [call.CallModalities.Audio], source: "demoApp"});
    callPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Ligação avançada para partilhar conteúdo para realizar reuniões

Para adicionar uma ligação avançada para partilhar conteúdo no palco, tem de ter um contexto de aplicação. O contexto da aplicação permite que o cliente do Teams obtenha o manifesto da aplicação e marcar se a partilha no palco for possível. Segue-se um exemplo de um contexto de aplicação:

{ "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view", "appId": "9ec80a73-1d41-4bcb-8190-4b9eA9e29fbb" , "useMeetNow": false }

Os parâmetros de consulta para o contexto da aplicação são:

  • appID: este é o ID que pode ser obtido a partir do manifesto da aplicação.
  • appSharingUrl: o URL, que tem de ser partilhado no palco, deve ser um domínio válido definido no manifesto da aplicação. Se o URL não for um domínio válido, é apresentada uma caixa de diálogo de erro para fornecer ao utilizador uma descrição do erro.
  • useMeetNow: isto inclui um parâmetro Booleano que pode ser verdadeiro ou falso.

    • Verdadeiro: quando o useMeetNow valor for verdadeiro e se não houver uma reunião em curso, será iniciada uma nova reunião Reunir agora. Quando houver uma reunião em curso, este valor será ignorado.

    • Falso: o valor predefinido de useMeetNow é falso, o que significa que, quando uma ligação avançada é partilhada no palco e não há uma reunião em curso, será apresentado um pop-up de calendário. No entanto, pode partilhar diretamente durante uma reunião.

Certifique-se de que todos os parâmetros de consulta estão devidamente codificados com URI e que o contexto da aplicação tem de ser codificado duas vezes no URL final. Segue-se um exemplo:

const appContext= JSON.stringify({ 
  "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view",
  "appId": "9cc80a93-1d41-4bcb-8170-4b9ec9e29fbb",
  "useMeetNow": false
});
const encodedContext = encodeURIComponent(appContext).replace(/'/g,"%27").replace(/"/g,"%22");
const encodedAppContext = encodeURIComponent(encodedContext).replace(/'/g,"%27").replace(/"/g,"%22");

Uma ligação avançada pode ser iniciada a partir da Web do Teams ou do cliente de ambiente de trabalho ou móvel do Teams.

Utilize o seguinte formato para iniciar uma ligação avançada a partir da Web do Teams para partilhar conteúdos em palco:

msteams:/l/meeting-share?deeplinkId={GUID}&fqdn={string}&lm=deeplink&appContext={json encoded app context}

Exemplo: https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D

Link profundo Formatar Exemplo
Para partilhar a aplicação e abrir o calendário do Teams, quando useMeeetNow for falso, predefinição. https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context} https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D
Para partilhar a aplicação e iniciar uma reunião instantânea, quando useMeeetNow é verdade. https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context} https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D

Os parâmetros de consulta são:

  • deepLinkId: Qualquer identificador utilizado para a correlação de telemetria.
  • fqdn: fqdn é um parâmetro opcional, que pode ser utilizado para mudar para um ambiente adequado de uma reunião para partilhar uma aplicação no palco. Suporta cenários em que uma partilha de aplicações específica ocorre num ambiente específico. O valor predefinido de fqdn é o URL da empresa e os valores possíveis são Teams.live.com para o Teams for Life, teams.microsoft.comou teams.microsoft.us.

Observação

Para que a sua aplicação passe na validação, quando criar uma ligação avançada a partir do seu site, aplicação Web ou Cartão Ajustável, utilize Partilhar na reunião como cadeia ou cópia.

Pode gerar uma ligação avançada para partilhar a aplicação no palco e para iniciar ou participar numa reunião.

Pode gerar uma ligação avançada para o painel do lado da reunião numa reunião. Utilize o seguinte formato para uma ligação avançada para o painel do lado da reunião:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>.

Exemplo:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

Por predefinição, é aberta uma ligação avançada num painel do lado da reunião. Para abrir uma ligação avançada diretamente numa aplicação em vez do painel do lado da reunião, adicione openInMeeting=false o formato de ligação avançada:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

Para obter mais informações, veja ligação avançada a um separador.

A ligação avançada não é aberta no painel do lado da reunião nos seguintes cenários:

  • Não há nenhuma reunião ativa.
  • A aplicação não tem sidePanel o contexto declarado no manifesto da aplicação.
  • openInMeeting está definido como false na ligação avançada.
  • A ligação avançada está selecionada fora da janela ou componente da reunião.
  • A ligação avançada não corresponde à reunião atual, como uma ligação avançada criada noutra reunião.

A aplicação Teams pode ler o URL para participar num URL de reunião através de Graph APIs. Esta ligação avançada apresenta a IU para o utilizador participar na reunião. Para obter mais informações, consulte Obter onlineMeeting e Obter detalhes da reunião.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Ligação avançada que consome o ID de Subentidade Este exemplo mostra como utilizar uma ligação avançada de um chat de bot para um separador que consome o ID de Subentidade. Também mostra ligações avançadas para:
- Navegar para uma aplicação
- Navegar para uma conversa
- Abrir uma caixa de diálogo de perfil
- Abrir uma caixa de diálogo de agendamento		 View Exibir