Partilhar via

Link profundo para o chat do Teams

  • Artigo

Você pode criar um link profundo para um chat do Teams, como iniciar um novo chat, ir para uma conversa de canal e acessar um arquivo em um canal.

Neste artigo, você aprenderá a criar:

Você pode navegar até ou criar chats privados entre usuários com a biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS) especificando o conjunto de participantes. Se não houver um chat com os participantes especificados, o link direcionará o usuário para um novo chat vazio.

Quando um usuário cria um novo chat usando um link profundo, o Teams cria o novo chat no estado de rascunho até que o usuário envie a primeira mensagem. Você também pode fornecer o nome do chat se ele ainda não existir, juntamente com o texto que deve ser inserido na caixa de composição do usuário. Considere este um atalho para o usuário que está tomando a ação manual de navegar ou criar o chat e, em seguida, compor a mensagem.

Como exemplo de caso de uso, se você estiver recuperando uma informação de perfil de usuário do Microsoft 365 do seu bot como um cartão, esse link profundo poderá permitir que o usuário do aplicativo converse facilmente com essa pessoa.

Você pode configurar links profundos para iniciar um novo chat de uma das duas maneiras a seguir:

Embora o uso das APIs fortemente tipadas seja recomendado, você pode usar o seguinte formato para um link profundo criado manualmente que pode ser usado em um bot, conector ou cartão de extensão de mensagem:

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

Para usar esse link profundo com o bot, especifique o link profundo como o destino da URL no botão do cartão ou toque em ação por meio do tipo de açãoopenUrl.

Os parâmetros de consulta são:

  • users: uma 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. Atualmente, o parâmetro ID do usuário dá suporte ao Microsoft Entra UserPrincipalName, como somente um endereço de email.
  • topicName: um parâmetro 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 composição do usuário do aplicativo atual enquanto o chat está no estado de rascunho.

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

O exemplo a seguir demonstra como abrir uma mensagem de chat para um grupo de participantes com uma mensagem inicial. Você pode direcionar o link profundo para um chat existente ou novo. Se um chat já existir, o link profundo será aberto nesse 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 */ }

Para navegar até uma conversa de chat específica no Teams, use o seguinte formato de link profundo:

https://teams.microsoft.com/l/chat/<chatId>/conversations

O parâmetro de consulta é chatId, que representa a ID de chat da conversa. O formato com suporte para chatId é 19:xxx.

Exemplo: https://teams.microsoft.com/l/chat/19:c6d70e392a384916c3262b15406d763e@thread.v2/conversations

Você pode usar o seguinte formato de link profundo para acessar uma conversa específica no thread do canal:

https://teams.microsoft.com/l/message/<channelId>/<parentMessageId>?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=<parentMessageId>&teamName=<teamName>&channelName=<channelName>&createdTime=<createdTime>

Os parâmetros de consulta são:

  • channelId: ID do Canal da conversa. Por exemplo, 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: ID do locatário, como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId: ID do grupo do arquivo. Por exemplo, 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: ID da mensagem pai da conversa.
  • teamName: nome da equipe.
  • channelName: nome do canal da equipe.

Observação

Você pode ver channelId e groupId na URL do canal.

Exemplo: https://teams.microsoft.com/l/message/<channelId>/1648741500652?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=1648741500652&teamName=<teamName>&channelName=<channelName>&createdTime=1648741500652

Use o seguinte formato de link profundo para navegar um usuário até uma mensagem em um chat pessoal ou em grupo no Teams:

https://teams.microsoft.com/l/message/{chatId}/{messageId}?tenantId=<tenantId>?context={"contextType":"chat"}

Exemplo: https://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Os parâmetros de consulta são:

  • chatId: ID de chat da conversa. O formato com suporte para chatId é 19: xxx. Por exemplo, 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Os aplicativos podem ler uma ID de chat por meio do contexto do aplicativo no Teams, a carga de entrada para bot ou por meio de APIs do Microsoft Graph.

    Observação

    Para chats individuais com bot, a carga de entrada para bot contém a ID da conversa em um formato:xxx.

  • messageId: ID de mensagem exclusiva de cada mensagem em um chat. Quando um bot posta uma mensagem no chat, ela messageId é retornada. Você também pode obter as messageIdAPIs do Microsoft Graph. Por exemplo, 1563480968434.
  • context: especifique o contextType como chat.

Exemplo: http://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Para navegar até uma equipe específica, use o seguinte formato de link profundo:

https://teams.microsoft.com/l/team/<channelId>/conversations?groupId=<groupId>&tenantId=<tenantId>

Os parâmetros de consulta são:

  • channelId: ID do canal da conversa (URL codificada). Por exemplo, 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: ID do grupo do arquivo. Por exemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID do locatário, como 72f988bf-86f1-41af-91ab-2d7cd011db47.

Observação

Você pode obter channelId e groupId na URL da equipe.

Exemplo: https://teams.microsoft.com/l/team/19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2/conversations?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

Você pode usar os seguintes formatos de link profundo para navegar até determinados canais:

  • Canal padrão: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>

    Exemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

  • Canal privado: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    Exemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true

  • Canal compartilhado: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    Exemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true&allowXTenantAccess=true

Os parâmetros de consulta são:

  • channelId: ID do canal da conversa (URL codificada). Por exemplo, 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: nome do canal da equipe (URL codificada). Por exemplo, My%20example%20channel.
  • groupId: ID de grupo da equipe. Por exemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID do locatário, como 72f988bf-86f1-41af-91ab-2d7cd011db47.
  • ngc: indica um canal de próxima geração. Para canais privados, precisa ser definido como true.
  • allowXTenantAccess: indica um canal que pode ser acessado entre limites de locatário. Para canais compartilhados, precisa ser definido como true.

Use o seguinte formato de link profundo pode ser usado em um bot, conector ou extensão de mensagem cartão para configurar um link profundo para se conectar a um arquivo em um canal:

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectUrl=<objectUrl>&baseUrl=<baseUrl>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

Os parâmetros de consulta são:

  • fileId: ID de arquivo exclusivo do Sharepoint Online, também conhecida como sourcedoc. Por exemplo, 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: ID do locatário, como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType: tipo de arquivo compatível, como .docx, .pptx, .xlsx e .pdf.
  • objectUrl: URL do objeto do arquivo. O formato é https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Por exemplo, https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: URL base do arquivo. O formato é https://{tenantName}.sharepoint.com/sites/{TeamName}. Por exemplo, https://microsoft.sharepoint.com/teams.
  • serviceName: Nome do serviço, ID do aplicativo. Por exemplo, teams.
  • threadId: o threadID é a ID da equipe em que o arquivo é armazenado. É opcional e não pode ser definido para arquivos armazenados na pasta OneDrive de um usuário. Por exemplo, 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>.
  • groupId: ID do grupo do arquivo. Por exemplo, ae063b79-5315-4ddb-ba70-27328ba6c31e.

Observação

  • Você pode ver threadId e groupId na URL do canal.
  • No novo cliente do Teams, o formato de link profundo usando objectURL para um arquivo em um canal não tem suporte, use objectUrl no formato de link profundo.

O formato de exemplo a seguir ilustra link profundo para arquivos:

https://teams.microsoft.com/l/file/5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80?tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb&fileType=pptx&objectUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform%2FShared%20Documents%2FFC7-%20Bot%20and%20Action%20Infra%2FKaizala%20Actions%20in%20Adaptive%20Cards%20-%20Deck.pptx&baseUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform&serviceName=teams&threadId=19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

Serialização deste objeto

{
fileId: "5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80",
tenantId: "0d9b645f-597b-41f0-a2a3-ef103fbd91bb",
filetype: = "pptx",
objectUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform/Shared Documents/FC7- Bot and Action Infra/Kaizala Actions in Adaptive Cards - Deck.pptx",
baseUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform",
serviceName: "teams",
threadId: = "19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Link profundo que consome A ID da sub-entidade Este exemplo mostra como usar um link profundo de um chat de bot para uma guia que consome a ID da Sub entidade. Ele também mostra links profundos para:
– Navegando até um aplicativo
– Navegando até um chat
– Abrir uma caixa de diálogo de perfil
– Abrir uma caixa de diálogo de agendamento		 View View