Enviar mensagem de boas-vinda aos usuários

aplica-se a: SDK v4

Ao criar um bot, o principal objetivo é envolver seu usuário em uma conversa produtiva. Uma das melhores maneiras de fazer isso é garantir que, a partir do momento em que o usuário se conectar pela primeira vez, ele entenda o objetivo e as funcionalidades principais do bot, a razão pela qual seu bot foi criado. Este artigo fornece exemplos de código para ajudá-lo a dar boas-vindas aos usuários em seu bot.

Pré-requisitos

Sobre este código de exemplo

Este código de exemplo mostra como detectar e recepcionar novos usuários quando eles são inicialmente conectados ao seu bot. O diagrama a seguir mostra o fluxo lógico desse bot.

Os dois principais eventos encontrados pelo bot são:

  • OnMembersAddedAsync, que é chamado sempre que um novo usuário é conectado ao seu bot
  • OnMessageActivityAsync, que é chamado sempre que uma nova entrada do usuário é recebida.

diagrama csharp do fluxo lógico do usuário de boas-vindas

Sempre que um novo usuário se conecta, ele recebe WelcomeMessage, InfoMessage e PatternMessage do bot. Quando uma nova entrada do usuário é recebida, WelcomeUserState é conferido para ver se DidBotWelcomeUser está definido como true. Se não, uma mensagem inicial de boas-vindas será retornada ao usuário.

Criar estado do usuário

O objeto de estado do usuário é criado na inicialização e a dependência é injetada no construtor de bot.

Startup.cs [!code-csharpdefine state]

Bots\WelcomeUserBot.cs [!code-csharpconsume state]

Criar acessadores de propriedade

Agora, criamos um acessador de propriedade que nos fornece um identificador para WelcomeUserState dentro do método OnMessageActivityAsync. Em seguida, chame o método GetAsync para obter a chave de escopo correta. Em seguida, salvamos os dados de estado do usuário após cada iteração de entrada do usuário, usando o método SaveChangesAsync.

Bots\WelcomeUserBot.cs [!code-csharpGet state]

// Save any state changes.
await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);

Detectar e saudar usuários conectados recentemente

Em WelcomeUserBot, verificamos se há uma atualização de atividade, usando OnMembersAddedAsync() para ver se um novo usuário foi adicionado à conversa e, em seguida, enviamos a ele um conjunto de três mensagens inicias de boas-vindas: WelcomeMessage, InfoMessage e PatternMessage. O código completo dessa interação é mostrado abaixo.

Bots\WelcomeUserBot.cs [!code-csharpDefine messages]

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var member in membersAdded)
    {
        if (member.Id != turnContext.Activity.Recipient.Id)
        {
            await turnContext.SendActivityAsync($"Hi there - {member.Name}. {WelcomeMessage}", cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync(InfoMessage, cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync($"{LocaleMessage} Current locale is '{turnContext.Activity.GetLocale()}'.", cancellationToken: cancellationToken);
            await turnContext.SendActivityAsync(PatternMessage, cancellationToken: cancellationToken);
        }
    }
}

Recepção do novo usuário e descarte da entrada inicial

Também é importante considerar quando a entrada do usuário pode realmente conter informações úteis. Isso pode variar para cada canal. Para garantir que o usuário tenha uma boa experiência em todos os canais possíveis, verificamos o sinalizador de status didBotWelcomeUser e, se ele for “false”, não processaremos a entrada inicial do usuário. Em vez disso, forneceremos ao usuário uma mensagem inicial de boas-vindas. O booliano welcomedUserProperty é definido como "true", armazenado em UserState e nosso código agora processará essa entrada do usuário usando todas as atividades adicionais de mensagem.

Bots\WelcomeUserBot.cs [!code-csharpDidBotWelcomeUser]

// Save any state changes.
await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);

Processar entrada adicional

Após a recepção de um novo usuário, as informações de entrada do usuário são avaliadas a cada turno de mensagem e o bot fornece uma resposta com base no contexto dessa entrada. O código a seguir mostra a lógica de decisão usada para gerar essa resposta.

Uma entrada de “intro” ou “help” chama a função SendIntroCardAsync para apresentar ao usuário um cartão Hero informativo. Esse código é examinado na próxima seção deste artigo.

Bots\WelcomeUserBot.cs [!code-csharpSwitchOnUtterance]

Usar a saudação do cartão Hero

Conforme mencionado acima, algumas entradas do usuário geram um cartão Hero em resposta à solicitação. Saiba mais sobre as saudações do cartão Hero aqui: Enviar um cartão de introdução. Veja abaixo o código necessário para criar a resposta do cartão Hero do bot.

Bots\WelcomeUserBot.cs [!code-csharpSendHeroCardGreeting]

Testar o bot

Baixe e instale o Bot Framework Emulator mais recente

  1. Execute o exemplo localmente em seu computador. Se você precisar de instruções, consulte o README arquivo para exemplo do C# Sample ou js.
  2. Use o Emulador para testar o bot, conforme mostrado abaixo.

test welcome bot sample

Testar saudação do cartão Hero.

test welcome bot card

Recursos adicionais

Saiba mais sobre várias respostas de mídia em Adicionar mídia a mensagens.

Próximas etapas