Criar sugestões de pedidos

As sugestões de pedidos são comandos que são apresentados aos utilizadores no chat do Microsoft Teams.

As sugestões de pedidos criam uma experiência de utilizador envolvente e perspicaz e ajudam o bot a adquirir e reter utilizadores, mostrando-lhes o valor do bot através de conversações rápidas. Pode utilizar sugestões de pedidos para ajudar os seus utilizadores a iniciar conversações com o bot e aprender a interagir com o mesmo.

Existem dois tipos de sugestões de pedidos que pode utilizar:

Iniciadores de pedidos

Os iniciadores de pedidos ajudam os utilizadores a iniciar uma conversa com o bot.

Ações sugeridas

As ações sugeridas ajudam os utilizadores a continuar as conversações com o bot.

Iniciadores de pedidos

Observação

• O bot pode utilizar um arranque de pedido ou uma mensagem de boas-vindas. Se o bot utilizar entradas de pedidos, certifique-se de que o bot não envia uma mensagem de boas-vindas.

• Os iniciadores de pedidos só são suportados para bots de chat um-para-um.

Para ativar os iniciadores de pedidos, defina a commands propriedade no manifesto da aplicação do bot. Cada comando contém um title e description. É title o pedido e descreve description o que os utilizadores conseguem. Quando o utilizador seleciona num inicializador de pedidos, o title do pedido é preenchido na caixa de composição. Para definir commands no manifesto da aplicação, pode utilizar o Portal do Programador ou adicioná-los manualmente no manifesto da aplicação.

Portal do Desenvolvedor

Para criar iniciadores de pedidos com o Portal do Programador:

1. Abra o Teams e selecione Aplicativos no painel esquerdo. Na página Aplicações , procure Portal do Programador e, em seguida, selecione Abrir.

   

2. No Portal do Programador, selecione o separador Aplicações . Se não tiver um pacote de aplicações existente, pode criar ou importar uma aplicação existente. Para obter mais informações, veja Portal do Programador do Teams.

3. Selecione o separador Aplicações , selecione Funcionalidades da aplicação no painel esquerdo e, em seguida, selecione Bots.

4. Em Comandos, selecione Adicionar um comando.

   

5. Introduza os valores para os seguintes campos:

   • Comando: aparece como a linha de comandos do bot.
   • Descrição: uma breve explicação do objetivo do comando.

6. Selecione o âmbito pessoal e, em seguida, selecione Adicionar. Isto define onde o menu de comandos tem de aparecer.

   

Manualmente no manifesto da aplicação

Outra forma de criar um iniciador de pedidos é criá-lo diretamente no ficheiro de manifesto da aplicação enquanto desenvolve o código fonte do bot. Para usar esse método, siga estes pontos:

• A command propriedade suporta até 10 comandos.
• Pode criar iniciadores de pedidos que funcionam em todos os âmbitos ou criar entradas de pedidos diferentes para cada âmbito.

Exemplo de manifesto para iniciadores de pedidos

O código de exemplo de manifesto para iniciadores de pedidos é o seguinte:

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal"
      ],
      "commandLists":[
        {
          "scopes":[
            "personal"
          ],
          "commands":[
            {
              "title":"Help",
              "description":"Displays this help message"
            },
            {
              "title":"Search Flights",
              "description":"Search flights from Seattle to Phoenix May 2-5 departing after 3pm"
            },
            {
              "title":"Search Hotels",
              "description":"Search hotels in Portland tonight"
            },
            {
              "title":"Best Time to Fly",
              "description":"Best time to fly to London for a 5 day trip this summer"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Observação

Se você remover qualquer comando do manifesto, deverá reimplantar seu aplicativo para implementar as alterações. Em geral, todas as alterações no manifesto exigem que você reimplante seu aplicativo.

O seguinte ilustra um exemplo de sugestões de pedidos:

Desktop

Dispositivo móvel

Os iniciadores de pedidos reaparecem na lista de opções Ver Solicitações acima da caixa de composição durante uma conversação e permite que os utilizadores revejam os pedidos enquanto interagem com o bot.

Você deve lidar com os comandos do menu em seu código bot, assim como lida com qualquer mensagem dos usuários. Pode processar comandos de menu no código do bot ao analisar a parte @Mention do texto da mensagem.

Identificador commands no bot

Os bots num grupo ou canal só respondem quando estão @mentioned numa mensagem. Cada mensagem recebida por um bot quando em um escopo de grupo ou canal contém seu nome no texto da mensagem. Antes de lidar com o comando que está sendo retornado, a análise de mensagem deve lidar com a mensagem recebida por um bot com seu nome.

Observação

Processe os comandos no código e estes são enviados para o bot como uma mensagem normal. Você deve lidar com eles como lidaria com qualquer outra mensagem de seus usuários. Os comandos no código inserem texto pré-configurado na caixa de texto. Em seguida, o usuário deve enviar esse texto da maneira como faria com qualquer outra mensagem.

C#

• Referência do SDK

• Referência de código de exemplo

Pode analisar a parte @Mention do texto da mensagem através de um método estático fornecido com o Microsoft Bot Framework. É um método da classe com o Activity nome RemoveRecipientMention.

O código C# para analisar a parte @Mention do texto da mensagem é o seguinte:

// Remove recipient mention text from Text property.
// Use with caution because this function is altering the text on the Activity.
var modifiedText = turnContext.Activity.RemoveRecipientMention();

JavaScript

• Referência do SDK

• Referência de código de exemplo

Você pode analisar a parte @Mention parte do texto da mensagem usando um método estático fornecido com o Bot Framework. É um método da classe com o TurnContext nome removeMentionText.

O código JavaScript para analisar a parte @Mention do texto da mensagem é o seguinte:

// Remove mention text from Text property, this function is altering the text on the Activity.
const modifiedText = TurnContext.removeMentionText(turnContext.activity, turnContext.activity.recipient.id);

Python

• Referência do SDK

• Referência de código de exemplo

Você pode analisar a parte @Mention parte do texto da mensagem usando um método estático fornecido com o Bot Framework. É um método da classe com o TurnContext nome remove_recipient_mention.

O código Python para analisar a parte @Mention do texto da mensagem é o seguinte:

# Remove recipient mention text from Text property, this function is altering the text on the Activity.
modified_text = TurnContext.remove_recipient_mention(turn_context.activity)

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:

Desktop

Dispositivo móvel

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js
Bot de iniciadores de pedidos	Este código de exemplo descreve a implementação de iniciadores de pedidos para bot através commands da propriedade no manifesto da aplicação do bot.	View	Exibir

Confira também

• Criar bots para o Teams
• Esquema de manifesto do aplicativo para o Teams
• Mensagens em conversas de bot
• Cartões Ajustáveis para programadores de bots