Adicionar bots personalizados ao Microsoft Teams com WebHooks de saídaAdd custom bots to Microsoft Teams with outgoing webhooks

O que são WebHooks de saída no Microsoft Teams?What are outgoing webhooks in Teams?

Os WebHooks são uma ótima maneira de a integração do Microsoft Teams com aplicativos externos.Webhooks are a great way for Teams to integrate with external apps. Um webhook é essencialmente uma solicitação POST enviada para uma URL de retorno de chamada.A webhook is essentially a POST request sent to a callback URL. No Teams, os WebHooks de saída fornecem uma maneira simples de permitir que os usuários enviem mensagens para o seu serviço Web sem precisar passar por todo o processo de criação de bots por meio da Microsoft bot Framework.In Teams, outgoing webhooks provide a simple way to allow users to send messages to your web service without having to go through the full process of creating bots via the Microsoft Bot Framework. Os WebHooks de saída postam dados do teams para qualquer serviço escolhido capaz de aceitar uma carga JSON.Outgoing webhooks post data from Teams to any chosen service capable of accepting a JSON payload. Após um webhook de saída ser adicionado a uma equipe, ele atua como bot, ouvindo canais para mensagens usando ** @ menção**, enviando notificações para serviços Web externos e respondendo com mensagens avançadas que podem incluir cartões e imagens.Once an outgoing webhook is added to a team, it acts like bot, listening in channels for messages using @mention, sending notifications to external web services, and responding with rich messages that can include cards and images.

Recursos de chave de webhook de saídaOutgoing webhook key features

RecursoFeature DescriçãoDescription
Configuração com escopoScoped Configuration Os WebHooks têm escopo no nível da equipe.Webhooks are scoped at the team level. Você precisará passar pelo processo de instalação para cada equipe à qual deseja adicionar o webhook de saída.You’ll need to go through the setup process for each team you want to add your outgoing webhook to.
Mensagens reativasReactive Messaging Os usuários devem usar @mention para o webhook para receber mensagens.Users must use @mention for the webhook to receive messages. Atualmente, os usuários só podem enviar uma mensagem para um webhook de saída em canais públicos e não dentro do escopo pessoal ou privadoCurrently users can only message an outgoing webhook in public channels and not within the personal or private scope
Troca de mensagens HTTP padrãoStandard HTTP message exchange As respostas aparecerão na mesma cadeia da mensagem de solicitação original e podem incluir qualquer conteúdo de mensagem da estrutura de bot (Rich Text, imagens, cartões e emojis).Responses will appear in the same chain as the original request message and can include any Bot Framework message content (rich text, images, cards, and emojis). Observação: embora os WebHooks de saída possam usar cartões, eles não podem usar nenhuma ação de cartão, exceto para openURL .Note: Although outgoing webhooks can use cards, they cannot use any card actions except for openURL.
Suporte ao método de API do teamsTeams API method support No Teams, os WebHooks de saída enviam um HTTP POST para um serviço Web e processam uma resposta de retorno.In Teams, outgoing webhooks send an HTTP POST to a web service and process a response back. Eles não podem acessar nenhuma outra API como recuperar a lista ou a lista de canais em uma equipe.They cannot access any other APIs like retrieve the roster or list of channels in a team.

Adicionando processamento de webhook de saída ao seu aplicativoAdding outgoing webhook processing to your app

Cenário: enviar notificações de status de alteração em um servidor de banco de dados de canal do teams para seu aplicativo.Scenario: Push change status notifications on a Teams channel database server to your app.
Exemplo: você tem um aplicativo de linha de negócios que controla todas as operações CRUD feitas a registros de funcionários por usuários de canal de RH de canal de equipe em uma locação do Office 365.Example: You have a line-of-business app that tracks all CRUD operations made to employee records by Teams channel HR users across an Office 365 tenancy.

1. criar uma URL no servidor de seu aplicativo para aceitar e processar uma solicitação POST com uma carga JSON1. Create a URL on your app's server to accept and process a POST request with a JSON payload

Seu serviço receberá mensagens no esquema de mensagens do serviço bot do Azure padrão.Your service will receive messages in the standard Azure bot service messaging schema. O conector da estrutura de bot é um serviço RESTful que permite que seu serviço processe o intercâmbio de mensagens formatadas por JSON por meio de protocolos HTTPS, conforme documentado na API do serviço de bot do Azure.The Bot Framework connector is a RESTful service that enables your service to process the interchange of JSON formatted messages via HTTPS protocols as documented in the Azure Bot Service API. Como alternativa, você pode seguir o [Microsoft bot Framework SDK] para processar e analisar mensagens.Alternatively, you can follow the [Microsoft Bot Framework SDK] to process and parse messages. Consulte também sobre o serviço de bot do Azure.See also About Azure Bot Service.

Os WebHooks de saída têm escopo para o team nível e são visíveis para todos os membros da equipe.Outgoing webhooks are scoped to the team level and are visible to all members of the team. Assim como um bot, os usuários precisam ** @ mencionar** o nome do webhook de saída para chamá-lo no canal.Just like a bot, users are required to @mention the name of the outgoing webhook to invoke it in the channel.

2. Crie um método para verificar o token HMAC de saída de webhook2. Create a method to verify the outgoing webhook HMAC token

Para garantir que o serviço esteja recebendo chamadas apenas de clientes do Microsoft Teams, o Microsoft Teams fornece um código HMAC no hmac cabeçalho HTTP que deve sempre ser incluído no seu protocolo de autenticação.To ensure that your service is receiving calls only from actual Teams clients, Teams provides an HMAC Code in the HTTP hmac header that should always be included in your authentication protocol.

O código deve sempre validar a assinatura HMAC incluída na solicitação:Your code should always validate the HMAC signature included in the request:

  • Gere o token HMAC do corpo da solicitação da mensagem.Generate the HMAC token from the request body of the message. Há bibliotecas padrão para fazer isso na maioria das plataformas (consulte crypto para Node.js ou consulte Teams webhook Sample for C # ).There are standard libraries to do this on most platforms (see Crypto for Node.js or see Teams Webhook Sample for C#). O Microsoft Teams usa a criptografia HMAC de SHA256 padrão.Microsoft Teams uses standard SHA256 HMAC cryptography . Você precisará converter o corpo em uma matriz de bytes em UTF8.You will need to convert the body to a byte array in UTF8.
  • Compute o hash da matriz de bytes do token de segurança fornecido pelo Microsoft Teams quando você registrou o webhook de saída no cliente do teams].Compute the hash from the byte array of the security token provided by Teams when you registered the outgoing webhook in the Teams client]. Confira criar um webhook de saída, abaixo.See Create an outgoing webhook, below.
  • Converta o hash em uma cadeia de caracteres usando a codificação UTF-8.Convert the hash to a string using UTF-8 encoding.
  • Compare o valor da cadeia de caracteres do hash gerado com o valor fornecido na solicitação HTTP.Compare the string value of the generated hash with the value provided in the HTTP request.

3. criar um método para enviar uma resposta de êxito ou falha3. Create a method to send a success or failure response

As respostas do webhook de saída aparecerão na mesma cadeia de resposta da mensagem original.Responses from your outgoing webhook will appear in the same reply chain as the original message. Quando o usuário executa uma consulta, o Microsoft Teams emite uma solicitação HTTP síncrona para o seu serviço e seu código terá 5 segundos para responder à mensagem antes que o tempo limite da conexão expire e seja encerrado.When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service and your code will have 5 seconds to respond to the message before the connection times out and terminates.

Resposta de exemploExample response

{
    "type": "message",
    "text": "This is a reply!"
}

Criar um webhook de saídaCreate an outgoing webhook

  1. Selecione a equipe apropriada e selecione Gerenciar equipe no menu suspenso (•••).Select the appropriate team and select Manage team from the (•••) drop-down menu.
  2. Escolha a guia aplicativos na barra de navegação.Choose the Apps tab from the navigation bar.
  3. No canto inferior direito da janela, selecione criar um webhook de saída.From the window's lower right corner select Create an outgoing webhook.
  4. Na janela pop-up resultante, preencha os campos obrigatórios:In the resulting popup window complete the required fields:
  • Nome -o título do webhook e o @mention toque.Name - The webhook title and @mention tap.
  • URL de retorno de chamada : o ponto de extremidade HTTPS que aceita cargas JSON e receberá solicitações post do teams.Callback URL - The HTTPS endpoint that accepts JSON payloads and will receive POST requests from Teams.
  • Descrição -uma cadeia de caracteres detalhada que aparecerá no cartão de perfil e no painel de aplicativos de nível de equipe.Description - A detailed string that will appear in the profile card and the team-level App dashboard.
  • Imagem de perfil (opcional) um ícone de aplicativo para seu webhook.Profile Picture (optional) an app icon for your webhook.
  • Selecione o botão criar no canto inferior direito da janela pop-up e o webhook de saída será adicionado aos canais da equipe atual.Select the Create button from lower right corner of the pop-up window and the outgoing webhook will be added to the current team's channels.
  • A próxima janela de diálogo exibirá um token de segurança HMAC (código de autenticação de mensagens baseado em hash) que será usado para autenticar chamadas entre o Teams e o serviço externo designado.The next dialog window will display an Hash-based Message Authentication Code (HMAC) security token that will be used to authenticate calls between Teams and the designated outside service.
  • Se a URL for válida e os tokens de autenticação de servidor e cliente forem iguais (ou seja, um handshake HMAC), o webhook de saída estará disponível para os usuários da equipe.If the URL is valid and the server and client authentication tokens are equal (i.e., an HMAC handshake), the outgoing webhook will be available to the team's users.

Exemplos de códigoCode samples

Você pode exibir exemplos de código de webhook de saída no GitHub:You can view outgoing webhook code samples on GitHub:

Node.jsNode.js

OfficeDev/msteams-amostras-saída-webhook-NodeJSOfficeDev/msteams-samples-outgoing-webhook-nodejs

Unidade#C#

OfficeDev/Microsoft-Teams-Sample-saída-webhookOfficeDev/microsoft-teams-sample-outgoing-webhook