Criar uma extensão de mensagens no Microsoft TeamsCreate a messaging extension in Microsoft Teams

Em um nível alto, você precisará concluir as etapas a seguir para criar uma extensão de mensagens.At a high level, you'll need to complete the following steps to create a messaging extension.

  1. Preparar seu ambiente de desenvolvimentoPrepare your development environment
  2. Criar e implantar seu serviço Web (ao desenvolver o uso de um serviço de encapsulamento como o ngrok para executá-lo localmente)Create and deploy your web service (while developing use a tunneling service like ngrok to run it locally)
  3. Registrar seu serviço Web com a estrutura botRegister your web service with the Bot Framework
  4. Criar seu pacote de aplicativosCreate your app package
  5. Carregar um pacote do aplicativo para o Microsoft TeamsUpload your package to Microsoft Teams

A criação do seu serviço Web, a criação do pacote de aplicativos e o registro do serviço Web com a estrutura de bot podem ser feitas em qualquer ordem.Creating your web service, creating your app package, and registering your web service with the Bot Framework can be done in any order. Como essas três partes estão desentrelaçadas, não importa a ordem em que você precisará retornar para atualizar as outras.Because those three pieces are so intertwined, no matter which order you do them in you'll need return to update the others. Seu registro precisa do ponto de extremidade de mensagens do seu serviço Web implantado e seu serviço Web precisa da ID e senha criadas a partir do seu registro.Your registration needs the messaging endpoint from your deployed web service, and your web service needs the Id and password created from your registration. O manifesto do aplicativo também precisa dessa ID para conectar o Microsoft Teams ao seu serviço Web.Your app manifest also needs that Id to connect Teams to your web service.

À medida que você está criando sua extensão de mensagens, você vai migrar regularmente entre alterar o manifesto do aplicativo e implantar o código no seu serviço Web.As you're building your messaging extension, you'll regularly be moving between changing your app manifest, and deploying code to your web service. Ao trabalhar com o manifesto do aplicativo, tenha em mente que você pode manipular manualmente o arquivo JSON ou fazer alterações através do App Studio.When working with the app manifest, keep in mind that you can either manually manipulate the JSON file, or make changes through App Studio. De qualquer forma, você precisará implantar (carregar) seu aplicativo no Teams quando fizer uma alteração no manifesto, mas não é necessário fazê-lo ao implantar as alterações no serviço Web.Either way, you'll need to re-deploy (upload) your app in Teams when you make a change to the manifest, but there's no need to do so when you deploy changes to your web service.

Preparar seu ambiente de desenvolvimentoPrepare your development environment

A primeira coisa que você precisará fazer é preparar seu ambiente de desenvolvimento.The first thing you'll need to do is prepare your development environment. Você precisará certificar-se de que o carregamento de aplicativos personalizados está habilitado para a organização do Office 365 em que você deseja compilar seu aplicativo.You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. Se você precisar de um locatário de desenvolvimento dedicado, você pode se inscrever no programa para desenvolvedores do Office 365.If you need a dedicated development tenant, you can sign up for the Office 365 developer program. Para obter informações adicionais, consulte configurar seu ambiente de desenvolvimento.For additional information see Setup your development environment.

Criar seu serviço WebCreate your web service

O coração de sua extensão de mensagens é seu serviço Web.The heart of your messaging extension is your web service. Ele definirá uma única rota, geralmente /api/messages , para receber todas as solicitações.It will define a single route, typically /api/messages, to receive all requests on. Se você estiver começando a partir do zero, terá algumas opções para escolher.If you're getting started from scratch, you have a few options to choose from.

  • Use um de nossos tutoriais de QuickStartES que orientarão você durante a criação do seu serviço Web.Use one of our quickstarts tutorials that will guide you through the creation of your web service.
  • Escolha uma das amostras de extensão de mensagens disponíveis no repositório de exemplo da estrutura de bot para começar.Choose one of the messaging extension samples available in the Bot Framework sample repository to start from.
  • Se você estiver usando o JavaScript, use o gerador Yeoman para o Microsoft Teams para estruturar seu aplicativo do Teams, incluindo o serviço Web.If you're using JavaScript, use the Yeoman generator for Microsoft Teams to scaffold your Teams app, including your web service.
  • Criar seu serviço Web a partir do zero.Create your web service from scratch. Você pode optar por adicionar o SDK do verificador de bot para o seu idioma ou trabalhar diretamente com as cargas JSON.You can choose to add the Bot Framework SDK for your language, or you can work directly with the JSON payloads.

Registrar seu serviço Web com a estrutura botRegister your web service with the Bot Framework

As extensões de mensagens aproveitam o esquema de mensagens da estrutura de bot e o protocolo de comunicação seguro; Se você ainda não tiver um, você precisará registrar seu serviço Web na estrutura de bot.Messaging extensions take advantage of the Bot Framework's messaging schema and secure communication protocol; if you don't already have one you'll need to register your web service on the Bot Framework. A ID do aplicativo da Microsoft (vamos nos referir a isso como o seu ID de bot de dentro do teams para identificá-lo a partir de outras IDs de aplicativos que você pode estar trabalhando) e o ponto de extremidade de mensagens que seu registrador com a estrutura de bot será usado em sua extensão de mensagens para receber e responder a solicitações.The Microsoft App Id (we'll refer to this as your Bot Id from inside of Teams, to identify it from other App Id's you might be working with) and the messaging endpoint your register with the Bot Framework will be used in your messaging extension to receive and respond to requests. Se você estiver usando um registro existente, certifique-se de habilitar o canal do Microsoft Teams.If you're using an existing registration, make sure you enable the Microsoft Teams channel.

Se você seguir um dos QuickStarts ou iniciar a partir de um dos exemplos disponíveis, será guiado através do registro do seu serviço Web.If you follow one of the quickstarts or start from one of the available samples you'll be guided through registering your web service. Se quiser registrar manualmente seu serviço, você terá três opções para fazer isso.If you want to manually register your service you have three options to do so. Se você optar por se registrar sem usar uma assinatura do Azure, não será possível aproveitar o fluxo de autenticação OAuth simplificado fornecido pela estrutura do bot.If you choose to register without using an Azure subscription you will not be able to take advantage of the simplified OAuth authentication flow provided by the Bot Framework. Você poderá migrar seu registro para o Azure após a criação.You will be able to migrate your registration to Azure after creation.

  • Se você tiver uma assinatura do Azure (ou quiser criar uma nova), poderá registrar o serviço Web manualmente usando o portal do Azure.If you have an Azure subscription (or want to create a new one), you can register your web service manually using the Azure Portal. Crie um recurso "registro de canais de bot".Create a "Bot Channels Registration" resource. Você pode escolher a camada de preços gratuita, uma vez que as mensagens do Microsoft Teams não contam com relação ao total de mensagens permitidas por mês.You can choose the free pricing tier, as messages from Microsoft Teams do not count towards your total allowable messages per month.
  • Se não quiser usar uma assinatura do Azure, você pode usar o portal de registro herdado.If you do not wish to use an Azure subscription, you can use the legacy registration portal.
  • O app Studio também pode ajudá-lo a registrar o serviço Web (bot).App Studio can also help you register your web service (bot). Os serviços Web registrados por meio do App Studio não são registrados no Azure.Web services registered through App Studio are not registered in Azure. Você pode usar o portal herdado para exibir, gerenciar e migrar seus registros.You can use the legacy portal to view, manage, and migrate your registrations.

Criar o manifesto do aplicativoCreate your app manifest

Você pode usar o aplicativo Studio para ajudá-lo a criar seu manifesto de aplicativo ou a criá-lo manualmente.You can either use App Studio to help you create your app manifest, or create it manually.

Criar seu manifesto de aplicativo usando o app StudioCreate your app manifest using App Studio

Você pode usar o aplicativo App Studio no cliente Microsoft Teams para ajudar a criar seu manifesto de aplicativo.You can use the App Studio app from within the Microsoft Teams client to help create your app manifest.

  1. No cliente do Teams, abra o aplicativo Studio no menu de estouro ... no trilho de navegação à esquerda.In the Teams client, open App Studio from the ... overflow menu on the left navigation rail. Se ainda não estiver instalado, você pode fazê-lo pesquisando.If it isn't already installed, you can do so by searching for it.
  2. Na guia Editor de manifesto , selecione criar um novo aplicativo (ou se você estiver adicionando uma extensão de mensagens a um aplicativo existente, poderá importar seu pacote de aplicativos)On the Manifest editor tab select Create a new app (or if you're adding a messaging extension to an existing app, you can import your app package)
  3. Adicione os detalhes do aplicativo (Confira definição de esquema de manifesto para obter descrições completas de cada campo).Add your app details (see manifest schema definition for full descriptions of each field).
  4. Na guia extensões de mensagens , clique no botão Configurar .On the Messaging extensions tab click the Setup button.
  5. Você pode criar um novo serviço Web (bot) para que sua extensão de mensagens seja usada, ou se já tiver registrado um SELECT/Add-lo aqui.You can either create a new web service (bot) for your messaging extension to use, or if you've already registered one select/add it here.
  6. Se necessário, atualize o endereço do ponto de extremidade do bot para apontar para o seu bot.If necessary, update your bot endpoint address to point to your bot. Ela deve ser similar a https://someplace.com/api/messages.It should look something like https://someplace.com/api/messages.
  7. O botão Adicionar na seção comando orientará você na adição de comandos à extensão do sistema de mensagens.The Add button in the Command section will guide you through adding commands to your messaging extension. Consulte a seção saiba mais para obter links para mais informações sobre como adicionar comandos.See the Learn more section for links to more information on adding commands. Lembre-se de que você pode definir até 10 comandos para sua extensão de mensagens.Remember you can define up to 10 commands for your messaging extension.
  8. A seção manipuladores de mensagens permite que você adicione um domínio para o qual as mensagens serão disparadas.The Message Handlers section allows you to add a domain that your messaging will trigger on. Confira link Unfurling para obter mais informações.See link unfurling for more information.

Na guia concluir => teste e distribuição , você pode baixar seu pacote de aplicativos (que inclui o manifesto do aplicativo, bem como seus ícones de aplicativo) ou instalar o pacote.From the Finish => Test and distribute tab you can Download your app package (which includes your app manifest as well as your app icons), or Install the package.

Criar o manifesto do aplicativo manualmenteCreate your app manifest manually

Como com bots e guias, você atualiza o manifesto do aplicativo de seu aplicativo para incluir as propriedades de extensão de mensagens.As with bots and tabs, you update the app manifest of your app to include the messaging extension properties. Essas propriedades controlam como sua extensão de mensagens aparece e se comporta no cliente Microsoft Teams.These properties govern how your messaging extension appears and behaves in the Microsoft Teams client. As extensões de mensagens têm suporte a partir da versão v 1.0 do manifesto.Messaging extensions are supported beginning with v1.0 of the manifest.

Declarar sua extensão de mensagensDeclare your messaging extension

Para adicionar uma extensão de mensagens, inclua uma nova estrutura JSON de nível superior em seu manifesto de aplicativo com a composeExtensions propriedade.To add a messaging extension, include a new top-level JSON structure in your app manifest with the composeExtensions property. Você cria uma única extensão de mensagens para seu aplicativo, com até 10 comandos.You create a single messaging extension for your app, with up to 10 commands.

Observação

O manifesto se refere a extensões de mensagens como composeExtensions .The manifest refers to messaging extensions as composeExtensions. Isso é para manter a compatibilidade com versões anteriores.This is to maintain backward compatibility.

A definição de extensão é um objeto que tem a seguinte estrutura:The extension definition is an object that has the following structure:

Nome da propriedadeProperty name FinalidadePurpose Obrigatório?Required?
botId O ID exclusivo do aplicativo Microsoft para o bot conforme registrado na estrutura do bot.The unique Microsoft app ID for the bot as registered with the Bot Framework. Isso deve ser normalmente o mesmo que a ID do aplicativo de suas equipes gerais.This should typically be the same as the ID for your overall Teams app. SimYes
canUpdateConfiguration Habilita o item de menu configurações .Enables Settings menu item. NãoNo
commands Matriz de comandos que esta extensão de mensagens suporta.Array of commands that this messaging extension supports. Você está limitado a 10 comandos.You are limited to 10 commands. SimYes

Definir seus comandosDefine your commands

Sua extensão de mensagens deve declarar um ou mais comandos, que definem onde seus usuários podem disparar sua extensão de mensagens e o tipo de interação.Your messaging extension should declare one or more commands, which define where your users can trigger your messaging extension, and the type of interaction. Consulte saiba mais para obter mais informações sobre os comandos de extensão de mensagens.See learn more for more information on messaging extension commands.

Exemplo de manifesto simplesSimple manifest example

O exemplo a seguir é um objeto de extensão de mensagem simples no manifesto de aplicativo com um comando de pesquisa.The example below is a simple messaging extension object in the app manifest with a search command. Esse não é o arquivo de manifesto completo do aplicativo, apenas a parte específica das extensões de mensagens.This is not the entire app manifest file, just the part specific to messaging extensions. Consulte esquema de manifesto de aplicativo para obter um exemplo completo.See app manifest schema for a complete example.

...
"composeExtensions": [
  {
    "botId": "abcd1234-1fc5-4d97-a142-35bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "searchCmd",
        "description": "Search you ToDo's",
        "title": "Search",
        "initialRun": true,
        "parameters": [
          {
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }
        ]
      }
    ]
  }
]
...

Adicionar seus manipuladores de mensagens de chamadaAdd your invoke message handlers

Quando seus usuários disparam sua extensão de mensagens, você precisará lidar com a mensagem de chamada inicial, coletar algumas informações do usuário e, em seguida, processar essas informações e responder de forma adequada.When your users trigger your messaging extension you'll need to handle the initial invoke message, collect some information from the user, then process that information and respond appropriately. Para fazer isso, primeiro você precisará decidir que tipo de comandos você deseja adicionar à sua extensão de mensagens e adicionar comandos de ação ou Adicionar um comando de pesquisa.To do that, you'll first need to decide what kind of commands you want to add to your messaging extension and either add an action commands or add a search commands.

Extensões de mensagens em reuniões do teamsMessaging extensions in Teams meetings

Após a reunião começar, os participantes do teams podem interagir diretamente com sua extensão de mensagens durante uma chamada ativa.Once a meeting begins, Teams participants can interact directly with your messaging extension during a live call. Considere o seguinte ao criar sua extensão de mensagens na reunião:Consider the following when building your in-meeting messaging extension:

  1. LocalizaçãoLocation. Sua extensão de mensagens pode ser invocada a partir da área de mensagem de composição, da caixa de comando ou @mentioned no chat da reunião.Your messaging extension can be invoked from the compose message area, the command box, or @mentioned in the meeting chat.

  2. Metadados.Metadata. Quando sua extensão de mensagens é invocada, ela pode identificar o usuário e o locatário de userId e tenantId .When your messaging extension is invoked it can identify the user and tenant from userId and tenantId. O meetingId pode ser encontrado como parte do channelData objeto.The meetingId can be found as part of the channelData object. Seu aplicativo pode usar o userId e o meetingId para a GetParticipant solicitação de API para recuperar funções de usuário.Your app can use the userId and meetingId for the GetParticipant API request to retrieve user roles.

  3. Tipo de comando.Command type. Se sua extensão de mensagem usa comandos baseados em ação, ela deve seguir as guias autenticação de logon único .If your message extension uses action-based commands, it should follow tabs Single Sign-On authentication.

  4. Experiência do usuário.User experience. Você deve determinar a experiência do usuário final para extensões de mensagens invocadas durante um chat de reunião.You should determine the intended the end-user experience for messaging extensions invoked during a meeting chat.

Próximas etapasNext steps

Saiba maisLearn more

Experimente em um QuickStart:Try it out in a quickstart:

Saiba mais sobre os conceitos de extensões de mensagens:Learn more about messaging extensions concepts: