Criar seu primeiro bot para o TeamsCreate your first bot for Teams

Este tutorial ensina você a criar um aplicativo de bot básico.This tutorial teaches you to build a basic bot app. Um bot age como um intermediário entre usuários do Teams e seu aplicativo Web ou serviço com uma interface de conversa.A bot acts as an intermediary between Teams users and your web app or service with a conversational interface. As pessoas podem conversar com um bot para obter informações rapidamente ou iniciar fluxos de trabalho e tarefas executadas pelo seu serviço.People can chat with a bot to quickly get information or initiate workflows and tasks performed by your service.

O que você aprenderáWhat you'll learn

  • Crie um projeto de aplicativo e um bot usando o microsoft Teams Toolkit para Visual Studio Código.Create an app project and bot using the Microsoft Teams Toolkit for Visual Studio Code.
  • Entenda as configurações de aplicativo do Teams relevantes para bots.Understand the Teams app configurations relevant to bots.
  • Hospede e execute um aplicativo localmente usando uma solução de túnel localhost.Host and run an app locally using a localhost tunneling solution.
  • Fazer sideload e testar um bot no Teams.Sideload and test a bot in Teams.

Pré-requisitosPrerequisites

Certifique-se de entender como configurar e criar um aplicativo simples do Teams.Ensure that you understand how to set up and build a simple Teams app. Para obter mais informações, consulte criar seu primeiro aplicativo do Microsoft Teams "Hello, World!".For more information, see create your first Microsoft Teams "Hello, World!" app.

1. Crie seu projeto de aplicativo1. Create your app project

O microsoft Teams Toolkit ajuda você a configurar os seguintes componentes para seu aplicativo:The Microsoft Teams Toolkit helps you set up the following components for your app:

  • Configurações de aplicativos e scaffolding relevantes para botsApp configurations and scaffolding relevant to bots
  • Bot que é registrado automaticamente no Serviço de Bot do Microsoft AzureBot that's automatically registered with the Microsoft Azure Bot Service

Para criar seu projeto de aplicativoTo create your app project

  1. Em Visual Studio Código, selecione Microsoft Teams na Barra de Atividades à esquerda e escolha Criar um novo aplicativo do Teams.

    Captura de tela mostrando como criar um aplicativo no teams Toolkit.

  2. Quando solicitado, entre com sua conta de desenvolvimento do Microsoft 365.When prompted, sign in with your Microsoft 365 development account.

  3. Na tela Selecionar projeto, selecione Bots de conversa:On the Select project screen, select Conversation bots:

    Captura de tela mostrando como criar um novo bot no teams Toolkit.

  4. Na tela Configurar projeto, insira um nome para seu bot.On the Configure project screen, enter a name for your bot. Esse é o nome padrão para seu aplicativo e também o nome do diretório do projeto do aplicativo em sua máquina local.This is the default name for your app and also the name of the app project directory on your local machine.

  5. Selecione Criar um novo Registro de Bot Criar > Bot, conforme mostrado na imagem a seguir:Select Create a new Bot > Create Bot Registration as shown in the following image:

    Captura de tela mostrando a nomeação de novo bot no teams Toolkit.

    Se tiver êxito, seu novo bot terá um status Registrado.If successful, your new bot will have a Registered status. Agora seu bot é registrado automaticamente no Serviço de Bot do Microsoft Azure.Now your bot is automatically registered with the Microsoft Azure Bot Service.

    Captura de tela mostrando o registro de novo bot no teams Toolkit.

  6. Selecione Concluir na parte inferior da tela e salve seu projeto em seu computador.Select Finish at the bottom of the screen and save your project on your machine.

2. Entenda os componentes do projeto do aplicativo2. Understand your app project components

Grande parte das configurações e scaffolding do aplicativo são configuradas automaticamente quando você cria seu projeto com o teams Toolkit.Much of the app configurations and scaffolding are set up automatically when you create your project with the Teams Toolkit. Vamos ver os principais componentes para a criação de um bot:Let's look at the main components for building a bot:

Captura de tela mostrando um scaffold de projeto no teams Toolkit.

Se você criou uma guia em outro tutorial, o scaffolding do aplicativo para o bot é diferente.If you created a tab in another tutorial, the app scaffolding for the bot is different. Ao contrário das guias, o desenvolvimento de bot não exige que você crie nenhum componente web front-end ou use o SDK do cliente JavaScript do Teams.Unlike tabs, bot development doesn't require you to build any front-end web components or use the Teams JavaScript client SDK. Em vez disso, o scaffolding usa o Microsoft Bot Framework, que é um SDK de código aberto para criar bots inteligentes de nível empresarial que podem funcionar na Web, no celular e, claro, no Teams!Instead, the scaffolding uses the Microsoft Bot Framework, which is an open-source SDK for building intelligent, enterprise-grade bots that can work on the web, mobile, and of course Teams!

O arquivo, localizado no diretório raiz do seu projeto, é o manipulador específico do Teams que lida com atividades de bot, como como o bot responde botActivityHandler.js a mensagens específicas.The botActivityHandler.js file, located in the root directory of your project, is the Teams-specific handler that handles bot activities, such as how the bot responds to specific messages. O scaffolding de aplicativo fornece um arquivo, localizado no diretório raiz do seu projeto, é o manipulador específico do Teams que lida com atividades de bot, como como o bot responde a mensagens botActivityHandler.js específicas.The app scaffolding provides a botActivityHandler.js file, located in the root directory of your project, is the Teams specific handler that handles bot activities such as how the bot responds to specific messages.

3. Expor seu localhost com segurança à Internet3. Securely expose your localhost to the internet

Dê uma olhada no arquivo, que cria um servidor HTTP e lida com o roteamento para ouvir solicitações index.js de entrada para seu bot.Take a look at the index.js file, which creates an HTTP server and handles routing to listen for incoming requests to your bot. A URL do ponto de extremidade do seu /api/messages aplicativo é para responder às solicitações do cliente:The /api/messages is your app's endpoint URL to respond to client requests:

server.post('/api/messages', (req, res) => { 
  adapter.processActivity(req, res, async (context) => { 
    await botActivityHandler.run(context); 
  }); 
}); 

Para encaminhar as solicitações para a lógica do bot, você deve configurar uma URL publicamente acessível, como , em https://example.com/api/messages vez de https://localhost .To forward the requests to your bot's logic, you must set up a publicly accessible URL, such as https://example.com/api/messages, instead of https://localhost. Como seu aplicativo está em execução no momento do seu localhost, você deve canalizando a rede.Because your app is running from your localhost currently, you must tunnel the network.

O túnel é um protocolo que permite que você transporte dados em uma rede.Tunneling is a protocol that allows you to transport data across a network. E o túnel localhost fornece uma conexão entre o computador local e uma conexão remota.And localhost tunneling gives you a connection between your local machine and a remote connection. Para expor seu localhost com segurança à Internet, recomendamos que você use a ferramenta de terceiros chamada, ngrok.To securely expose your localhost to the internet, we recommend you to use the 3rd party tool called, ngrok. Isso lhe dará uma URL segura.This will give you a secure URL.

  1. Vá para o site ngrok.com e siga a instrução para instalar e configurar o ngrok em seu ambiente.Go to the ngrok.com site and follow the instruction to install and set up ngrok in your environment.

    Adicione o caminho completo ao arquivo ngrok.exe que você instalou à variável de ambiente PATH do sistema.Add the full path to the ngrok.exe file that you installed to the system PATH environment variable. As etapas exatas são específicas do shell que você está usando.The exact steps are specific to the shell that you are using.

  2. Depois de terminar de defini-lo, abra um terminal e execute ngrok http -host-header=rewrite 3978 .After you have finished setting it up, open a terminal and run ngrok http -host-header=rewrite 3978.

    Agora o ngrok fornece uma URL pública e segura que encaminha para o seu localhost na porta 3978, portanto, copie a URL HTTPS, por exemplo, conforme mostrado na captura de tela abaixo, já que o Teams requer conexões https://287a4f4223bc.ngrok.io HTTPS:Now ngrok provides you a public, secure URL that forwards to your localhost at port 3978, so copy the HTTPS URL, for example, https://287a4f4223bc.ngrok.io as shown in the screenshot below, since Teams requires HTTPS connections:

    Captura de tela mostrando o tunelamento de localhost com ngrok.

  3. Registre a URL no manifesto do aplicativo.Register the URL in your app manifest.

4. Registre seu ponto de extremidade de bot4. Register your bot endpoint

Para usar um bot no Teams, você deve registrá-lo com o Serviço bot do Azure.To use a bot in Teams, you must register it with the Azure Bot Service. Isso é feito automaticamente quando você configura seu aplicativo usando o teams Toolkit.This is done automatically when you set up your app using the Teams Toolkit.

Você ainda deve especificar um endereço de ponto de extremidade para receber e processar mensagens de usuário, ou solicitações, enviadas para o bot.You must still specify an endpoint address to receive and process user messages, or requests, sent to the bot. Normalmente, a URL se parece com https://HOST_URL/api/messages .Typically, the URL looks like https://HOST_URL/api/messages. Você pode configurar isso rapidamente no kit de ferramentas.You can configure this quickly in the toolkit.

  1. Em Visual Studio Código, abra o Microsoft Teams Toolkit.In Visual Studio Code, open Microsoft Teams Toolkit.

  2. Selecione Bots > Registros de bots existentes e selecione o bot que você criou durante a instalação.Select Bots > Existing bot registrations and select the bot you created during setup.

  3. No campo endereço do ponto de extremidade bot, insira a URL do ngrok, por exemplo, , onde você está hospedando o bot e https://287a4f4223bc.ngrok.io anexar a /api/messages ele:In the Bot endpoint address field, enter the ngrok URL, for example, https://287a4f4223bc.ngrok.io, where you're hosting the bot and append /api/messages to it:

    Captura de tela mostrando como túnel localhost com ngrok.

    Seu bot poderá responder a mensagens no Teams depois de configurar o ponto de extremidade corretamente.Your bot will be able to respond to messages in Teams, after you set up the endpoint correctly.

5. Crie e execute seu aplicativo5. Build and run your app

Você configurou uma URL para hospedar seu bot e configurá-lo para manipular mensagens.You've set up a URL to host your bot and configured it to handle messages. É hora de fazer o aplicativo funcionar.It's time to get your app up and running.

  1. Em um terminal, vá para o diretório raiz do seu projeto de aplicativo e execute npm install .In a terminal, go to the root directory of your app project and run npm install.

  2. Executar npm start .Run npm start.

    Se tiver êxito, você verá a seguinte mensagem indicando que seu bot está escutando atividades em seu localhost :If successful, you see the following message indicating your bot is listening for activity at your localhost:

    Bot/ME service listening at http://localhost:3978

6. Fazer sideload do bot no Teams6. Sideload your bot in Teams

Com o bot em execução, você pode instalá-lo no Teams.With your bot running, you can install it in Teams.

Dica

Se você ainda não fez sideload de um aplicativo do Teams antes e correu para problemas, siga estas instruções.If you haven't sideloaded a Teams app before and run into issues, follow these instructions.

  1. Em Visual Studio Código, selecione a chave F5 para iniciar um cliente Web do Teams.In Visual Studio Code, select the F5 key to launch a Teams web client.

  2. Na caixa de diálogo de instalação do aplicativo, selecione Adicionar para mim.In the app install dialog, select Add for me.

    Observação

    Por padrão, o aplicativo é adicionado à sua mensagem de chat direta 1:1, no entanto, você pode optar por instalá-la a uma equipe ou chat clicando na pequena seta ao lado de Adicionar para mim.By default, the app is added to your 1:1 direct chat message, however you can choose to install it to a team or chat by clicking the little arrow beside Add for me. Neste tutorial, vamos clicar em Adicionar.In this tutorial, let’s just click Add.

    Captura de tela mostrando o localhost de tunelamento com ngrok.

7. Teste seu bot7. Test your bot

Vamos dizer "Olá" para seu bot.Let's say "Hello" to your bot.

  • Na caixa de redação, envie uma Hello mensagem.In the compose box, send a Hello message. Seu bot responde a algo como a seguinte mensagem:Your bot replies with something like the following message:

    Uma captura de tela mostrando um usuário dizer "Hello" para um bot do Teams e obter uma resposta.

    Agora você criou um bot básico do Teams que pode se comunicar com usuários um-a-um ou em configurações de grupo (canais e chats) 🎉You have now created a basic Teams bot that can communicate with users one-on-one or in group settings (channels and chats) 🎉

Solucionar problemas de seu botTroubleshoot your bot

As informações a seguir podem ajudar se você tiver problemas ao concluir este tutorial.The following information may help if you had issues completing this tutorial.

Bot não está conectado ao TeamsBot isn't connected to Teams

Se você instalou seu aplicativo, mas o bot não está funcionando, certifique-se de que o bot está conectado ao canal do Teams do Serviço de Bot do Azure .If you installed your app but the bot isn't working, make sure the bot is connected to the Azure Bot Service's Teams channel.

É importante entender que isso não é o mesmo que um canal no Teams.It's important to understand that this isn't the same as a channel in Teams. Nesse caso, um canal é como o Serviço bot do Azure conecta seu bot ao Teams ou a outro aplicativo de comunicações da Microsoft ou de terceiros com suporte.In this case, a channel is how the Azure Bot Service connects your bot to Teams or another supported Microsoft or third-party communications app.

Confira tambémSee also

Próxima etapaNext step