Compartilhar via

Ligação avançada para o chat do Teams

  • Artigo

Pode criar uma ligação avançada para um chat do Teams, como iniciar uma nova conversa, aceder a uma conversa de canal e aceder a um ficheiro num canal.

Neste artigo, irá aprender a criar:

Pode navegar ou criar conversas privadas entre utilizadores com a biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams ao especificar 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 utilizador cria uma nova conversa através de uma ligação avançada, o Teams cria o novo chat no estado de rascunho até o utilizador enviar a primeira mensagem. Também pode indicar o nome do chat se ainda não existir, juntamente com o texto que deve ser inserido na caixa de composição do utilizador. Considere isto um atalho para o utilizador efetuar a ação manual de navegar ou criar o chat e, em seguida, compor a mensagem.

Como exemplo de caso de utilização, se estiver a obter informações de perfil de utilizador do Microsoft 365 do seu bot como card, esta ligação avançada pode permitir que o utilizador da aplicação converse facilmente com essa pessoa.

Pode configurar ligações avançadas para iniciar um novo chat de uma das duas formas seguintes:

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

Os parâmetros de consulta são:

  • users: uma lista separada por vírgulas de IDs de utilizador que representam os participantes da conversa. O usuário que executa a ação é sempre incluído como um participante. O parâmetro ID de Utilizador suporta o Microsoft Entra UserPrincipalName, como apenas um endereço de e-mail.
  • topicName: um parâmetro 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 pretende inserir na caixa de composição do utilizador da aplicação 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. Pode direcionar a ligação avançada para uma conversa existente ou nova. Se já existir uma conversa, a ligação avançada é aberta 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 para uma conversação de chat específica no Teams, utilize o seguinte formato de ligação avançada:

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

O parâmetro de consulta é chatId, que representa o ID de chat da conversação. O formato suportado para chatId é 19:xxx.

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

Pode utilizar o seguinte formato de ligação avançada para aceder a uma conversação específica no tópico 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 inquilino, 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

Utilize o seguinte formato de ligação avançada para navegar um utilizador para uma mensagem numa conversa pessoal ou de grupo no Teams:

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

Os parâmetros de consulta são:

  • chatId: ID de chat da conversação. O formato suportado para chatId é 19: xxx. Por exemplo, 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    As aplicações podem ler um ID de chat através do contexto da aplicação no Teams, do payload recebido para o bot ou através das APIs do Microsoft Graph.

    Observação

    Para conversas um-para-um com o bot, o payload recebido para o bot contém o ID de conversação num formato:xxx.

  • messageId: ID de mensagem exclusivo de cada mensagem numa conversa. Quando um bot publica uma mensagem no chat, a messageId mensagem é devolvida. Também pode obter as APIs através do messageIdMicrosoft Graph. Por exemplo, 1563480968434.
  • context: especifique o contextType como 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

Pode iniciar uma conversação com um bot através de uma mensagem pré-preenchida através de uma ligação avançada. Utilize o ID do bot com 28: o prefixo em vez de um endereço de e-mail. O formato da ligação avançada é:

https://teams.microsoft.com/l/chat/0/0?users=28:[bot guid]&message=This%20message%20was%20triggered%20by%20a%20link!

O parâmetro de consulta é bot guid, que é o atributo ID do bot no manifesto da aplicação.

Exemplo: https://teams.microsoft.com/l/chat/0/0?users=28:47345678-2134-6534-9143-65146789012&message=This%20message%20was%20triggered%20by%20a%20link!

A ligação avançada fornecida só carrega a mensagem para a caixa de texto do chat do bot e não envia a mensagem automaticamente. Para enviar a mensagem, tem de selecionar o botão Enviar ou selecionar Enter.

Para navegar para uma determinada equipa, utilize o seguinte formato de ligação avançada:

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ção (CODIFICADO por URL). Por exemplo, 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: ID do grupo do arquivo. Por exemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID do inquilino, como 72f988bf-86f1-41af-91ab-2d7cd011db47.

Observação

Pode obter channelId e groupId no URL da equipa.

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

Pode utilizar os seguintes formatos de ligação avançada para navegar para canais específicos:

  • 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 partilhado: 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ção (CODIFICADO por URL). Por exemplo, 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: nome do canal da equipa (codificado por URL). Por exemplo, My%20example%20channel.
  • groupId: ID de grupo da equipa. Por exemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID do inquilino, como 72f988bf-86f1-41af-91ab-2d7cd011db47.
  • ngc: indica um canal de próxima geração. Para canais privados tem de ser definido como true.
  • allowXTenantAccess: indica um canal que pode ser acedido através dos limites do inquilino. Para canais partilhados tem de ser definido como true.

Utilize o seguinte formato de ligação avançada num bot, conector ou extensão de mensagem card para configurar uma ligação avançada para ligar a um ficheiro num 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 ficheiro exclusivo do Sharepoint Online, também conhecido como sourcedoc ou sharepointIds.listItemUniqueId da resposta da API do Sharepoint Online driveItem . Por exemplo, 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: ID do inquilino, 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 é o ID de equipa da equipa onde o ficheiro está 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 ligação avançada que utiliza objectURL para um ficheiro num canal não é suportado, utilize objectUrl no formato de ligação avançada.

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