Noções básicas sobre conversasConversation basics

Importante

Os exemplos de código nesta seção são baseados em 4,6 e versões posteriores do SDK da estrutura de bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando por documentação para versões anteriores, consulte a seção do SDK bots-v3 na pasta recursos da documentação.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Uma conversa é uma série de mensagens enviadas entre o bot e um ou mais usuários.A conversation is a series of messages sent between your bot and one or more users. Há três tipos de conversas (também chamadas de escopos) no Teams:There are three kinds of conversations (also called scopes) in Teams:

  • teams Também chamado de conversações de canal, visíveis para todos os membros do canal.teams Also called channel conversations, visible to all members of the channel.
  • personal Conversas entre bots e um único usuário.personal Conversations between bots and a single user.
  • groupChat Converse entre um bot e dois ou mais usuários.groupChat Chat between a bot and two or more users. O também habilita o bot em conversas de reunião.Also enables your bot in meeting chats.

Um bot se comporta de forma ligeiramente diferente dependendo do tipo de conversa envolvido em:A bot behaves slightly differently depending on what kind of conversation it is involved in:

  • Os bots nas conversas de chat de canal e de grupo exigem que o usuário @ mencione o bot para chamá-lo em um canal.Bots in channel and group chat conversations require the user to @ mention the bot to invoke it in a channel.
  • Os bots em uma conversa de um-para-um não exigem um @ menção.Bots in a one-to-one conversation do not require an @ mention. Todas as mensagens enviadas pelo usuário serão encaminhadas para o bot.All messages sent by the user will be routed to your bot.

Para habilitar o bot em um escopo específico, adicione esse escopo ao manifesto do aplicativo.To enable your bot in a particular scope, add that scope to your app manifest.

AtividadesActivities

Cada mensagem é um Activity objeto do tipo messageType: message .Each message is an Activity object of type messageType: message. Quando um usuário envia uma mensagem, o Teams posta a mensagem no bot; especificamente, ele envia um objeto JSON para o ponto de extremidade de mensagem de seu bot.When a user sends a message, Teams posts the message to your bot; specifically, it sends a JSON object to your bot's messaging endpoint. O bot examina a mensagem para determinar seu tipo e responde de acordo.Your bot examines the message to determine its type and responds accordingly.

A conversa básica é manipulada por meio do conector da estrutura de bot, uma única API REST para permitir que seu bot se comunique com o Teams e outros canais.Basic conversation is handled through the Bot Framework Connector, a single REST API to enable your bot to communicate with Teams and other channels. O SDK do bot Builder fornece acesso fácil a essa API, funcionalidade adicional para gerenciar o fluxo e o estado da conversa e maneiras simples de incorporar serviços cognitivas, como o processamento de idioma natural (NLP).The Bot Builder SDK provides easy access to this API, additional functionality to manage conversation flow and state, and simple ways to incorporate cognitive services such as natural language processing (NLP).

Receber uma mensagemReceive a message

Para receber uma mensagem de texto, use a Text Propriedade do Activity objeto.To receive a text message, use the Text property of the Activity object. No manipulador de atividade do bot, use o objeto de contexto Turn Activity para ler uma única solicitação de mensagem.In the bot's activity handler, use the turn context object's Activity to read a single message request.

O código a seguir mostra um exemplo.The code below shows an example.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

Enviar uma mensagemSend a message

Para enviar uma mensagem de texto, especifique a cadeia de caracteres que você deseja enviar como atividade.To send a text message, specify the string you want to send as the activity. Nos manipuladores de atividade do bot, use o método Turn Context Object SendActivityAsync para enviar uma resposta de mensagem única.In the bot's activity handlers, use the turn context object's SendActivityAsync method to send a single message response. Você também pode usar o método do objeto SendActivitiesAsync para enviar várias respostas ao mesmo tempo.You can also use the object's SendActivitiesAsync method to send multiple responses at once. O código a seguir mostra um exemplo de envio de uma mensagem quando alguém é adicionado a uma conversaThe code below shows an example of sending a message when someone is added to a conversation

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Dados de canal do teamsTeams channel data

O channelData objeto contém informações específicas de equipes e é a fonte definitiva para IDs de canal e equipe.The channelData object contains Teams-specific information and is the definitive source for team and channel IDs. Talvez seja necessário armazenar em cache e usar essas IDs como chaves para armazenamento local.You may need to cache and use these ids as keys for local storage. O TeamsActivityHandler no SDK normalmente retira informações importantes do channelData objeto para torná-lo mais facilmente acessível, no entanto, você sempre pode acessar as informações originais do turnContext objeto.The TeamsActivityHandler in the SDK will typically pull out important information from the channelData object to make it more easily accessible, however you can always access the original information from the turnContext object.

O channelData objeto não está incluído nas mensagens em conversas pessoais, pois elas ocorrem fora de qualquer canal.The channelData object is not included in messages in personal conversations since these take place outside of any channel.

Um objeto channelData típico em uma atividade enviada ao seu bot contém as seguintes informações:A typical channelData object in an activity sent to your bot contains the following information:

  • eventType Tipo de evento Teams; aprovado apenas em casos de eventos de modificação de canaleventType Teams event type; passed only in cases of channel modification events
  • tenant.id ID de locatário do Azure Active Directory; aprovado em todos os contextostenant.id Azure Active Directory tenant ID; passed in all contexts
  • team Aprovado apenas em contextos de canal, não no chat pessoal.team Passed only in channel contexts, not in personal chat.
  • channel É passado apenas em contextos de canal quando o bot é mencionado ou para eventos em canais no Teams onde o bot foi adicionadochannel Passed only in channel contexts when the bot is mentioned or for events in channels in teams where the bot has been added
  • channelData.teamsTeamId Preterido.channelData.teamsTeamId Deprecated. Essa propriedade é incluída apenas para compatibilidade com versões anteriores.This property is included only for backwards compatibility.
  • channelData.teamsChannelId Preterido.channelData.teamsChannelId Deprecated. Essa propriedade é incluída apenas para compatibilidade com versões anteriores.This property is included only for backwards compatibility.

Exemplo do objeto channelData (evento channelCreated)Example channelData object (channelCreated event)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Conteúdo da mensagemMessage content

Seu bot pode enviar Rich Text, imagens e cartões.Your bot can send rich text, pictures, and cards. Os usuários podem enviar Rich Text e imagens para o bot.Users can send rich text and pictures to your bot.

FormatarFormat De usuário para botFrom user to bot De bot para usuárioFrom bot to user ObservaçõesNotes
Rich text Rich text
ImagensPictures Máximo de 1024 × 1024 e 1 MB no formato PNG, JPEG ou GIF; GIF animado não é suportadoMaximum 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF are not supported
CartõesCards Consulte a referência de cartões de equipe para cartões suportadosSee the Teams Card Reference for supported cards
EmojisEmojis No momento, o Microsoft Teams oferece suporte a emojis via UTF-16 (como U + 1F600 para Grinning face)Teams currently supports emojis via UTF-16 (such as U+1F600 for grinning face)

Adicionando notificações à sua mensagemAdding notifications to your message

As notificações alertam os usuários sobre novas tarefas, mencionadas e comentários relacionados ao que estão trabalhando ou precisam examinar inserindo um aviso no feed de atividades.Notifications alert users about new tasks, mentions and comments related to what they are working on, or need to look at by inserting a notice into their Activity Feed. Você pode definir notificações para que disparem da mensagem do bot, definindo a TeamsChannelData Propriedade Objects Notification.Alert como true.You can set notifications to trigger from your bot message by setting the TeamsChannelData objects Notification.Alert property to true. Se uma notificação será disparada, em última análise dependerá das configurações de equipe do usuário individual e você não poderá ignorar essas configurações programaticamente.Whether or not a notification is raised will ultimately depend on the individual user's Teams settings and you cannot programmatically override these settings. O tipo de notificação será um cabeçalho ou uma faixa e um email.The type of notification will be either a banner or both a banner and an email.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  await turnContext.SendActivityAsync(message);
}

Mensagens de imagemPicture messages

As imagens são enviadas adicionando anexos a uma mensagem.Pictures are sent by adding attachments to a message. Você pode encontrar mais informações sobre anexos na documentação da estrutura do bot.You can find more information on attachments in the Bot Framework documentation.

As imagens podem ser no máximo 1024 × 1024 e 1 MB no formato PNG, JPEG ou GIF; GIF animado não é suportado.Pictures can be at most 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF is not supported.

Recomendamos que você especifique a altura e a largura de cada imagem usando XML.We recommend that you specify the height and width of each image by using XML. Se você usar redução, o tamanho da imagem padrão será 256 × 256.If you use Markdown, the image size defaults to 256×256. Por exemplo:For example:

  • Use <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>Use - <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • Não use- ![Duck on a rock](http://aka.ms/Fo983c)Don't use - ![Duck on a rock](http://aka.ms/Fo983c)

Próximas etapasNext steps