Mensagens em conversas de bot

  • Artigo

Cada mensagem numa conversação é um Activity objeto do tipo messageType: message. Quando um utilizador envia uma mensagem, o Microsoft Teams publica a atividade da mensagem no seu bot. O Teams envia um objeto JSON para o ponto final de mensagens do bot e o Teams permite apenas um ponto final para mensagens. Seu bot examina a mensagem para determinar seu tipo e responde adequadamente.

As conversações básicas são processadas através do conector do Bot Framework, uma única API REST. Esta API permite que o bot comunique com o Teams e outros canais. O SDK do Bot Builder fornece as seguintes funcionalidades:

  • Acesso fácil ao conector do Bot Framework.
  • Funcionalidade para gerir o fluxo e o estado da conversação.
  • Formas simples de incorporar serviços cognitivos, como o processamento de linguagem natural (NLP).

O bot recebe mensagens do Teams através da Text propriedade e envia respostas de mensagens individuais ou múltiplas aos utilizadores.

Para obter mais informações, veja Atribuição de utilizador para mensagens de bot.

A tabela seguinte lista a atividade que o bot pode receber e tomar medidas:

Tipo Objeto payload Escopo
Receber uma atividade de mensagem Atividade de mensagens Todos
Receber atividade de edição de mensagens Atividade de edição de mensagens Todos
Receber atividade de não eliminação de mensagens Atividade de anular eliminação de mensagens Todos
Receber atividade de mensagem de eliminação recuperável Atividade de eliminação recuperável de mensagens Todos

Receber uma atividade de mensagem

Para receber uma mensagem sms, utilize 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 seguinte mostra um exemplo de como receber 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 definição Recibos de leitura no Teams permite que o remetente de uma mensagem de chat seja notificado quando a mensagem foi lida pelo destinatário em conversas um-a-um e em grupo. Depois de o destinatário ler a mensagem, é apresentada a mensagem Vista junto à mensagem. Também tem a opção de configurar o bot para receber eventos de recibos de leitura através da definição Recibos de leitura. O evento de recibo de leitura ajuda-o a melhorar a experiência do utilizador das seguintes formas:

  • Pode configurar o bot para enviar uma mensagem de seguimento se o utilizador da sua aplicação não tiver lido a mensagem no chat pessoal.

  • Pode criar um ciclo de comentários com recibos de leitura para otimizar a experiência do bot.

Observação

  • Os recibos de leitura são suportados apenas em cenários de chat de utilizador para bot.
  • Os recibos de leitura para bots não suportam âmbitos de chat de equipa, canal e grupo.
  • Se um administrador de inquilinos ou utilizador desativar a definição Recibos de leitura, o bot não recebe o evento de recibo de leitura.

Para receber eventos de recibos de leitura para o bot, certifique-se do seguinte:

    
"webApplicationInfo": {
    
     "id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
     "resource": ""
},
"authorization": {
    "permissions": {
    "orgwide": [],
     "resourceSpecific": [
        {
        "name": "ChatMessageReadReceipt.Read.Chat",
        "type": "Application"
        }
        ]
     }
 }

Também pode adicionar permissões RSC através de API do Graph. Para obter mais informações, confira consentedPermissionSet.

  • Substitua o método OnTeamsReadReceiptAsync pelo IsMessageRead processador.

    O IsMessageRead método auxiliar é útil para determinar se a mensagem é lida pelos destinatários. Se for compareMessageId menor ou igual a LastReadMessageId, significa que a mensagem foi lida. Substitua o OnTeamsReadReceiptAsync método para receber recibos de leitura com IsMessageRead o 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);    
    }
}

    Segue-se um exemplo de pedido 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 definição de administrador de recibos de leitura ou a definição de utilizador está ativada para o inquilino para que o bot receba os eventos de recibo de leitura. O administrador do inquilino ou o utilizador têm de ativar ou desativar a definição de recibo de leitura.

Depois de o bot estar ativado num cenário de chat de bot de um utilizador, o bot recebe prontamente um evento de recibo de leitura quando o utilizador ler a mensagem do bot. Pode controlar a interação do utilizador ao contar o número de eventos e também pode enviar uma mensagem com suporte para o contexto.

Enviar uma mensagem

Para enviar uma mensagem sms, especifique a cadeia que pretende enviar como uma atividade. No processador de atividade do bot, utilize o método do objeto de SendActivityAsync contexto turn para enviar uma única resposta de mensagem. Utilize o método do SendActivitiesAsync objeto para enviar várias respostas.

O código seguinte mostra um exemplo de envio de uma mensagem quando um utilizador é adicionado a uma conversação:


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 sms e um anexo são enviados no mesmo payload de atividade. O Teams divide esta atividade em duas atividades separadas, uma com uma mensagem de texto e outra com um anexo. À medida que a atividade é dividida, não recebe o ID da mensagem em resposta, que é utilizado para atualizar ou eliminar a mensagem proativamente. Recomenda-se que envie 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, veja Localizar a sua aplicação.

As mensagens enviadas entre utilizadores e bots incluem dados de canal internos na mensagem. Estes dados permitem que o bot comunique corretamente nesse canal. O SDK do Bot Builder permite-lhe modificar a estrutura da mensagem.

Obter atividade de edição de mensagens

Quando edita uma mensagem, o bot recebe uma notificação da atividade editar mensagem.

Para obter uma notificação de atividade de edição de mensagens num bot, pode substituir OnTeamsMessageEditAsync o processador.

Segue-se um exemplo de uma notificação de atividade de edição de mensagens que utiliza 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 anular eliminação de mensagens

Quando anula a eliminação de uma mensagem, o bot recebe uma notificação da atividade de anular a eliminação da mensagem.

Para obter uma notificação de atividade de anulação de eliminação de mensagens num bot, pode substituir OnTeamsMessageUndeleteAsync o processador.

Segue-se um exemplo de uma notificação de atividade de não eliminação de mensagens que utiliza OnTeamsMessageUndeleteAsync quando uma mensagem eliminada é 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 mensagens de eliminação recuperável

Quando elimina uma mensagem de forma recuperável, o bot recebe uma notificação da atividade da mensagem de eliminação recuperável.

Para obter uma notificação de atividade de mensagem de eliminação recuperável num bot, pode substituir OnTeamsMessageSoftDeleteAsync o processador.

Segue-se um exemplo de uma notificação de atividade de eliminação recuperável de mensagens que utiliza OnTeamsMessageSoftDeleteAsync quando uma mensagem é eliminada de forma recuperável:


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 ajudam os utilizadores com ideias sobre o que perguntar a seguir, com base na resposta ou conversação anterior. O bot deve oferecer sugestões específicas de contexto ao utilizador, em vez de sugestões genéricas ou fixas. Pode utilizar o grande modelo de linguagem (LLM) do bot para gerar até três sugestões, juntamente com as respetivas respostas. Em seguida, pode extrair estas sugestões e apresentá-las como opções para o utilizador escolher.

Quando um utilizador seleciona um botão, este permanece visível e acessível nos cartões avançados. No entanto, para as ações sugeridas, os botões são concebidos para desaparecer após a seleção para impedir que o utilizador selecione opções obsoletas que podem já não ser relevantes.

Observação

  • SuggestedActions só são suportados para bots de chat um-para-um com mensagens baseadas em texto e Cartões Ajustáveis.
  • SuggestedActions não são suportados para bots de chat com anexos para qualquer tipo de conversação.
  • imBack é o único tipo de ação suportado e o Teams apresenta até três ações sugeridas.

Para adicionar ações sugeridas a uma mensagem, especifique uma lista de card objetos de ação que representam os botões a serem apresentados ao utilizador para a sugestedActions propriedade do objeto de atividade.

Segue-se um exemplo para implementar e experimentar ações sugeridas:

{
  "type": "message",
  "from": {
    "id": "12345678",
    "name": "sender's name"
  },
  "conversation": {
    "id": "abcd1234",
    "name": "conversation's name"
  },
  "recipient": {
    "id": "1234abcd",
    "name": "recipient's name"
  },
  "text": "What are the tasks for the day.",
  "inputHint": "expectingInput",
  "suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Create a new query identifying overdue tasks",
        "value": "Create a new query identifying overdue tasks"
      },
      {
        "type": "imBack",
        "title": "Create a new work item for this feature",
        "value": "Create a new work item for this feature"
            }
        ]
    },
  "replyToId": "5d5cdc723"
}

O seguinte ilustra um exemplo de ações sugeridas:

Dados do canal do Teams

O channelData objeto contém informações específicas do Teams e é uma origem definitiva para IDs de equipa e de canal. Opcionalmente, pode colocar em cache e utilizar estes IDs como chaves para o armazenamento local. O TeamsActivityHandler no SDK obtém informações importantes do channelData objeto para torná-lo acessível. No entanto, pode sempre aceder aos dados originais a turnContext partir do objeto.

O channelData objeto não está incluído em mensagens em conversações pessoais, uma vez que estas ocorrem fora de um canal.

Um objeto típico channelData numa atividade enviada para o bot contém as seguintes informações:

  • eventType: Tipo de evento do Teams transmitido apenas em casos de eventos de modificação de canais.
  • tenant.id: Microsoft Entra ID de inquilino transmitido em todos os contextos.
  • team: transmitido apenas em contextos de canal e não em conversas pessoais.
  • channel: transmitido apenas em contextos de canal, quando o bot é mencionado ou para eventos em canais em equipas, onde o bot é adicionado.
  • channelData.teamsTeamId: Preterido. Esta propriedade só está incluída para retrocompatibilidade.
  • channelData.teamsChannelId: Preterido. Esta propriedade só está incluída para retrocompatibilidade.

Exemplo de channelData object

O código seguinte mostra um exemplo do objeto channelData (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 mensagem

As mensagens recebidas ou enviadas para o bot podem incluir diferentes tipos de conteúdo de mensagens.

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 píxeis e 1 MB no formato PNG, JPEG ou GIF. Não suporta o GIF animado.
Cartões ❌ ✔️ Veja Referência de card do Teams para cartões suportados.
Emojis ✔️ ✔️ O Teams suporta emojis através de UTF-16, como U+1F600 para sorrisos.

Mensagens de imagem

Para melhorar a sua mensagem, pode incluir imagens como anexos dessa mensagem. Para obter mais informações sobre anexos, consulte Adicionar anexos multimédia a mensagens.

As imagens podem ter, no máximo, 1024 × 1024 píxeis 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 com XML. Em Markdown, o tamanho da imagem é predefinido para 256×256. Por exemplo:

  • Utilize: <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>.
  • Não utilize: ![Duck on a rock](http://aka.ms/Fo983c).

Um bot de conversação pode incluir Cartões Ajustáveis que simplificam os fluxos de trabalho empresariais. Os Cartões Ajustáveis oferecem texto, voz, imagens, botões e campos de entrada personalizáveis avançados.

Cartões Adaptáveis

Os Cartões Ajustáveis podem ser criados num bot e apresentados em várias aplicações, como o Teams, o seu site, etc. Para obter mais informações, Cartões Adaptáveis.

O código seguinte 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

Existem duas formas de enviar uma notificação a partir da sua aplicação:

  • Ao definir a Notification.Alert propriedade na mensagem do bot.
  • Ao enviar uma notificação do feed de atividades com o API do Graph.

Pode adicionar notificações à sua mensagem com a Notification.Alert propriedade . As notificações alertam os utilizadores para um evento na sua aplicação, como novas tarefas, menções ou comentários. Estes alertas estão relacionados com aquilo em que os utilizadores estão a trabalhar ou o que têm de ver ao inserir um aviso no respetivo feed de atividades. Para que as notificações acionem a partir da mensagem do bot, defina a TeamsChannelData propriedade objects Notification.Alert como true. Se uma notificação for levantada, depende das definições individuais do Teams do utilizador e não pode substituir estas definições.

Se quiser gerar uma notificação arbitrária sem enviar uma mensagem ao utilizador, pode utilizar o API do Graph. Para obter mais informações, veja como enviar notificações do feed de atividades com API do Graph juntamente com as melhores práticas.

Observação

O campo Resumo apresenta qualquer texto do utilizador como uma mensagem de notificação no feed.

O código seguinte 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 estado das APIs de conversação do bot

Certifique-se de que lida com estes erros adequadamente na sua aplicação Teams. A tabela seguinte lista os códigos de erro e as descrições nas quais os erros são gerados:

Código de status Código de erro e valores de mensagens Descrição Pedido de repetição Ação de programador
400 Código: Bad Argument
Mensagem: *cenário específico		 Payload de pedido inválido fornecido pelo bot. Veja a mensagem de erro para obter detalhes específicos. Não Reavalie o payload do pedido para erros. Verifique a mensagem de erro devolvida para obter detalhes.
401 Código: BotNotRegistered
Mensagem: Não foi encontrado nenhum registo para este bot.		 O registo deste bot não foi encontrado. Não Verifique o ID e a palavra-passe do bot. Confirme que o ID do bot (Microsoft Entra ID) está registado no Portal do Programador do Teams ou através do registo do canal de bot do Azure no Azure com o canal "Teams" ativado.
403 Código: BotDisabledByAdmin
Mensagem: O administrador de inquilinos desativou este bot		 O administrador do inquilino bloqueou as interações entre o utilizador e a aplicação de bot. O administrador de inquilinos tem de permitir a aplicação para o utilizador dentro das políticas de aplicações. Para obter mais informações, veja Políticas de aplicações. Não Pare a publicação na conversação até que a interação com o bot seja explicitamente iniciada por um utilizador na conversação que indica que o bot já não está bloqueado.
403 Código: BotNotInConversationRoster
Mensagem: O bot não faz parte da lista de conversações.		 O bot não faz parte da conversação. A aplicação tem de ser reinstalada na conversação. Não Antes de tentar enviar outro pedido de conversação, aguarde por um installationUpdate evento, que indica que o bot é adicionado novamente.
403 Código: ConversationBlockedByUser
Mensagem: O utilizador bloqueou a conversação com o bot.		 O utilizador bloqueou o bot no chat pessoal ou num canal através das definições de moderação. Não Elimine a conversação da cache. Pare de tentar publicar em conversações até que a interação com o bot seja explicitamente iniciada por um utilizador na conversação, indicando que o bot já não está bloqueado.
403 Código: ForbiddenOperationException
Mensagem: O bot não está instalado no âmbito pessoal do utilizador		 A mensagem proativa é enviada por um bot, que não está instalado num âmbito pessoal. Não Antes de tentar enviar outro pedido de conversação, instale a aplicação no âmbito pessoal.
403 Código: InvalidBotApiHost
Mensagem: Anfitrião de API de bot inválido. Para inquilinos GCC, chame https://smba.infra.gcc.teams.microsoft.com.		 O bot chamou o ponto final da API pública para uma conversação que pertence a um inquilino GCC. Não Atualize o URL do serviço para a conversação e https://smba.infra.gcc.teams.microsoft.com repita o pedido.
403 Código: NotEnoughPermissions
Mensagem: *cenário específico		 O bot não tem as permissões necessárias para efetuar a ação pedida. Não Determine a ação necessária da mensagem de erro.
404 Código: ActivityNotFoundInConversation
Mensagem: Conversação não encontrada.		 Não foi possível localizar o ID da mensagem fornecida na conversação. A mensagem não existe ou é eliminada. Não Verifique se o ID da mensagem enviada é um valor esperado. Remova o ID se tiver sido colocado em cache.
404 Código: ConversationNotFound
Mensagem: Conversação não encontrada.		 A conversação não foi encontrada porque não existe ou é eliminada. Não Verifique se o ID de conversação enviado é um valor esperado. Remova o ID se tiver sido colocado em cache.
412 Código: PreconditionFailed
Mensagem: Falha na pré-condição. Tente novamente.		 Uma condição prévia falhou numa das nossas dependências devido a várias operações simultâneas na mesma conversação. Sim Repita com um recuo exponencial.
413 Código: MessageSizeTooBig
Mensagem: Tamanho da mensagem demasiado grande.		 O tamanho do pedido recebido era demasiado grande. Para obter mais informações, consulte Formatar as mensagens do bot. Não Reduza o tamanho do payload.
429 Código: Throttled
Mensagem: Demasiados pedidos. Também devolve quando tentar novamente depois.		 Demasiados pedidos enviados pelo bot. Para obter mais informações, veja Limite de taxa. Sim Repita a utilização do cabeçalho Retry-After para determinar o tempo de trás.
500 Código: ServiceError
Mensagem: *vários		 Erro de servidor interno. Não Comunicar o problema na comunidade de programadores.
502 Código: ServiceError
Mensagem: *vários		 Problema de dependência do serviço. Sim Repita com um recuo exponencial. Se o problema persistir, comunique o problema na comunidade de programadores.
503 O serviço não está disponível. Sim Repita com um recuo exponencial. Se o problema persistir, comunique o problema na comunidade de programadores.
504 Tempo Limite do Gateway. Sim Repita com um recuo exponencial. Se o problema persistir, comunique o problema na comunidade de programadores.

Documentação de orientação de repetição dos códigos de estado

As orientações gerais de repetição para cada código de status estão listadas na tabela seguinte. O bot tem de evitar repetir status códigos que não estão especificados:

Código de status Estratégia de repetição
403 Repita ao chamar a API https://smba.infra.gcc.teams.microsoft.com GCC para InvalidBotApiHost.
412 Repita com o recuo exponencial.
429 Repita a utilização do cabeçalho Retry-After para determinar o tempo de espera em segundos e entre os pedidos, se disponível. Caso contrário, repita a utilização de um backoff exponencial com o ID do thread, se possível.
502 Repita com o recuo exponencial.
503 Repita com o recuo exponencial.
504 Repita com o recuo exponencial.

Exemplo de código

Nome do exemplo Descrição Node.js .NETCore Python .NET Manifesto
Bot de conversas do Teams Esta aplicação de exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no Bot Framework v4. View View Exibir NA Exibir
Localização de aplicações do Teams Este exemplo mostra a localização da aplicação Teams com o bot e o separador. View NA NA Exibir NA

Próxima etapa

Menus de comando do bot

Confira também