Mensagens em conversas de bot
Cada mensagem em uma conversa é um Activity objeto do tipo messageType: message. Quando um usuário envia uma mensagem, o Microsoft Teams posta a atividade de mensagem no bot. O Teams envia um objeto JSON para o ponto de extremidade de mensagens do bot e o Teams permite apenas um ponto de extremidade para mensagens. Seu bot examina a mensagem para determinar seu tipo e responde adequadamente.
As conversas básicas são tratadas por meio do conector do Bot Framework, uma única API REST. Essa API permite que seu bot se comunique com o Teams e outros canais. O SDK do Construtor de Bots fornece os seguintes recursos:
- Acesso fácil ao conector do Bot Framework.
- Funcionalidade para gerenciar o fluxo e o estado da conversa.
- Maneiras simples de incorporar serviços cognitivos, como o NLP (processamento de linguagem natural).
O bot recebe mensagens do Teams usando a Text propriedade e envia respostas de mensagens individuais ou múltiplas para os usuários.
Para obter mais informações, consulte atribuição do usuário para mensagens de bot.
A tabela a seguir lista a atividade que seu bot pode receber e agir em:
| Tipo | Objeto payload | Escopo |
|---|---|---|
| Receber uma atividade de mensagem | Atividade de mensagem | Todos |
| Receber atividade de mensagem de edição | Atividade de edição de mensagem | Todos |
| Receber atividade de mensagem undelete | Atividade undelete de mensagem | Todos |
| Receber atividade de mensagem de exclusão suave | Atividade de exclusão suave da mensagem | Todos |
Receber uma atividade de mensagem
Para receber uma mensagem de texto, use a Text propriedade de um Activity objeto. No manipulador de atividades do bot, alterne o contexto do objeto Activity para ler uma única solicitação de mensagem.
O código a seguir mostra um exemplo de recebimento de uma atividade de mensagem:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}
Receber um recibo de leitura
A configuração De leitura de recibos no Teams permite que o remetente de uma mensagem de chat seja notificado quando sua mensagem foi lida pelo destinatário em chats individuais e em grupo. Depois que o destinatário lê a mensagem, o Visto
aparece ao lado da mensagem. Você também tem a opção de configurar o bot para receber eventos de recebimento de leitura por meio da configuração De leitura de recibos . O evento de recebimento de leitura ajuda você a aprimorar a experiência do usuário das seguintes maneiras:
Você pode configurar o bot para enviar uma mensagem de acompanhamento se o usuário do aplicativo não tiver lido a mensagem no chat pessoal.
Você pode criar um loop de comentários usando recibos de leitura para ajustar a experiência do bot.
Observação
- Os recibos de leitura têm suporte apenas em cenários de chat do usuário para bot.
- Os recibos de leitura para bots não dão suporte a escopos de chat de equipe, canal e grupo.
- Se um administrador de locatário ou usuário desabilitar a configuração De recibos de leitura , o bot não receberá o evento de recebimento de leitura.
Para receber eventos de recibos de leitura para o bot, verifique o seguinte:
- Adicione a permissão RSC
ChatMessageReadReceipt.Read.Chatno manifesto do aplicativo, da seguinte maneira:
"webApplicationInfo": {
"id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
"resource": ""
},
"authorization": {
"permissions": {
"orgwide": [],
"resourceSpecific": [
{
"name": "ChatMessageReadReceipt.Read.Chat",
"type": "Application"
}
]
}
}
Você também pode adicionar permissões RSC por meio de API do Graph. Para obter mais informações, confira consentedPermissionSet.
Substitua o método
OnTeamsReadReceiptAsynccomIsMessageReado manipulador.O
IsMessageReadmétodo auxiliar é útil para determinar se a mensagem é lida pelos destinatários. Se ocompareMessageIdfor menor ou igual aoLastReadMessageId, a mensagem será lida. Substitua oOnTeamsReadReceiptAsyncmétodo para receber recibos de leitura comIsMessageReado método auxiliar:protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) { var lastReadMessageId = readReceiptInfo.LastReadMessageId; if (IsMessageRead("{id of the message that you care}", LastReadMessageId)) { await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken); } }A seguir está um exemplo de solicitação de evento de recibos de leitura que um bot recebe:
{ "name": "application/vnd.microsoft.readReceipt", "type": "event", "timestamp": "2023-08-16T17:23:11.1366686Z", "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007", "channelId": "msteams", "serviceUrl": "https://smba.trafficmanager.net/amer/", "from": { "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw", "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5" }, "conversation": { "conversationType": "personal", "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f", "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z" }, "recipient": { "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb", "name": "Test Bot" }, "channelData": { "tenant": { "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f" } }, "value": { "lastReadMessageId": "1692206589131" } }A configuração do administrador de recibo de leitura ou a configuração do usuário está ativada para que o locatário do bot receba os eventos de recebimento de leitura. O administrador do locatário ou o usuário devem habilitar ou desabilitar a configuração de recebimento de leitura.
Depois que o bot é habilitado em um cenário de chat do usuário para bot, o bot recebe prontamente um evento de recebimento de leitura quando o usuário lê a mensagem do bot. Você pode acompanhar o envolvimento do usuário contando o número de eventos e também pode enviar uma mensagem de reconhecimento de contexto.
Enviar uma mensagem
Para enviar uma mensagem de texto, especifique a cadeia de caracteres que você deseja enviar como uma atividade. No manipulador de atividades do bot, use o método do SendActivityAsync objeto de contexto de turno para enviar uma única resposta de mensagem. Use o método do SendActivitiesAsync objeto para enviar várias respostas.
O código a seguir mostra um exemplo de envio de uma mensagem quando um usuário é adicionado a uma conversa:
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
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. O Teams divide essa atividade em duas atividades separadas, uma com uma mensagem de texto e outra com um anexo. À medida que a atividade é dividida, você não recebe a ID da mensagem em resposta, que é usada para atualizar ou excluir a mensagem proativamente. É recomendável enviar atividades separadas em vez de depender da divisão de mensagens.
- As mensagens enviadas podem ser localizadas para fornecer personalização. Para obter mais informações, confira localizar seu aplicativo.
As mensagens enviadas entre usuários e bots incluem dados internos do canal na mensagem. Esses dados permitem que o bot se comunique corretamente nesse canal. O SDK do Construtor de Bots permite que você modifique a estrutura da mensagem.
Obter atividade de mensagem de edição
Quando você edita uma mensagem, o bot recebe uma notificação da atividade de edição da mensagem.
Para obter uma notificação de atividade de mensagem de edição em um bot, você pode substituir o OnTeamsMessageEditAsync manipulador.
A seguir está um exemplo de uma notificação de atividade de edição de mensagem usando OnTeamsMessageEditAsync quando uma mensagem enviada é editada:
protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is updated");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Obter atividade de mensagem undelete
Quando você desdelete uma mensagem, o bot recebe uma notificação da atividade de mensagem undelete.
Para obter uma notificação de atividade de mensagem não-delete em um bot, você pode substituir o OnTeamsMessageUndeleteAsync manipulador.
Veja a seguir um exemplo de uma notificação de atividade de mensagem nãodelete usando OnTeamsMessageUndeleteAsync quando uma mensagem excluída é restaurada:
protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is undeleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Obter atividade de mensagem de exclusão suave
Quando você exclui uma mensagem, o bot recebe uma notificação da atividade de mensagem de exclusão suave.
Para obter uma notificação de atividade de mensagem de exclusão suave em um bot, você pode substituir o OnTeamsMessageSoftDeleteAsync manipulador.
A seguir está um exemplo de uma notificação de atividade de mensagem de exclusão suave usando OnTeamsMessageSoftDeleteAsync quando uma mensagem é excluída:
protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is soft deleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Enviar ações sugeridas
As ações sugeridas permitem que o bot apresente botões que o usuário pode selecionar para fornecer entrada. As ações sugeridas aprimoram a experiência do usuário, permitindo que o usuário responda a uma pergunta ou faça uma escolha com a seleção de um botão, em vez de digitar uma resposta com um teclado. Quando o usuário seleciona um botão, ele permanece visível e acessível nos cartões avançados, mas não para as ações sugeridas. Isso impede que o usuário escolha botões obsoletos em uma conversa.
Para adicionar ações sugeridas a uma mensagem, defina a suggestedActions propriedade de um objeto de atividade para especificar a lista de objetos de ação cartão que representam os botões a serem apresentados ao usuário. Para obter mais informações, confira sugestedActions.
Veja a seguir um exemplo de implementação e experiência de ações sugeridas:
"suggestedActions": {
"actions": [
{
"type": "imBack",
"title": "Action 1",
"value": "Action 1"
},
{
"type": "imBack",
"title": "Action 2",
"value": "Action 2"
}
],
"to": [<list of recepientIds>]
}
O seguinte ilustra um exemplo de ações sugeridas:
Observação
SuggestedActionssó há suporte para bots de chat individuais com mensagens baseadas em texto e Cartões Adaptáveis.SuggestedActionsnão há suporte para bots de chat com anexos para qualquer tipo de conversa.imBacké o único tipo de ação com suporte e o Teams exibe até três ações sugeridas.
Dados do canal do Teams
O channelData objeto contém informações específicas do Teams e é uma fonte definitiva para IDs de equipe e canal. Opcionalmente, você pode armazenar em cache e usar essas IDs como chaves para armazenamento local. O TeamsActivityHandler no SDK retira informações importantes do channelData objeto para torná-lo acessível. No entanto, você sempre pode acessar os dados originais do turnContext objeto.
O channelData objeto não está incluído em mensagens em conversas pessoais, pois elas ocorrem fora de um canal.
Um objeto típico channelData em uma atividade enviada ao bot contém as seguintes informações:
eventType: o tipo de evento teams passou apenas em casos de eventos de modificação de canal.tenant.id: Microsoft Entra ID do locatário passada em todos os contextos.team: passado somente em contextos de canal, não em chat pessoal.id: GUID para o canal.name: nome da equipe passado apenas em casos de eventos de renomeação de equipe.
channel: passado somente em contextos de canal, quando o bot é mencionado ou para eventos em canais em equipes, em que o bot é adicionado.id: GUID para o canal.name: nome do canal passado somente em casos de eventos de modificação de canal.
channelData.teamsTeamId:Preterido. Essa propriedade só está incluída para compatibilidade com versões anteriores.channelData.teamsChannelId:Preterido. Essa propriedade só está incluída para compatibilidade com versões anteriores.
Exemplo de objeto channelData
O código a seguir mostra um exemplo de objeto channelData (evento channelCreated):
"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 mensagem
As mensagens recebidas ou enviadas para o bot podem incluir diferentes tipos de conteúdo de mensagem.
| Formatar | Do usuário para o bot | Do bot para o usuário | Observações |
|---|---|---|---|
| Rich text | ✔️ | ✔️ | Seu bot pode enviar rich text, imagens e cartões. Os usuários podem enviar rich text e imagens para seu bot. |
| Imagens | ✔️ | ✔️ | Máximo de 1024 × 1024 pixels e 1 MB no formato PNG, JPEG ou GIF. Não dá suporte ao GIF animado. |
| Cartões | ❌ | ✔️ | Consulte Referência de cartão do Teams para cartões com suporte. |
| Emojis | ✔️ | ✔️ | Atualmente, o Teams dá suporte a emojis por meio do UTF-16, como U+1F600 para rosto sorridente. |
Mensagens de imagem
Para aprimorar sua mensagem, você pode incluir imagens como anexos a essa mensagem. Para obter mais informações sobre anexos, consulte adicionar anexos de mídia às mensagens.
As imagens podem ter no máximo 1.024 × 1024 pixels e 1 MB no formato PNG, JPEG ou GIF. Não há suporte para GIF animado.
Especifique a altura e a largura de cada imagem usando XML. No Markdown, o tamanho da imagem é padrão para 256×256. Por exemplo:
- Use:
<img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>. - Não use:
.
Um bot de conversa pode incluir cartões adaptáveis que simplificam os fluxos de trabalho de negócios. Cartões Adaptáveis oferecem texto, fala, imagens, botões e campos de entrada personalizáveis avançados.
Cartões Adaptáveis
Cartões Adaptáveis podem ser criados em um bot e mostrados em vários aplicativos, como o Teams, seu site e assim por diante. Para obter mais informações, Cartões Adaptáveis.
O código a seguir mostra um exemplo de envio de um cartão adaptável simples:
{
"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"
}
]
}
Adicionar notificações à sua mensagem
Há duas maneiras de enviar uma notificação do seu aplicativo:
- Definindo a
Notification.Alertpropriedade na mensagem do bot. - Enviando uma notificação do feed de atividades usando o API do Graph.
Você pode adicionar notificações à sua mensagem usando a Notification.Alert propriedade. As notificações alertam os usuários para um evento em seu aplicativo, como novas tarefas, menções ou comentários. Esses alertas estão relacionados ao que os usuários estão trabalhando ou ao que devem examinar inserindo um aviso no feed de atividades. Para que as notificações acionem de sua mensagem de bot, defina a TeamsChannelData propriedade objetos Notification.Alert como true. Se uma notificação for gerada depende das configurações do Teams do usuário individual, e você não poderá substituir essas configurações.
Se você quiser gerar uma notificação arbitrária sem enviar uma mensagem ao usuário, poderá usar o API do Graph. Para obter mais informações, confira como enviar notificações de feed de atividades usando API do Graph junto com as práticas recomendadas.
Observação
O campo Resumo exibe qualquer texto do usuário como uma mensagem de notificação no feed.
O código a seguir mostra um exemplo de adição de notificações à sua mensagem:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Returns a simple text message.
var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
message.TeamsNotifyUser();
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(message);
}
Códigos de status de APIs conversacionais de bot
Certifique-se de lidar com esses erros adequadamente em seu aplicativo do Teams. A tabela a seguir lista os códigos de erro e as descrições nas quais os erros são gerados:
| Código de status | Códigos de erro e valores de mensagem | Descrição | Repita a solicitação | Ação do desenvolvedor |
|---|---|---|---|---|
| 400 | Código: Bad Argument Mensagem: *cenário específico |
Carga de solicitação inválida fornecida pelo bot. Consulte mensagem de erro para obter detalhes específicos. | Não | Reavaliar a carga de solicitação para erros. Verifique a mensagem de erro retornada para obter detalhes. |
| 401 | Código: BotNotRegistered Mensagem: nenhum registro encontrado para este bot. |
O registro desse bot não foi encontrado. | Não | Verifique a ID do bot e a senha. Verifique se a ID do bot (Microsoft Entra ID) está registrada no Portal do Desenvolvedor do Teams ou por meio do registro do canal de bot do Azure no Azure com o canal 'Teams' habilitado. |
| 403 | Código: BotDisabledByAdmin Mensagem: o administrador do locatário desabilitou este bot |
O administrador do locatário bloqueou as interações entre o usuário e o aplicativo bot. O administrador do locatário precisa permitir o aplicativo para o usuário dentro das políticas de aplicativo. Para obter mais informações, consulte políticas de aplicativo. | Não | Pare de postar na conversa até que a interação com o bot seja iniciada explicitamente por um usuário na conversa indicando que o bot não está mais bloqueado. |
| 403 | Código: BotNotInConversationRoster Mensagem: o bot não faz parte da lista de conversas. |
O bot não faz parte da conversa. O aplicativo precisa ser reinstalado na conversa. | Não | Antes de tentar enviar outra solicitação de conversa, aguarde por um installationUpdate evento, o que indica que o bot foi adicionado novamente. |
| 403 | Código: ConversationBlockedByUser Mensagem: o usuário bloqueou a conversa com o bot. |
O usuário bloqueou o bot no chat pessoal ou em um canal por meio de configurações de moderação. | Não | Exclua a conversa do cache. Pare de tentar postar em conversas até que a interação com o bot seja iniciada explicitamente por um usuário na conversa, indicando que o bot não está mais bloqueado. |
| 403 | Código: ForbiddenOperationException Mensagem: o bot não está instalado no escopo pessoal do usuário |
A mensagem proativa é enviada por um bot, que não está instalado em um escopo pessoal. | Não | Antes de tentar enviar outra solicitação de conversa, instale o aplicativo no escopo pessoal. |
| 403 | Código: InvalidBotApiHost Mensagem: host de api de bot inválido. Para locatários do GCC, chame https://smba.infra.gcc.teams.microsoft.com. |
O bot chamou o ponto de extremidade da API pública para uma conversa que pertence a um locatário do GCC. | Não | Atualize a URL de serviço para https://smba.infra.gcc.teams.microsoft.com a conversa e tente novamente a solicitação. |
| 403 | Código: NotEnoughPermissions Mensagem: *cenário específico |
O bot não tem permissões necessárias para executar a ação solicitada. | Não | Determine a ação necessária da mensagem de erro. |
| 404 | Código: ActivityNotFoundInConversation Mensagem: conversa não encontrada. |
A ID da mensagem fornecida não pôde ser encontrada na conversa. A mensagem não existe ou é excluída. | Não | Verifique se a ID da mensagem enviada é um valor esperado. Remova a ID se ela estiver armazenada em cache. |
| 404 | Código: ConversationNotFound Mensagem: conversa não encontrada. |
A conversa não foi encontrada, pois ela não existe ou é excluída. | Não | Verifique se a ID da conversa enviada é um valor esperado. Remova a ID se ela estiver armazenada em cache. |
| 412 | Código: PreconditionFailed Mensagem: falha na pré-condição, tente novamente. |
Falha na pré-condição em uma de nossas dependências devido a várias operações simultâneas na mesma conversa. | Sim | Tente novamente com backoff exponencial. |
| 413 | Código: MessageSizeTooBig Mensagem: tamanho da mensagem muito grande. |
O tamanho da solicitação de entrada era muito grande. Para obter mais informações, consulte formatar suas mensagens de bot. | Não | Reduza o tamanho da carga. |
| 429 | Código: Throttled Mensagem: muitas solicitações. Também retorna quando tentar novamente depois. |
Muitas solicitações enviadas pelo bot. Para obter mais informações, consulte limite de taxa. | Sim | Tente novamente usar Retry-After o cabeçalho para determinar o tempo de backoff. |
| 500 | Código: ServiceError Mensagem: *vários |
Erro de servidor interno. | Não | Relatar o problema na comunidade de desenvolvedores. |
| 502 | Código: ServiceError Mensagem: *vários |
Problema de dependência de serviço. | Sim | Tente novamente com backoff exponencial. Se o problema persistir, reporte o problema na comunidade de desenvolvedores. |
| 503 | O serviço não está disponível. | Sim | Tente novamente com backoff exponencial. Se o problema persistir, reporte o problema na comunidade de desenvolvedores. | |
| 504 | Tempo limite do gateway. | Sim | Tente novamente com backoff exponencial. Se o problema persistir, reporte o problema na comunidade de desenvolvedores. |
Diretrizes de repetição de códigos de status
As diretrizes gerais de repetição para cada código status estão listadas na tabela a seguir, o bot deve evitar repetir status códigos que não são especificados:
| Código de status | Estratégia de repetição |
|---|---|
| 403 | Tente novamente chamando a API https://smba.infra.gcc.teams.microsoft.com do GCC para InvalidBotApiHost. |
| 412 | Tente novamente usando backoff exponencial. |
| 429 | Tente novamente usar Retry-After o cabeçalho para determinar o tempo de espera em segundos e entre as solicitações, se estiver disponível. Caso contrário, tente novamente usar o backoff exponencial com a ID do thread, se possível. |
| 502 | Tente novamente usando backoff exponencial. |
| 503 | Tente novamente usando backoff exponencial. |
| 504 | Tente novamente usando backoff exponencial. |
Exemplo de código
| Nome do exemplo | Descrição | Node.js | .NETCore | Python | .NET | Manifesto |
|---|---|---|---|---|---|---|
| Bot de conversas do Teams | Este aplicativo de exemplo mostra como usar diferentes eventos de conversa de bot disponíveis no Bot Framework v4. | View | View | Exibir | NA | Exibir |
| Localização do aplicativo Teams | Este exemplo mostra a localização do aplicativo teams usando bot e guia. | Exibir | NA | NA | View | NA |
Próxima etapa
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de