Welkomstbericht verzenden naar gebruikers

Artikel
10/27/2023

VAN TOEPASSING OP: SDK v4

Het belangrijkste doel bij het maken van een bot is om uw gebruiker in een zinvol gesprek te betrekken. Een van de beste manieren om dit doel te bereiken, is ervoor te zorgen dat vanaf het moment dat een gebruiker voor het eerst verbinding maakt, inzicht krijgt in het belangrijkste doel en de mogelijkheden van uw bot, de reden waarom uw bot is gemaakt. Dit artikel bevat codevoorbeelden om u te helpen gebruikers welkom te verwelkomen bij uw bot.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Vereisten

Basisbeginselen van bot begrijpen.
Een kopie van het welkomstgebruikersvoorbeeld in C#-voorbeeld, JS-voorbeeld, Java-voorbeeld of Python-voorbeeld. De code uit het voorbeeld wordt gebruikt om uit te leggen hoe u welkomstberichten verzendt.

Over deze voorbeeldcode

Deze voorbeeldcode laat zien hoe u nieuwe gebruikers kunt detecteren en verwelkomen wanneer ze in eerste instantie zijn verbonden met uw bot. In het volgende diagram ziet u de logische stroom voor deze bot.

De twee belangrijkste gebeurtenissen die door de bot worden aangetroffen, zijn:

OnMembersAddedAsync, aangeroepen wanneer een nieuwe gebruiker verbinding maakt met uw bot.
OnMessageActivityAsync, aangeroepen wanneer uw bot nieuwe gebruikersinvoer ontvangt.

Logische stroomdiagram voor C#-voorbeeld.

Wanneer een nieuwe gebruiker is verbonden, worden deze geleverd met een WelcomeMessage, InfoMessageen PatternMessage door de bot. Wanneer er een nieuwe gebruikersinvoer wordt ontvangen, wordt WelcomeUserState gecontroleerd om te zien of DidBotWelcomeUser deze is ingesteld op waar. Zo niet, dan wordt er een eerste welkomstbericht van de gebruiker geretourneerd.

De twee belangrijkste gebeurtenissen die door de bot worden aangetroffen, zijn:

onMembersAdded, aangeroepen wanneer een nieuwe gebruiker verbinding maakt met uw bot.
onMessage, aangeroepen wanneer uw bot nieuwe gebruikersinvoer ontvangt.

Logische stroomdiagram voor JavaScript-voorbeeld.

Wanneer een nieuwe gebruiker is verbonden, worden deze geleverd met een welcomeMessage, infoMessageen patternMessage door de bot. Wanneer een nieuwe gebruikersinvoer wordt ontvangen, welcomedUserProperty wordt gecontroleerd of didBotWelcomeUser deze is ingesteld op waar. Zo niet, dan wordt er een eerste welkomstbericht van de gebruiker geretourneerd. Als DidBotWelcomeUser dit waar is, wordt de invoer van de gebruiker geëvalueerd. Op basis van de inhoud van de invoer van de gebruiker voert deze bot een van de volgende handelingen uit:

Echo terug een begroeting ontvangen van de gebruiker.
Een herokaart weergeven die aanvullende informatie over bots biedt.
WelcomeMessage De verwachte invoer voor deze bot opnieuw verzenden.

De twee belangrijkste gebeurtenissen die door de bot worden aangetroffen, zijn:

onMembersAdded, aangeroepen wanneer een nieuwe gebruiker verbinding maakt met uw bot.
onMessageActivity, aangeroepen wanneer uw bot nieuwe gebruikersinvoer ontvangt.

Logische stroomdiagram voor Java-voorbeeld.

Wanneer een nieuwe gebruiker is verbonden, worden deze geleverd met een WELCOME_MESSAGE, INFO_MESSAGEen PATTERN_MESSAGE door de bot. Wanneer er een nieuwe gebruikersinvoer wordt ontvangen, wordt WelcomeUserState gecontroleerd om te zien of getDidBotWelcomeUser() deze is ingesteld op waar. Zo niet, dan wordt er een eerste welkomstbericht van de gebruiker geretourneerd.

De twee belangrijkste gebeurtenissen die door de bot worden aangetroffen, zijn:

on_members_added_activity, aangeroepen wanneer een nieuwe gebruiker verbinding maakt met uw bot.
on_message_activity, aangeroepen wanneer uw bot nieuwe gebruikersinvoer ontvangt.

Logische stroomdiagram voor Python-voorbeeld.

Wanneer een nieuwe gebruiker is verbonden, krijgt deze een welkomstbericht, informatiebericht en een patroonbericht van de bot. Wanneer er een nieuwe gebruikersinvoer wordt ontvangen, wordt de welcome_user_state.did_welcome_user eigenschap gecontroleerd. Als dit niet is ingesteld op true, wordt er een eerste welkomstbericht van de gebruiker geretourneerd. Als deze is ingesteld op true, doet deze bot op basis van de inhoud van de invoer van de gebruiker een van de volgende handelingen:

Echo terug een begroeting ontvangen van de gebruiker.
Een herokaart weergeven die aanvullende informatie over bots biedt.

Gebruikersstatus maken

Het gebruikersstatusobject wordt gemaakt bij het opstarten en de afhankelijkheid die is geïnjecteerd in de botconstructor.

Startup.cs


// Create the Bot Framework Authentication to be used with the Bot Adapter.
services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

// Create the Bot Adapter with error handling enabled.

Bots\WelcomeUserBot.cs


// Initializes a new instance of the "WelcomeUserBot" class.
public WelcomeUserBot(UserState userState)
{
    _userState = userState;
}

Bij het opstarten wordt de gebruikersstatus gedefinieerd in index.js en gebruikt door de botconstructor.

index.js


// Create HTTP server
const server = restify.createServer();
server.use(restify.plugins.bodyParser());

server.listen(process.env.port || process.env.PORT || 3978, function() {
    console.log(`\n${ server.name } listening to ${ server.url }`);
    console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator');

Het gebruikersstatusobject wordt gemaakt bij het opstarten en de afhankelijkheid die door de Spring-container is geïnjecteerd in de botconstructor.

Application.java

@Bean
public Bot getBot(UserState userState) {
    return new WelcomeUserBot(userState);
}

WelcomeUserBot.java

private final UserState userState;

// Initializes a new instance of the "WelcomeUserBot" class.
@Autowired
public WelcomeUserBot(UserState withUserState) {
    userState = withUserState;
}

Bij het opstarten wordt de gebruikersstatus gedefinieerd in app.py en gebruikt door de botconstructor.

app.py


# Create the Bot
BOT = WelcomeUserBot(USER_STATE)


# Listen for incoming requests on /api/messages.

Eigenschapstoegangsors maken

We maken nu een eigenschapstoegangsor die ons een ingang biedt binnen WelcomeUserState de OnMessageActivityAsync methode. Roep vervolgens de GetAsync methode aan om de juiste bereiksleutel op te halen. Vervolgens slaan we gebruikersstatusgegevens op na elke iteratie van gebruikersinvoer met behulp van de SaveChangesAsync methode.

Bots\WelcomeUserState.cs

// Gets or sets whether the user has been welcomed in the conversation.
public bool DidBotWelcomeUser { get; set; } = false;

Bots\WelcomeUserBot.cs

var didBotWelcomeUser = await welcomeUserStateAccessor.GetAsync(turnContext, () => new WelcomeUserState(), cancellationToken);

    await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);
}

We maken nu een eigenschapstoegangsfunctie die ons een ingang biedt voor welcomedUserProperty die blijft behouden in userState.

bots/welcomeBot.js

this.welcomedUserProperty = userState.createProperty(WELCOMED_USER);

this.onMessage(async (context, next) => {
    // Read UserState. If the 'DidBotWelcomedUser' does not exist (first time ever for a user)
    // set the default to false.
    const didBotWelcomedUser = await this.welcomedUserProperty.get(context, false);

/**
 * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
 */
async run(context) {
    await super.run(context);

    // Save state changes
    await this.userState.saveChanges(context);
}

We maken nu een eigenschapstoegangsor die ons een ingang biedt binnen WelcomeUserState de onMessageActivity methode. Roep vervolgens de get methode aan om de juiste bereiksleutel op te halen. Vervolgens slaan we gebruikersstatusgegevens op na elke iteratie van gebruikersinvoer met behulp van de saveChanges methode.

WelcomeUserBot.java

// Get state data from UserState.
StatePropertyAccessor<WelcomeUserState> stateAccessor =
    userState.createProperty("WelcomeUserState");
CompletableFuture<WelcomeUserState> stateFuture =
    stateAccessor.get(turnContext, WelcomeUserState::new);

return super.onTurn(turnContext)
    .thenCompose(saveResult -> userState.saveChanges(turnContext));

In dit voorbeeld wordt een accessor voor gespreksstatuseigenschappen gemaakt, user_state_accessorin de botconstructor.

bots/welcome-user-bot.py

self.user_state_accessor = self._user_state.create_property("WelcomeUserState")

Deze gebruikt de eigenschapstoegangsor in de on_message_activity handler en overschrijft de handler om de on_turn status op te slaan vóór het einde van de beurt.

# Get the state properties from the turn context.
welcome_user_state = await self.user_state_accessor.get(
    turn_context, WelcomeUserState
)

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # save changes to WelcomeUserState after each turn
    await self._user_state.save_changes(turn_context)

Nieuw verbonden gebruikers detecteren en begroeten

In WelcomeUserBot controleren we op een activiteitsupdate om OnMembersAddedAsync() te zien of er een nieuwe gebruiker is toegevoegd aan het gesprek en vervolgens een set van drie eerste welkomstberichten WelcomeMessagete verzenden, InfoMessage en PatternMessage. Volledige code voor deze interactie wordt hieronder weergegeven.

Bots\WelcomeUserBot.cs

public class WelcomeUserBot : ActivityHandler
{
    // Messages sent to the user.
    private const string WelcomeMessage = "This is a simple Welcome Bot sample. This bot will introduce you " +
                                            "to welcoming and greeting users. You can say 'intro' to see the " +
                                            "introduction card. If you are running this bot in the Bot Framework " +
                                            "Emulator, press the 'Start Over' button to simulate user joining " +
                                            "a bot or a channel";

    private const string InfoMessage = "You are seeing this message because the bot received at least one " +
                                        "'ConversationUpdate' event, indicating you (and possibly others) " +
                                        "joined the conversation. If you are using the emulator, pressing " +
                                        "the 'Start Over' button to trigger this event again. The specifics " +
                                        "of the 'ConversationUpdate' event depends on the channel. You can " +
                                        "read more information at: " +
                                        "https://aka.ms/about-botframework-welcome-user";

    private const string LocaleMessage = "You can use the activity's 'GetLocale()' method to welcome the user " +
                                         "using the locale received from the channel. " + 
                                         "If you are using the Emulator, you can set this value in Settings.";

{
    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);
        }
    }
}

Met deze JavaScript-code worden initiële welkomstberichten verzonden wanneer een gebruiker wordt toegevoegd. Dit wordt gedaan door de gespreksactiviteit te controleren en te controleren of er een nieuw lid is toegevoegd aan het gesprek.

bots/welcomeBot.js

// Sends welcome messages to conversation members when they join the conversation.
// Messages are only sent to conversation members who aren't the bot.
this.onMembersAdded(async (context, next) => {
    // Iterate over all new members added to the conversation
    for (const idx in context.activity.membersAdded) {
        // Greet anyone that was not the target (recipient) of this message.
        // Since the bot is the recipient for events from the channel,
        // context.activity.membersAdded === context.activity.recipient.Id indicates the
        // bot was added to the conversation, and the opposite indicates this is a user.
        if (context.activity.membersAdded[idx].id !== context.activity.recipient.id) {
            await context.sendActivity(`Welcome to the 'Welcome User' Bot. This bot will introduce you to welcoming and greeting users.`);
            await context.sendActivity(`You are seeing this message because the bot received at least one 'ConversationUpdate' ` +
                `event, indicating you (and possibly others) joined the conversation. If you are using the emulator, ` +
                `pressing the 'Start Over' button to trigger this event again. The specifics of the 'ConversationUpdate' ` +
                `event depends on the channel. You can read more information at https://aka.ms/about-botframework-welcome-user`);
            await context.sendActivity(`You can use the activity's 'locale' property to welcome the user ` +
                `using the locale received from the channel. ` +
                `If you are using the Emulator, you can set this value in Settings. ` +
                `Current locale is '${ context.activity.locale }'`);
            await context.sendActivity(`It is a good pattern to use this event to send general greeting to user, explaining what your bot can do. ` +
                `In this example, the bot handles 'hello', 'hi', 'help' and 'intro'. ` +
                `Try it now, type 'hi'`);
        }
    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

In WelcomeUserBot controleren we op een activiteitsupdate om onMembersAdded() te zien of er een nieuwe gebruiker is toegevoegd aan het gesprek en vervolgens een set van drie eerste welkomstberichten WELCOME_MESSAGEte verzenden, INFO_MESSAGE en PATTERN_MESSAGE. Volledige code voor deze interactie wordt hieronder weergegeven.

WelcomeUserBot.java

public class WelcomeUserBot extends ActivityHandler {
    // Messages sent to the user.
    private static final String WELCOME_MESSAGE =
        "This is a simple Welcome Bot sample. This bot will introduce you "
            + "to welcoming and greeting users. You can say 'intro' to see the "
            + "introduction card. If you are running this bot in the Bot Framework "
            + "Emulator, press the 'Start Over' button to simulate user joining "
            + "a bot or a channel";

    private static final String INFO_MESSAGE =
        "You are seeing this message because the bot received at least one "
            + "'ConversationUpdate' event, indicating you (and possibly others) "
            + "joined the conversation. If you are using the emulator, pressing "
            + "the 'Start Over' button to trigger this event again. The specifics "
            + "of the 'ConversationUpdate' event depends on the channel. You can "
            + "read more information at: " + "https://aka.ms/about-botframework-welcome-user";

    private String localeMessage =
        "You can use the activity's GetLocale() method to welcome the user "
            + "using the locale received from the channel. "
            + "If you are using the Emulator, you can set this value in Settings.";

    private static final String PATTERN_MESSAGE =
        "It is a good pattern to use this event to send general greeting"
            + "to user, explaining what your bot can do. In this example, the bot "
            + "handles 'hello', 'hi', 'help' and 'intro'. Try it now, type 'hi'";

@Override
protected CompletableFuture<Void> onMembersAdded(
    List<ChannelAccount> membersAdded,
    TurnContext turnContext
) {
    return membersAdded.stream()
        .filter(
            member -> !StringUtils
                .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
        )
        .map(
            channel -> turnContext
                .sendActivities(
                    MessageFactory.text(
                        "Hi there - " + channel.getName() + ". " + WELCOME_MESSAGE
                    ),
                    MessageFactory.text(INFO_MESSAGE),
                    MessageFactory.text(
                        localeMessage
                        + " Current locale is " + turnContext.getActivity().getLocale() + "."),
                    MessageFactory.text(PATTERN_MESSAGE)
                )
        )
        .collect(CompletableFutures.toFutureList())
        .thenApply(resourceResponses -> null);
}

De on_members_added_activity controles om te zien of een nieuwe gebruiker is toegevoegd en verzendt vervolgens drie eerste welkomstberichten: een welkomstbericht, een informatiebericht en een patroonbericht.

bots/welcome-user-bot.py

"""
Greet when users are added to the conversation.
Note that all channels do not send the conversation update activity.
If you find that this bot works in the emulator, but does not in
another channel the reason is most likely that the channel does not
send this activity.
"""
for member in members_added:
    if member.id != turn_context.activity.recipient.id:
        await turn_context.send_activity(
            f"Hi there { member.name }. " + self.WELCOME_MESSAGE
        )

        await turn_context.send_activity(self.INFO_MESSAGE)

        await turn_context.send_activity(
            f"{ self.LOCALE_MESSAGE } Current locale is { turn_context.activity.locale }."
        )

        await turn_context.send_activity(self.PATTERN_MESSAGE)

Nieuwe gebruiker verwelkomen en initiële invoer negeren

Het is ook belangrijk om te overwegen wanneer de invoer van uw gebruiker nuttige informatie kan bevatten. Dit kan per kanaal variëren. Om ervoor te zorgen dat uw gebruiker een goede ervaring heeft met alle mogelijke kanalen, controleren we de statusvlag didBotWelcomeUser en als dit onwaar is, verwerken we de initiële gebruikersinvoer niet. In plaats daarvan geven we de gebruiker een eerste welkomstbericht. De bool welcomedUserProperty wordt vervolgens ingesteld op 'true', opgeslagen in UserState en onze code verwerkt nu de invoer van deze gebruiker van alle aanvullende berichtactiviteiten.

Bots\WelcomeUserBot.cs

{
    var welcomeUserStateAccessor = _userState.CreateProperty<WelcomeUserState>(nameof(WelcomeUserState));
    var didBotWelcomeUser = await welcomeUserStateAccessor.GetAsync(turnContext, () => new WelcomeUserState(), cancellationToken);

    if (didBotWelcomeUser.DidBotWelcomeUser == false)
    {
        didBotWelcomeUser.DidBotWelcomeUser = true;

        // the channel should sends the user name in the 'From' object
        var userName = turnContext.Activity.From.Name;

        await turnContext.SendActivityAsync("You are seeing this message because this was your first message ever to this bot.", cancellationToken: cancellationToken);
        await turnContext.SendActivityAsync($"It is a good practice to welcome the user and provide personal greeting. For example, welcome {userName}.", cancellationToken: cancellationToken);
    }
    else

    await _userState.SaveChangesAsync(turnContext, cancellationToken: cancellationToken);
}

Het is ook belangrijk om te overwegen wanneer de invoer van uw gebruiker nuttige informatie kan bevatten. Dit kan per kanaal variëren. Om ervoor te zorgen dat uw gebruiker een goede ervaring heeft met alle mogelijke kanalen, controleren we de eigenschap didBotWelcomedUser, als deze niet bestaat, stellen we deze in op 'false' en verwerken we de initiële gebruikersinvoer niet. In plaats daarvan geven we de gebruiker een eerste welkomstbericht. De bool didBotWelcomeUser wordt vervolgens ingesteld op 'true' en onze code verwerkt de gebruikersinvoer van alle aanvullende berichtactiviteiten.

bots/welcomeBot.js

this.onMessage(async (context, next) => {
    // Read UserState. If the 'DidBotWelcomedUser' does not exist (first time ever for a user)
    // set the default to false.
    const didBotWelcomedUser = await this.welcomedUserProperty.get(context, false);

    // Your bot should proactively send a welcome message to a personal chat the first time
    // (and only the first time) a user initiates a personal chat with your bot.
    if (didBotWelcomedUser === false) {
        // The channel should send the user name in the 'From' object
        const userName = context.activity.from.name;
        await context.sendActivity('You are seeing this message because this was your first message ever sent to this bot.');
        await context.sendActivity(`It is a good practice to welcome the user and provide personal greeting. For example, welcome ${ userName }.`);

        // Set the flag indicating the bot handled the user's first message.
        await this.welcomedUserProperty.set(context, true);
    } else {

    }

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Het is belangrijk om te overwegen wanneer de invoer van uw gebruiker nuttige informatie kan bevatten, die voor elk kanaal kan variëren. Om ervoor te zorgen dat uw gebruiker een goede ervaring heeft met alle mogelijke kanalen, controleren we de statusvlag getDidBotWelcomeUser en als dit onwaar is, verwerken we de initiële gebruikersinvoer niet. In plaats daarvan geven we de gebruiker een eerste welkomstbericht. De bool setDidBotWelcomeUser wordt vervolgens ingesteld op 'true', opgeslagen in UserState en onze code verwerkt nu de invoer van deze gebruiker van alle aanvullende berichtactiviteiten.

WelcomeUserBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from UserState.
    StatePropertyAccessor<WelcomeUserState> stateAccessor =
        userState.createProperty("WelcomeUserState");
    CompletableFuture<WelcomeUserState> stateFuture =
        stateAccessor.get(turnContext, WelcomeUserState::new);

    return stateFuture.thenApply(thisUserState -> {
        if (!thisUserState.getDidBotWelcomeUser()) {
            thisUserState.setDidBotWelcomeUser(true);

            // the channel should send the user name in the 'from' object
            String userName = turnContext.getActivity().getFrom().getName();
            return turnContext
                .sendActivities(
                    MessageFactory.text(FIRST_WELCOME_ONE),
                    MessageFactory.text(String.format(FIRST_WELCOME_TWO, userName))
                );

// Save any state changes. 
.thenApply(response -> userState.saveChanges(turnContext))

Het is ook belangrijk om te overwegen wanneer de invoer van de gebruiker nuttige informatie kan bevatten. Dit kan per kanaal verschillen. Controleert de did_welcome_user eigenschap om ervoor te zorgen dat de gebruiker een goede ervaring heeft met alle mogelijke kanalenon_message_activity. De eerste keer wordt deze ingesteld op false en wordt de invoer van de gebruiker niet verwerkt. In plaats daarvan krijgt de gebruiker een eerste welkomstbericht. Vervolgens wordt ingesteld did_welcome_user op waar en verwerkt de gebruikersinvoer van alle aanvullende berichtactiviteiten.

bots/welcome-user-bot.py

if not welcome_user_state.did_welcome_user:
    welcome_user_state.did_welcome_user = True

    await turn_context.send_activity(
        "You are seeing this message because this was your first message ever to this bot."
    )

    name = turn_context.activity.from_property.name
    await turn_context.send_activity(
        f"It is a good practice to welcome the user and provide personal greeting. For example: Welcome {name}"
    )

Aanvullende invoer verwerken

Zodra een nieuwe gebruiker is verwelkomd, wordt gebruikersinvoergegevens geëvalueerd voor elke berichtwisseling en geeft de bot een antwoord op basis van de context van die gebruikersinvoer. De volgende code toont de beslissingslogica die wordt gebruikt om dat antwoord te genereren.

Een invoer van 'intro' of 'help' roept de functie SendIntroCardAsync aan om de gebruiker te presenteren met een informatieve hero-kaart. Deze code wordt onderzocht in de volgende sectie van dit artikel.

Bots\WelcomeUserBot.cs

    switch (text)
    {
        case "hello":
        case "hi":
            await turnContext.SendActivityAsync($"You said {text}.", cancellationToken: cancellationToken);
            break;
        case "intro":
        case "help":
            await SendIntroCardAsync(turnContext, cancellationToken);
            break;
        default:
            await turnContext.SendActivityAsync(WelcomeMessage, cancellationToken: cancellationToken);
            break;
    }
}

Een invoer van 'intro' of 'help' gebruikt CardFactory om de gebruiker te presenteren met een adaptieve introkaart. Deze code wordt onderzocht in de volgende sectie van dit artikel.

bots/welcomeBot.js

// This example uses an exact match on user's input utterance.
// Consider using LUIS or QnA for Natural Language Processing.
const text = context.activity.text.toLowerCase();
switch (text) {
case 'hello':
case 'hi':
    await context.sendActivity(`You said "${ context.activity.text }"`);
    break;
case 'intro':
case 'help':
    await this.sendIntroCard(context);
    break;
default:
    await context.sendActivity(`This is a simple Welcome Bot sample. You can say 'intro' to
                                    see the introduction card. If you are running this bot in the Bot
                                    Framework Emulator, press the 'Start Over' button to simulate user joining a bot or a channel`);
}

Een invoer van 'intro' of 'help' roept de functie sendIntroCard aan om de gebruiker te presenteren met een informatieve hero-kaart. Deze code wordt onderzocht in de volgende sectie van dit artikel.

WelcomeUserBot.java

// This example hardcodes specific utterances. 
// You should use LUIS or QnA for more advance language understanding.
String text = turnContext.getActivity().getText().toLowerCase();
switch (text) {
    case "hello":
    case "hi":
        return turnContext.sendActivities(MessageFactory.text("You said " + text));

    case "intro":
    case "help":
        return sendIntroCard(turnContext);

    default:
        return turnContext.sendActivity(WELCOME_MESSAGE);
}

De invoer van een gebruiker van intro of hulp zorgt ervoor dat de bot wordt aangeroepen __send_intro_card, waarmee de gebruiker een adaptieve introkaart krijgt.

bots/welcome-user-bot.py

if text in ("hello", "hi"):
    await turn_context.send_activity(f"You said { text }")
elif text in ("intro", "help"):
    await self.__send_intro_card(turn_context)
else:
    await turn_context.send_activity(self.WELCOME_MESSAGE)

Een begroeting voor herokaarten gebruiken

Zoals hierboven vermeld, genereren sommige gebruikersinvoer een Hero-kaart als reactie op hun aanvraag. Hier vindt u meer informatie over heldkaartwensen : Een inleidingskaart verzenden. Hieronder vindt u de code die nodig is om het antwoord op de herokaart van deze bot te maken.

Bots\WelcomeUserBot.cs

    {
        var card = new HeroCard
        {
            Title = "Welcome to Bot Framework!",
            Text = @"Welcome to Welcome Users bot sample! This Introduction card
                     is a great way to introduce your Bot to the user and suggest
                     some things to get them started. We use this opportunity to
                     recommend a few next steps for learning more creating and deploying bots.",
            Images = new List<CardImage>() { new CardImage("https://aka.ms/bf-welcome-card-image") },
            Buttons = new List<CardAction>()
            {
                new CardAction(ActionTypes.OpenUrl, "Get an overview", null, "Get an overview", "Get an overview", "https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0"),
                new CardAction(ActionTypes.OpenUrl, "Ask a question", null, "Ask a question", "Ask a question", "https://stackoverflow.com/questions/tagged/botframework"),
                new CardAction(ActionTypes.OpenUrl, "Learn how to deploy", null, "Learn how to deploy", "Learn how to deploy", "https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0"),
            }
        };

        var response = MessageFactory.Attachment(card.ToAttachment());
        await turnContext.SendActivityAsync(response, cancellationToken);
    }
}

bots/welcomeBot.js

async sendIntroCard(context) {
    const card = CardFactory.heroCard(
        'Welcome to Bot Framework!',
        'Welcome to Welcome Users bot sample! This Introduction card is a great way to introduce your Bot to the user and suggest some things to get them started. We use this opportunity to recommend a few next steps for learning more creating and deploying bots.',
        ['https://aka.ms/bf-welcome-card-image'],
        [
            {
                type: ActionTypes.OpenUrl,
                title: 'Get an overview',
                value: 'https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0'
            },
            {
                type: ActionTypes.OpenUrl,
                title: 'Ask a question',
                value: 'https://stackoverflow.com/questions/tagged/botframework'
            },
            {
                type: ActionTypes.OpenUrl,
                title: 'Learn how to deploy',
                value: 'https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0'
            }
        ]
    );

    await context.sendActivity({ attachments: [card] });
}

WelcomeUserBot.java

private CompletableFuture<ResourceResponse> sendIntroCard(TurnContext turnContext) {
    HeroCard card = new HeroCard();
    card.setTitle("Welcome to Bot Framework!");
    card.setText(
        "Welcome to Welcome Users bot sample! This Introduction card "
            + "is a great way to introduce your Bot to the user and suggest "
            + "some things to get them started. We use this opportunity to "
            + "recommend a few next steps for learning more creating and deploying bots."
    );

    CardImage image = new CardImage();
    image.setUrl("https://aka.ms/bf-welcome-card-image");

    card.setImages(Collections.singletonList(image));

    CardAction overviewAction = new CardAction();
    overviewAction.setType(ActionTypes.OPEN_URL);
    overviewAction.setTitle("Get an overview");
    overviewAction.setText("Get an overview");
    overviewAction.setDisplayText("Get an overview");
    overviewAction.setValue(
        "https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0"
    );

    CardAction questionAction = new CardAction();
    questionAction.setType(ActionTypes.OPEN_URL);
    questionAction.setTitle("Ask a question");
    questionAction.setText("Ask a question");
    questionAction.setDisplayText("Ask a question");
    questionAction.setValue("https://stackoverflow.com/questions/tagged/botframework");

    CardAction deployAction = new CardAction();
    deployAction.setType(ActionTypes.OPEN_URL);
    deployAction.setTitle("Learn how to deploy");
    deployAction.setText("Learn how to deploy");
    deployAction.setDisplayText("Learn how to deploy");
    deployAction.setValue(
        "https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0"
    );
    card.setButtons(Arrays.asList(overviewAction, questionAction, deployAction));

    Activity response = MessageFactory.attachment(card.toAttachment());
    return turnContext.sendActivity(response);
}

bots/welcome-user-bot.py

async def __send_intro_card(self, turn_context: TurnContext):
    card = HeroCard(
        title="Welcome to Bot Framework!",
        text="Welcome to Welcome Users bot sample! This Introduction card "
        "is a great way to introduce your Bot to the user and suggest "
        "some things to get them started. We use this opportunity to "
        "recommend a few next steps for learning more creating and deploying bots.",
        images=[CardImage(url="https://aka.ms/bf-welcome-card-image")],
        buttons=[
            CardAction(
                type=ActionTypes.open_url,
                title="Get an overview",
                text="Get an overview",
                display_text="Get an overview",
                value="https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0",
            ),
            CardAction(
                type=ActionTypes.open_url,
                title="Ask a question",
                text="Ask a question",
                display_text="Ask a question",
                value="https://stackoverflow.com/questions/tagged/botframework",
            ),
            CardAction(
                type=ActionTypes.open_url,
                title="Learn how to deploy",
                text="Learn how to deploy",
                display_text="Learn how to deploy",
                value="https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0",
            ),
        ],
    )

    return await turn_context.send_activity(
        MessageFactory.attachment(CardFactory.hero_card(card))
    )

De bot testen

De nieuwste Bot Framework Emulator downloaden en installeren

Voer het voorbeeld lokaal uit op uw computer. Als u instructies nodig hebt, raadpleegt u het bestand voor het README C#-voorbeeld of JavaScript-voorbeeld.
Open de emulator om uw bot te testen.
1. Wanneer u een gesprek met uw bot start, ontvangt u een reeks welkomstberichten.
2. Wanneer u de eerste keer een 'hallo'-bericht verzendt, reageert uw bot met advies.
3. Wanneer u volgende 'hallo'-berichten verzendt, antwoordt uw bot met 'U zei hallo'.
4. Verzend een help-bericht naar uw bot. Het reageert door een herokaart te verzenden.

Aanvullende resources

Meer informatie over verschillende mediareacties in Media toevoegen aan berichten.

Volgende stappen

Gebruikersinvoer verzamelen

Delen via

Welkomstbericht verzenden naar gebruikers

Vereisten

Over deze voorbeeldcode

Gebruikersstatus maken

Eigenschapstoegangsors maken

Nieuw verbonden gebruikers detecteren en begroeten

Nieuwe gebruiker verwelkomen en initiële invoer negeren

Aanvullende invoer verwerken

Een begroeting voor herokaarten gebruiken

De bot testen

Aanvullende resources

Volgende stappen

Aanvullende resources