Mensagens em conversas de botMessages in bot conversations

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

As conversas básicas são manipuladas por meio do conector da Estrutura do Bot, uma única API REST.Basic conversations are handled through the Bot Framework connector, a single REST API. Essa API permite que seu bot se comunique com o Teams e outros canais.This API enables your bot to communicate with Teams and other channels. O SDK do Construtor de Bots fornece os seguintes recursos:The Bot Builder SDK provides the following features:

  • Acesso fácil ao conector da Estrutura de Bot.Easy access to the Bot Framework connector.
  • Funcionalidade adicional para gerenciar o fluxo e o estado da conversa.Additional functionality to manage conversation flow and state.
  • Maneiras simples de incorporar serviços cognitivos, como o processamento de linguagem natural (NLP).Simple ways to incorporate cognitive services, such as natural language processing (NLP).

Seu bot recebe mensagens do Teams usando a propriedade e envia respostas de mensagem única ou Text múltipla aos usuários.Your bot receives messages from Teams using the Text property and it sends single or multiple message responses to the users.

Receber uma mensagemReceive a message

Para receber uma mensagem de texto, use a propriedade Text do objeto Activity.To receive a text message, use the Text property of the Activity object. No manipulador de atividades do bot, alterne o contexto do objeto 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 de recebimento de uma mensagem:The following code shows an example of receiving a message:

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 a atividade.To send a text message, specify the string you want to send as the activity. No manipulador de atividades do bot, use o método do objeto turn context SendActivityAsync para enviar uma única resposta de mensagem.In the bot's activity handler, use the turn context object's SendActivityAsync method to send a single message response. Use o método do SendActivitiesAsync objeto para enviar várias respostas ao mesmo tempo.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 um usuário é adicionado a uma conversa:The following code shows an example of sending a message when a user 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);
}

Observação

A divisão de mensagens ocorre quando uma mensagem de texto e um anexo são enviados na mesma carga de atividade.Message splitting occurs when a text message and an attachment are sent in the same activity payload. Essa atividade é dividida em atividades separadas pelo Microsoft Teams, uma com apenas uma mensagem de texto e outra com um anexo.This activity is split into separate activities by Microsoft Teams, one with just a text message and the other with an attachment. À medida que a atividade é dividida, você não recebe a ID da mensagem em resposta, que é usada para atualizar ou excluir a mensagem proativamente.As the activity is split, you do not receive the message ID in response, which is used to update or delete the message proactively. É recomendável enviar atividades separadas em vez de depender da divisão de mensagens.It is recommended to send separate activities instead of depending on message splitting.

As mensagens enviadas entre usuários e bots incluem dados de canal interno dentro da mensagem.Messages sent between users and bots include internal channel data within the message. Esses dados permitem que o bot se comunique corretamente nesse canal.This data allows the bot to communicate properly on that channel. O SDK do Construtor de Bots permite modificar a estrutura de mensagens.The Bot Builder SDK allows you to modify the message structure.

Dados do canal do TeamsTeams channel data

O channelData objeto contém informações específicas do Teams e é uma fonte definitiva para IDs de equipe e canal.The channelData object contains Teams-specific information and is a definitive source for team and channel IDs. Opcionalmente, você pode armazenar em cache e usar essas IDs como chaves para armazenamento local.Optionally, you can cache and use these IDs as keys for local storage. O no SDK retira informações importantes do objeto para TeamsActivityHandler channelData torná-lo facilmente acessível.The TeamsActivityHandler in the SDK pulls out important information from the channelData object to make it easily accessible. No entanto, você sempre pode acessar os dados originais do turnContext objeto.However, you can always access the original data from the turnContext object.

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

Um objeto channelData típico em uma atividade enviada ao 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 do Teams passado somente em casos de eventos de modificação de canal.eventType: Teams event type passed only in cases of channel modification events.
  • tenant.id: ID de locatário do Azure Active Directory passada em todos os contextos.tenant.id: Azure Active Directory tenant ID passed in all contexts.
  • team: Passado somente em contextos de canal, não em chat pessoal.team: Passed only in channel contexts, not in personal chat.
  • channel: Passado somente em contextos de canal quando o bot é mencionado ou para eventos em canais em equipes onde o bot foi adicionado.channel: 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 só é incluída para compatibilidade com compatibilidade.This property is only included for backward compatibility.
  • channelData.teamsChannelId: Preterido.channelData.teamsChannelId: Deprecated. Essa propriedade só é incluída para compatibilidade com compatibilidade.This property is only included for backward compatibility.

Exemplo de objeto channelData ou evento channelCreatedExample channelData object or channelCreated event

O código a seguir mostra um exemplo do objeto channelData:The following code shows an example of channelData object:

"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"
    }
}

As mensagens recebidas ou enviadas ao bot podem incluir diferentes tipos de conteúdo de mensagem.Messages received from or sent to your bot can include different types of message content.

Conteúdo da mensagemMessage content

FormatarFormat De usuário para botFrom user to bot De bot para usuárioFrom bot to user ObservaçõesNotes
Rich text Rich text Seu bot pode enviar rich text, pictures e cards.Your bot can send rich text, pictures, and cards. Os usuários podem enviar texto e imagens rich para seu bot.Users can send rich text and pictures to your bot.
ImagensPictures Máximo de 1024×1024 e 1 MB no formato PNG, JPEG ou GIF.Maximum 1024×1024 and 1 MB in PNG, JPEG, or GIF format. Gif animado não é suportado.Animated GIF is not supported.
CartõesCards Consulte a referência de cartão do Teams para cartões com suporte.See the Teams card reference for supported cards.
EmojisEmojis Atualmente, o Teams dá suporte a emojis por meio do UTF-16, como U+1F600 para face de riso.Teams currently supports emojis through UTF-16, such as U+1F600 for grinning face.

Você também pode adicionar notificações à sua mensagem usando a Notification.Alert propriedade.You can also add notifications to your message using the Notification.Alert property.

Notificações à sua mensagemNotifications to your message

As notificações alertam os usuários sobre novas tarefas, menções e comentários.Notifications alert users about new tasks, mentions, and comments. Esses alertas estão relacionados ao que os usuários estão trabalhando ou ao que devem observar inserindo um aviso no feed de atividades.These alerts are related to what users are working on or what they must look at by inserting a notice into their activity feed. Para que as notificações acionem de sua mensagem bot, de definir a propriedade TeamsChannelData objects Notification.Alert como true.For notifications to trigger from your bot message, set the TeamsChannelData objects Notification.Alert property to true. A ativação ou não de uma notificação depende das configurações do Teams do usuário individual e você não pode substituir essas configurações.Whether or not a notification is raised depends on the individual user's Teams settings and you cannot override these settings. O tipo de notificação é um banner ou um banner e um email.The notification type is either a banner, or both a banner and an email.

Observação

O campo Resumo exibe qualquer texto do usuário como uma mensagem de notificação no feed.The Summary field displays any text from the user as a notification message in the feed.

O código a seguir mostra um exemplo de adição de notificações à sua mensagem:The following code shows an example of adding notifications to your message:

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);
}

Para aprimorar sua mensagem, você pode incluir imagens como anexos a essa mensagem.To enhance your message, you can include pictures as attachments to that message.

Mensagens de imagemPicture messages

As imagens são enviadas adicionando anexos a uma mensagem.Pictures are sent by adding attachments to a message. Para obter mais informações sobre anexos, consulte Documentação da Estrutura de Bots.For more information on attachments, see Bot Framework documentation.

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

Especifique a altura e a largura de cada imagem usando XML.Specify the height and width of each image by using XML. Na marcação, o tamanho da imagem é padrão para 256×256.In 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) .Do not use: ![Duck on a rock](http://aka.ms/Fo983c).

Um bot de conversa pode incluir Cartões Adaptáveis que simplificam fluxos de trabalho de negócios.A conversational bot can include Adaptive Cards that simplify business workflows. Os Cartões Adaptáveis oferecem texto, fala, imagens, botões e campos de entrada personalizáveis.Adaptive Cards offer rich customizable text, speech, images, buttons, and input fields.

Cartões AdaptáveisAdaptive Cards

Cartões adaptáveis podem ser autorados em um bot e mostrados em vários aplicativos, como o Teams, seu site e assim por diante.Adaptive Cards can be authored in a bot and shown in multiple apps such as Teams, your website, and so on. Para obter mais informações, consulte Adaptive Cards.For more information, see Adaptive Cards.

O código a seguir mostra um exemplo de envio de um cartão adaptável simples:The following code shows an example of sending a simple Adaptive Card:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Para saber mais sobre cartões e cartões em bots, consulte documentação de cartões.To know more about cards and cards in bots, see cards documentation.

Respostas de código de statusStatus code responses

A seguir estão os códigos de status e seus valores de código de erro e mensagem:Following are the status codes and their error code and message values:

Código de statusStatus code Valores de código de erro e mensagemError code and message values DescriçãoDescription
403403 Código: ConversationBlockedByUserCode: ConversationBlockedByUser
Mensagem: o usuário bloqueou a conversa com o bot.Message: User blocked the conversation with the bot.
O usuário bloqueou o bot no chat 1:1 ou em um canal por meio de configurações de moderação.User blocked the bot in 1:1 chat or a channel through moderation settings.
403403 Código: BotNotInConversationRosterCode: BotNotInConversationRoster
Mensagem: o bot não faz parte da lista de conversas.Message: The bot is not part of the conversation roster.
O bot não faz parte da conversa.The bot is not part of the conversation.
403403 Código: BotDisabledByAdminCode: BotDisabledByAdmin
Mensagem: o administrador do locatário desabilitou esse bot.Message: The tenant admin disabled this bot.
O locatário bloqueou o bot.Tenant blocked the bot.
401401 Código: BotNotRegisteredCode: BotNotRegistered
Mensagem: nenhum registro encontrado para este bot.Message: No registration found for this bot.
O registro desse bot não foi encontrado.The registration for this bot was not found.
412412 Código: PreconditionFailedCode: PreconditionFailed
Mensagem: Falha na pré-condição, tente novamente.Message: Precondition failed, please try again.
Uma pré-condição falhou em uma de nossas dependências devido a várias operações simultâneas na mesma conversa.A precondition failed on one of our dependencies due to multiple concurrent operations on the same conversation.
404404 Código: ConversationNotFoundCode: ConversationNotFound
Mensagem: Conversa não encontrada.Message: Conversation not found.
A conversa não foi encontrada.The conversation was not found.
413413 Código: MessageSizeTooBigCode: MessageSizeTooBig
Mensagem: tamanho da mensagem muito grande.Message: Message size too large.
O tamanho da solicitação de entrada era muito grande.The size on the incoming request was too large.
429429 Código: ThrottledCode: Throttled
Mensagem: solicitações demais.Message: Too many requests. Também retorna quando repetir depois.Also returns when to retry after.
Muitas solicitações foram enviadas pelo bot.Too many requests were sent by the bot. Para obter mais informações, consulte limite de taxa.For more information, see rate limit.

Exemplo de códigoCode sample

Exemplo de nomeSample name DescriçãoDescription . NETCore.NETCore Node.jsNode.js PythonPython
Bot de conversas do TeamsTeams conversation bot Manipulação de eventos de mensagens e conversas.Messaging and conversation event handling. ViewView ViewView ViewView

Confira tambémSee also

Próxima etapaNext step