Envío de mensajes de bienvenida a los usuariosSend welcome message to users

se aplica a: SDK V4APPLIES TO: SDK v4

El objetivo principal al crear cualquier bot es que el usuario participe en una conversación que tenga sentido.The primary goal when creating any bot is to engage your user in a meaningful conversation. Una de las mejores formas de lograr este objetivo es asegurarse de que desde el momento en que un usuario se conecta por primera vez, comprende la finalidad principal del bot y sus funcionalidades, es decir, el motivo de que se haya creado el bot.One of the best ways to achieve this goal is to ensure that from the moment a user first connects, they understand your bot's main purpose and capabilities, the reason your bot was created. Este artículo proporciona ejemplos de código que le ayudarán a dar la bienvenida a los usuarios del bot.This article provides code examples to help you welcome users to your bot.

Requisitos previosPrerequisites

Acerca de este código de ejemploAbout this sample code

Este código de ejemplo muestra cómo detectar y dar la bienvenida a los nuevos usuarios cuando se conectan al bot inicialmente.This sample code shows how to detect and welcome new users when they are initially connected to your bot. El siguiente diagrama muestra el flujo de lógica de este bot.The following diagram shows the logic flow for this bot.

Los dos principales eventos detectados por el bot son:The two main events encountered by the bot are:

  • OnMembersAddedAsync, que se llama cada vez que un nuevo usuario se conecta al botOnMembersAddedAsync which is called whenever a new user is connected to your bot
  • OnMessageActivityAsync, que se llama cada vez que se recibe la entrada de un nuevo usuario.OnMessageActivityAsync which is called whenever a new user input is received.

Diagrama de csharp de flujo de lógica de usuario de bienvenida

Cada vez que un nuevo usuario se conecta, el bot le proporciona los elementos WelcomeMessage, InfoMessage y PatternMessage.Whenever a new user is connected, they are provided with a WelcomeMessage, InfoMessage, and PatternMessage by the bot. Cuando se recibe una nueva entrada de usuario, WelcomeUserState se comprueba para ver si DidBotWelcomeUser está establecido en true.When a new user input is received, WelcomeUserState is checked to see if DidBotWelcomeUser is set to true. Si no es así, se devuelve un mensaje de bienvenida inicial al usuario.If not, an initial welcome user message is returned to the user.

Creación del estado del usuarioCreate user state

El objeto de estado del usuario se crea en el inicio y se inserta la dependencia en el constructor del bot.The user state object is created at startup and dependency injected into the bot constructor.

Startup.cs [!code-csharpdefine state]Startup.cs [!code-csharpdefine state]

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

Creación de los descriptores de acceso de la propiedadCreate property accessors

Ahora se crea un descriptor de acceso de la propiedad que nos proporciona un manipulador para WelcomeUserState dentro del método OnMessageActivityAsync.We now create a property accessor that provides us a handle to WelcomeUserState inside the OnMessageActivityAsync method. A continuación, se llamará al método GetAsync para obtener la clave con el ámbito correcto.Then call the GetAsync method to get the properly scoped key. A continuación, guardamos los datos de estado del usuario después de cada iteración de entrada del usuario con el método SaveChangesAsync.We then save user state data after each user input iteration using the SaveChangesAsync method.

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

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

Detección y saludo a los usuarios recién conectadosDetect and greet newly connected users

En WelcomeUserBot, se comprueba si hay una actualización de actividad mediante OnMembersAddedAsync() para ver si se ha agregado un nuevo usuario a la conversación y, a continuación, se envía un conjunto de tres mensajes iniciales de bienvenida: WelcomeMessage, InfoMessage y PatternMessage.In WelcomeUserBot, we check for an activity update using OnMembersAddedAsync() to see if a new user has been added to the conversation and then send them a set of three initial welcome messages WelcomeMessage, InfoMessage and PatternMessage. A continuación se muestra el código completo de esta interacción.Complete code for this interaction is shown below.

Bots\WelcomeUserBot.cs [!code-csharpDefine messages]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);
        }
    }
}

Bienvenida al nuevo usuario y descarte de la entrada inicialWelcome new user and discard initial input

También es importante tener en cuenta cuándo la entrada del usuario puede contener realmente información útil y esto puede variar para cada canal.It is also important to consider when your user's input might actually contain useful information, and this may vary for each channel. Para asegurarse de que el usuario tenga una buena experiencia en todos los canales posibles, comprobamos la marca de estado didBotWelcomeUser y, si es "false", no se procesa la entrada de usuario inicial.To ensure your user has a good experience on all possible channels, we check the status flag didBotWelcomeUser and if this is "false", we do not process the initial user input. En su lugar, proporcionamos al usuario un mensaje de bienvenida inicial.We instead provide the user with an initial welcome message. El valor booleano welcomedUserProperty, a continuación, se establece en "true", se almacena en UserState y el código procesará la entrada del usuario de todas las actividades de mensaje adicionales.The bool welcomedUserProperty is then set to "true", stored in UserState and our code will now process this user's input from all additional message activities.

Bots\WelcomeUserBot.cs [!code-csharpDidBotWelcomeUser]Bots\WelcomeUserBot.cs [!code-csharpDidBotWelcomeUser]

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

Proceso de entradas adicionalesProcess additional input

Una vez se ha dado la bienvenida a un nuevo usuario, la información de entrada del usuario se evalúa en cada turno de mensaje y el bot proporciona una respuesta en función del contexto de esa entrada del usuario.Once a new user has been welcomed, user input information is evaluated for each message turn and the bot provides a response based on the context of that user input. El código siguiente muestra la lógica de decisiones que se usa para generar esa respuesta.The following code shows the decision logic used to generate that response.

Una entrada de "intro" o "help" llama a la función SendIntroCardAsync para presentar al usuario una tarjeta de imagen prominente informativa.An input of 'intro' or 'help' calls the function SendIntroCardAsync to present the user with an informational hero card. El código se examina en la sección siguiente de este artículo.That code is examined in the next section of this article.

Bots\WelcomeUserBot.cs [!code-csharpSwitchOnUtterance]Bots\WelcomeUserBot.cs [!code-csharpSwitchOnUtterance]

Uso del saludo de la tarjeta de imagen prominenteUsing hero card greeting

Como se mencionó anteriormente, algunas entradas de usuario generan una tarjeta de imagen prominente en respuesta a su solicitud.As mentioned above, some user inputs generate a Hero Card in response to their request. Puede aprender más sobre las tarjetas de imagen prominente aquí: Envío de una tarjeta de introducción.You can learn more about hero card greetings here Send an Intro Card. A continuación está el código necesario para crear la respuesta de tarjeta de imagen prominente de este bot.Below is the code required to create this bot's hero card response.

Bots\WelcomeUserBot.cs [!code-csharpSendHeroCardGreeting]Bots\WelcomeUserBot.cs [!code-csharpSendHeroCardGreeting]

Probar el botTest the bot

Descargue e instale la versión más reciente de Bot Framework Emulator.Download and install the latest Bot Framework Emulator

  1. Ejecute el ejemplo localmente en la máquina.Run the sample locally on your machine. Si necesita instrucciones, consulte el archivo Léame en el ejemplo de C# o JS.If you need instructions, refer to the README file for C# Sample or JS Sample.
  2. Use el emulador para probar el bot tal y como se muestra a continuación.Use the Emulator to test the bot as shown below.

ejemplo de bot de bienvenida de prueba

Pruebe el saludo de la tarjeta de imagen prominente.Test hero card greeting.

tarjeta del bot de bienvenida de prueba

Recursos adicionalesAdditional Resources

Más información sobre diversas respuestas de elementos multimedia en Adición de elementos multimedia a los mensajes.Learn more about various media responses in Add media to messages.

Pasos siguientesNext steps