Link profundo para um fluxo de trabalho no Teams

Você pode criar um link profundo para executar uma tarefa específica no Teams, como criar um novo chat, abrir uma caixa de diálogo de agendamento e navegar até uma chamada de áudio e vídeo.

Neste artigo, você aprenderá a criar um link profundo:

• Para iniciar um novo chat
• Para abrir uma caixa de diálogo de agendamento de reunião
• Para iniciar uma chamada de áudio e vídeo
• Para compartilhar conteúdo no estágio em reuniões
• Para o painel lateral da reunião
• Para ingressar em uma reunião

Link profundo para iniciar um novo chat

Os aplicativos podem iniciar um novo chat com uma lista de usuários e fornecer informações adicionais, como nome do chat e mensagem de rascunho, usando 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 de ID do usuário é compatível com o UserPrincipalName do Microsoft Entra, como somente um endereço de email.
• topicName: um campo opcional para o nome de exibição do chat se um chat tiver três ou mais usuários. 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 usar esse link profundo com seu bot, especifique o link profundo como o destino da URL no botão do seu card ou toque em ação por meio do openUrl tipo de ação. Os aplicativos também podem usar a biblioteca de cliente JavaScript do Teams (TeamsJS) v.2.0 ou posterior para criar isso sem precisar preparar manualmente o link profundo. O exemplo a seguir usa o TeamsJS para marcar se há suporte para a funcionalidade de chat:

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

Link profundo para abrir uma caixa de diálogo de agendamento de reunião

Você pode criar um link profundo nos aplicativos do Teams para abrir uma caixa de diálogo de agendamento de reunião e fornecer informações, como o título da reunião e os participantes, usando os seguintes métodos:

• Configurar o link profundo manualmente para abrir uma caixa de diálogo de agendamento de reunião
• Configurar um link profundo usando a biblioteca TeamsJS para abrir uma caixa de diálogo de agendamento de reunião

Embora recomendemos o uso de APIs tipadas do TeamsJS, é possível criar manualmente links profundos para a caixa de diálogo de agendamento interna do Teams.

Configurar o link profundo manualmente para abrir uma caixa de diálogo de agendamento de reunião

Use o seguinte formato para configurar um link profundo que você pode usar em um bot, conector ou card de extensão de mensagem:

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

Os parâmetros de consulta são:

• attendees: Uma lista opcional separada por vírgulas de IDs de usuário que representam os participantes da reunião. O usuário que executa a ação é o organizador da reunião. O campo de ID do usuário suporta apenas o Microsoft Entra UserPrincipalName, normalmente um endereço de email.
• 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 término 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.

Para usar esse link profundo com seu bot, você pode especificar o link profundo como o destino da URL no botão do seu card ou como uma ação de toque por meio do openUrl tipo de ação.

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​​​​​​​​​​​​​​

Configurar um link profundo usando a biblioteca TeamsJS para abrir uma caixa de diálogo de agendamento de reunião

Você também pode usar o TeamsJS v.2.0 ou posterior no aplicativo Teams para abrir a caixa de diálogo de agendamento de reunião sem precisar preparar o link manualmente. Para abrir a caixa de diálogo de agendamento no Teams, você deve continuar usando o método original baseado em URL de link profundo, pois o Teams ainda não dá suporte ao recurso 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 */ }

// Open a scheduling dialog from your tab
microsoftTeams.executeDeepLink("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​​​​​​​​​​​​​​");

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.

Link profundo para iniciar uma chamada de áudio e vídeo com usuários

Você pode configurar seus aplicativos do Teams para preparar um link profundo para os usuários iniciarem uma chamada individual, uma chamada em grupo ou uma chamada de vídeo. Você pode invocar chamadas somente de áudio ou de áudio e vídeo para um único usuário ou um grupo de usuários especificando o tipo de chamada e os participantes. Antes de o Teams fazer a chamada, o cliente solicita uma confirmação. Se houver uma chamada em grupo, você poderá chamar um conjunto de usuários VoIP e PSTN na mesma chamada de link direto.

Em uma chamada de vídeo, o cliente do Teams pede confirmação antes de ativar o vídeo do chamador 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.

Você pode configurar links profundos de uma das duas maneiras a seguir:

• Configurar o link profundo manualmente para iniciar uma chamada de áudio e vídeo com usuários
• Configurar um link profundo usando a biblioteca TeamsJS para iniciar uma chamada de áudio e vídeo com os usuários

Configurar o link profundo manualmente para iniciar uma chamada de áudio e vídeo com usuários

Embora recomendemos o uso das APIs tipadas do TeamsJS v.2.0 ou posterior, você também pode usar um link profundo configurado manualmente para iniciar uma chamada. Consulte os seguintes formatos:

Estes são os parâmetros de consulta:

• users: uma lista separada por vírgulas de IDs de usuário que representam os participantes da chamada. O campo de ID do usuário é compatível com o Microsoft Entra UserPrincipalName, normalmente um endereço de email ou, em uma chamada PSTN, é compatível com um PSTN MRI 4:<phonenumber>.
• withVideo: um parâmetro opcional, que você pode usar para fazer uma chamada de vídeo. A configuração desse parâmetro ativa apenas a câmera do chamador. O destinatário da chamada tem a opção de atender por meio de uma chamada de áudio ou de áudio e vídeo por meio da janela de notificação de chamada do Teams.

Configurar um link profundo usando a biblioteca TeamsJS para iniciar uma chamada de áudio e vídeo com os usuários

Os aplicativos também podem usar o TeamsJS v.2.0 ou posterior para iniciar chamadas sem precisar preparar manualmente esses links profundos. O código a seguir demonstra o uso 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 */ }

Link profundo para compartilhar conteúdo no palco em reuniões

Para adicionar um link profundo para compartilhar conteúdo no palco, você precisa ter um contexto de aplicativo. O contexto do aplicativo permite que o cliente do Teams busque o manifesto do aplicativo e Marque se o compartilhamento na janela de conteúdo compartilhado é possível. Veja a seguir um exemplo de um contexto de aplicativo:

{ "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 do aplicativo são:

• appID: essa é a ID que pode ser obtida do manifesto do aplicativo.
• appSharingUrl: A URL, que precisa ser compartilhada no estágio, deve ser um domínio válido definido no manifesto do aplicativo. Se a URL não for um domínio válido, uma caixa de diálogo de erro será exibida para fornecer ao usuário uma descrição do erro.
• useMeetNow: inclui um parâmetro booliano que pode ser verdadeiro ou falso.

  • Verdadeiro: quando o useMeetNow valor for verdadeiro e se não houver nenhuma reunião em andamento, uma nova reunião Reunir Agora será iniciada. Quando houver uma reunião em andamento, esse valor será ignorado.

  • False: o valor padrão de useMeetNow é false, o que significa que quando um link profundo é compartilhado com o estágio e não há nenhuma reunião em andamento, um pop-up de calendário será exibido. No entanto, você pode compartilhar diretamente durante uma reunião.

Verifique se todos os parâmetros de consulta estão codificados corretamente como URI e se o contexto do aplicativo deve ser codificado duas vezes na URL final. Observe o exemplo a seguir:

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");

Um link profundo pode ser iniciado na Web do Teams ou na área de trabalho do cliente móvel ou da área de trabalho do Teams.

Os parâmetros de consulta são:

• deepLinkId: qualquer identificador usado para correlação de telemetria.
• fqdn: fqdn é um parâmetro opcional, que pode ser usado para alternar para um ambiente apropriado de uma reunião para compartilhar um aplicativo no palco. Ele dá suporte a cenários em que um compartilhamento de aplicativo específico ocorre em um ambiente específico. O valor padrão de fqdn é URL da empresa, e os valores possíveis são Teams.live.com para Teams for Life, teams.microsoft.comou teams.microsoft.us.

Você pode gerar um link profundo para compartilhar o aplicativo no estágio e para iniciar ou ingressar em uma reunião.

Link profundo para o painel lateral da reunião

Você pode gerar um link profundo para o painel lateral da reunião em uma reunião. Use o seguinte formato para criar um link profundo para o painel lateral 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 padrão, um link profundo é aberto em um painel lateral da reunião. Para abrir um link profundo diretamente em um aplicativo, em vez do painel lateral da reunião, adicione openInMeeting=false o formato de link profundo:

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

Para obter mais informações, confira o link profundo para uma guia.

O link profundo não abre no painel lateral da reunião nos seguintes cenários:

• Não há nenhuma reunião ativa.
• O aplicativo não tem sidePanel contexto declarado no manifesto do aplicativo.
• openInMeeting está definido como false no link profundo.
• O link profundo é selecionado fora da janela ou componente da reunião.
• O link profundo não corresponde à reunião atual, como um link profundo criado em outra reunião.

Link profundo para ingressar em uma reunião

O aplicativo Teams pode ler a URL para ingressar em uma URL de reunião por meio de APIs do Graph. Esse link profundo exibe a interface do usuário para o usuário ingressar na reunião. Para obter mais informações, consulte Obter onlineMeeting e obter detalhes da reunião.

Exemplo de código