Wysyłanie wiadomości powitalnej do użytkowników

DOTYCZY: ZESTAW SDK w wersji 4

Głównym celem tworzenia dowolnego bota jest angażowanie użytkownika w zrozumiałą konwersację. Jednym z najlepszych sposobów osiągnięcia tego celu jest upewnienie się, że od momentu, gdy użytkownik po raz pierwszy nawiązuje połączenie, rozumie główne przeznaczenie i możliwości bota, przyczynę utworzenia bota. Ten artykuł zawiera przykłady kodu ułatwiające powitanie użytkowników bota.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowych botów rozważ użycie programu Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilot.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

• Poznaj podstawy bota.
• Kopia przykładowego użytkownika powitalnego w przykładzie w języku C# Sample, JS Sample, Java Sample lub Python Sample. Kod z przykładu służy do wyjaśnienia sposobu wysyłania wiadomości powitalnych.

Informacje o tym przykładowym kodzie

Ten przykładowy kod pokazuje, jak wykrywać i powitać nowych użytkowników, gdy są oni początkowo połączeni z botem. Na poniższym diagramie przedstawiono przepływ logiki dla tego bota.

C#

Dwa główne zdarzenia napotkane przez bota to:

• OnMembersAddedAsync, wywoływany, gdy nowy użytkownik nawiązuje połączenie z botem.
• OnMessageActivityAsync, wywoływany, gdy bot otrzymuje nowe dane wejściowe użytkownika.

Za każdym razem, gdy nowy użytkownik jest połączony, otrzymuje element WelcomeMessage, InfoMessagei PatternMessage przez bota. Po odebraniu nowych danych wejściowych użytkownika jest sprawdzana wartość WelcomeUserState, aby sprawdzić, czy DidBotWelcomeUser ustawiono wartość true. W przeciwnym razie do użytkownika zostanie zwrócona początkowa wiadomość powitalna użytkownika.

JavaScript

Dwa główne zdarzenia napotkane przez bota to:

• onMembersAdded, wywoływany, gdy nowy użytkownik nawiązuje połączenie z botem.
• onMessage, wywoływany, gdy bot otrzymuje nowe dane wejściowe użytkownika.

Za każdym razem, gdy nowy użytkownik jest połączony, otrzymuje element welcomeMessage, infoMessagei patternMessage przez bota. Po odebraniu nowych danych wejściowych użytkownika jest sprawdzana wartość , aby sprawdzić, welcomedUserProperty czy ustawiono wartość truedidBotWelcomeUser. W przeciwnym razie do użytkownika zostanie zwrócona początkowa wiadomość powitalna użytkownika. Jeśli DidBotWelcomeUser wartość ma wartość true, dane wejściowe użytkownika są oceniane. Na podstawie zawartości danych wejściowych użytkownika ten bot wykona jedną z następujących czynności:

• Powtórz powitanie odebrane od użytkownika.
• Wyświetlanie karty hero zawierającej dodatkowe informacje o botach.
• WelcomeMessage Wyślij ponownie objaśnienie oczekiwanych danych wejściowych dla tego bota.

Java

Dwa główne zdarzenia napotkane przez bota to:

• onMembersAdded, wywoływany, gdy nowy użytkownik nawiązuje połączenie z botem.
• onMessageActivity, wywoływany, gdy bot otrzymuje nowe dane wejściowe użytkownika.

Za każdym razem, gdy nowy użytkownik jest połączony, otrzymuje element WELCOME_MESSAGE, INFO_MESSAGEi PATTERN_MESSAGE przez bota. Po odebraniu nowych danych wejściowych użytkownika jest sprawdzana wartość WelcomeUserState, aby sprawdzić, czy getDidBotWelcomeUser() ustawiono wartość true. W przeciwnym razie do użytkownika zostanie zwrócona początkowa wiadomość powitalna użytkownika.

Python

Dwa główne zdarzenia napotkane przez bota to:

• on_members_added_activity, wywoływany, gdy nowy użytkownik nawiązuje połączenie z botem.
• on_message_activity, wywoływany, gdy bot otrzymuje nowe dane wejściowe użytkownika.

Za każdym razem, gdy nowy użytkownik jest połączony, otrzymuje wiadomość powitalną, komunikat informacyjny i komunikat wzorca przez bota. Po odebraniu nowych danych wejściowych użytkownika właściwość jest zaznaczona welcome_user_state.did_welcome_user . Jeśli nie ustawiono wartości true, do użytkownika zostanie zwrócona początkowa wiadomość powitalna użytkownika. Jeśli jest ustawiona wartość true, na podstawie zawartości danych wejściowych użytkownika ten bot wykona jedną z następujących czynności:

• Powtórz powitanie odebrane od użytkownika.
• Wyświetlanie karty hero zawierającej dodatkowe informacje o botach.

Tworzenie stanu użytkownika

C#

Obiekt stanu użytkownika jest tworzony podczas uruchamiania i zależność wstrzykiwana do konstruktora bota.

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.

Boty\WelcomeUserBot.cs

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

JavaScript

Podczas uruchamiania stan użytkownika jest definiowany i index.js używany przez konstruktora bota.

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');

Java

Obiekt stanu użytkownika jest tworzony podczas uruchamiania i zależność wstrzykiwana do konstruktora bota przez kontener Spring.

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

Python

Podczas uruchamiania stan użytkownika jest definiowany i app.py używany przez konstruktora bota.

app.py

# Create the Bot
BOT = WelcomeUserBot(USER_STATE)


# Listen for incoming requests on /api/messages.

Tworzenie metod dostępu do właściwości

C#

Teraz utworzymy metodę dostępu do właściwości, która udostępnia nam uchwyt wewnątrz WelcomeUserState OnMessageActivityAsync metody. Następnie wywołaj metodę , GetAsync aby uzyskać prawidłowy klucz o określonym zakresie. Następnie zapisujemy dane stanu użytkownika po każdej iteracji wejściowej SaveChangesAsync użytkownika przy użyciu metody .

Bots\WelcomeUserState.cs

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

Boty\WelcomeUserBot.cs

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

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

JavaScript

Teraz utworzymy metodę dostępu do właściwości, która udostępnia nam uchwyt powitanyUserProperty, który jest utrwalany w obrębie userState.

boty/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);
}

Java

Teraz utworzymy metodę dostępu do właściwości, która udostępnia nam uchwyt wewnątrz WelcomeUserState onMessageActivity metody. Następnie wywołaj metodę , get aby uzyskać prawidłowy klucz o określonym zakresie. Następnie zapisujemy dane stanu użytkownika po każdej iteracji wejściowej saveChanges użytkownika przy użyciu metody .

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

Python

Ten przykład tworzy metodę dostępu do właściwości stanu konwersacji , user_state_accessorw konstruktorze bota.

boty/welcome-user-bot.py

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

Używa metody dostępu właściwości w procedurze on_message_activity obsługi i zastępuje on_turn program obsługi w celu zapisania stanu przed końcem kolei.

# 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)

Wykrywanie i witanie nowo połączonych użytkowników

C#

W aplikacji WelcomeUserBot sprawdzamy aktualizację działania przy użyciu polecenia OnMembersAddedAsync() , aby sprawdzić, czy nowy użytkownik został dodany do konwersacji, a następnie wysyłamy im zestaw trzech początkowych wiadomości WelcomeMessagepowitalnych i InfoMessage PatternMessage. Poniżej przedstawiono kompletny kod dla tej interakcji.

Boty\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);
        }
    }
}

JavaScript

Ten kod JavaScript wysyła początkowe wiadomości powitalne po dodaniu użytkownika. Odbywa się to przez sprawdzenie aktywności konwersacji i sprawdzenie, czy nowy członek został dodany do konwersacji.

boty/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();
});

Java

W aplikacji WelcomeUserBot sprawdzamy aktualizację działania przy użyciu polecenia onMembersAdded() , aby sprawdzić, czy nowy użytkownik został dodany do konwersacji, a następnie wysyłamy im zestaw trzech początkowych wiadomości WELCOME_MESSAGEpowitalnych i INFO_MESSAGE PATTERN_MESSAGE. Poniżej przedstawiono kompletny kod dla tej interakcji.

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

Python

Sprawdza, on_members_added_activity czy nowy użytkownik został dodany, a następnie wysyła trzy początkowe wiadomości powitalne: komunikat powitalny, komunikat informacyjny i komunikat wzorca.

boty/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)

Powitanie nowego użytkownika i odrzucenie początkowych danych wejściowych

C#

Ważne jest również, aby wziąć pod uwagę, kiedy dane wejściowe użytkownika mogą rzeczywiście zawierać przydatne informacje, a to może się różnić w przypadku każdego kanału. Aby upewnić się, że użytkownik ma dobre środowisko we wszystkich możliwych kanałach, sprawdzamy flagę stanu nieBotWelcomeUser , a jeśli jest to "false", nie przetwarzamy początkowych danych wejściowych użytkownika. Zamiast tego udostępniamy użytkownikowi początkową wiadomość powitalną. Wartość logiczna powitanaUserProperty jest następnie ustawiona na wartość "true", przechowywaną w parametrze UserState, a nasz kod będzie teraz przetwarzać dane wejściowe tego użytkownika ze wszystkich dodatkowych działań komunikatów.

Boty\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);
}

JavaScript

Ważne jest również, aby wziąć pod uwagę, kiedy dane wejściowe użytkownika mogą rzeczywiście zawierać przydatne informacje, a to może się różnić w przypadku każdego kanału. Aby upewnić się, że użytkownik ma dobre środowisko we wszystkich możliwych kanałach, sprawdzamy właściwość didBotWelcomedUser, jeśli nie istnieje, ustawimy ją na wartość "false" i nie przetwarzamy początkowych danych wejściowych użytkownika. Zamiast tego udostępniamy użytkownikowi początkową wiadomość powitalną. Wartość logiczna didBotWelcomeUser jest następnie ustawiona na wartość "true", a nasz kod przetwarza dane wejściowe użytkownika ze wszystkich dodatkowych działań komunikatów.

boty/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();
});

Java

Ważne jest, aby wziąć pod uwagę, kiedy dane wejściowe użytkownika mogą zawierać przydatne informacje, które mogą się różnić w przypadku każdego kanału. Aby upewnić się, że użytkownik ma dobre środowisko we wszystkich możliwych kanałach, sprawdzamy flagę stanu getDidBotWelcomeUser , a jeśli jest to "false", nie przetwarzamy początkowych danych wejściowych użytkownika. Zamiast tego udostępniamy użytkownikowi początkową wiadomość powitalną. Wartość logiczna setDidBotWelcomeUser jest następnie ustawiona na wartość "true", przechowywaną w parametrze UserState, a nasz kod będzie teraz przetwarzać dane wejściowe tego użytkownika ze wszystkich dodatkowych działań komunikatów.

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))                

Python

Ważne jest również, aby wziąć pod uwagę, kiedy dane wejściowe użytkownika mogą rzeczywiście zawierać przydatne informacje, może się to różnić w przypadku każdego kanału. Aby upewnić się, że użytkownik ma dobre środowisko we wszystkich możliwych kanałach, on_message_activity sprawdza did_welcome_user właściwość . Po raz pierwszy ustawia wartość false i nie przetwarza danych wejściowych użytkownika. Zamiast tego udostępnia użytkownikowi początkową wiadomość powitalną. Następnie ustawia did_welcome_user wartość true i przetwarza dane wejściowe użytkownika ze wszystkich dodatkowych działań komunikatów.

boty/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}"
    )

Przetwarzanie dodatkowych danych wejściowych

Po powitaniu nowego użytkownika informacje wejściowe użytkownika są oceniane dla każdego kolei komunikatu, a bot udostępnia odpowiedź na podstawie kontekstu danych wejściowych tego użytkownika. Poniższy kod przedstawia logikę decyzyjną używaną do generowania tej odpowiedzi.

C#

Dane wejściowe "intro" lub "help" wywołuje funkcję SendIntroCardAsync , aby przedstawić użytkownikowi kartę bohatera informacyjnego. Ten kod jest badany w następnej sekcji tego artykułu.

Boty\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;
    }
}

JavaScript

Dane wejściowe "intro" lub "help" używają metody CardFactory do prezentowania użytkownikowi karty adaptacyjnej intro. Ten kod jest badany w następnej sekcji tego artykułu.

boty/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`);
}

Java

Dane wejściowe "intro" lub "help" wywołuje funkcję sendIntroCard , aby przedstawić użytkownikowi kartę bohatera informacyjnego. Ten kod jest badany w następnej sekcji tego artykułu.

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

Python

Dane wejściowe wprowadzone przez użytkownika lub pomoc powodują wywołanie __send_intro_cardbota , który przedstawia użytkownikowi wprowadzenie karty adaptacyjnej.

boty/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)

Korzystanie z powitania na karcie hero

Jak wspomniano powyżej, niektóre dane wejściowe użytkownika generują kartę Hero w odpowiedzi na żądanie. Więcej informacji na temat powitań kart bohaterów można znaleźć tutaj : Wyślij kartę wprowadzającą. Poniżej znajduje się kod wymagany do utworzenia odpowiedzi na karty hero tego bota.

C#

Boty\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);
    }
}

JavaScript

boty/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] });
}

Java

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

Python

boty/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))
    )

Testowanie bota

Pobierz i zainstaluj najnowszą wersję emulatora platformy Bot Framework

1. Uruchom przykład lokalnie na maszynie. Jeśli potrzebujesz instrukcji, zapoznaj się z plikiem README przykładu języka C# lub przykładu języka JavaScript.
2. Otwórz emulator, aby przetestować bota.

   1. Po rozpoczęciu konwersacji z botem zostanie wysłana seria wiadomości powitalnych.

   2. Po pierwszym wysłaniu komunikatu "hello" bot odpowiada z poradami.

   3. Po wysłaniu kolejnych komunikatów "hello" bot odpowiada: "Powiedziałeś cześć".

      

   4. Wyślij do bota komunikat "pomoc". Odpowiada, wysyłając kartę bohatera.

      

Dodatkowe zasoby

Dowiedz się więcej o różnych odpowiedziach multimedialnych w temacie Dodawanie multimediów do wiadomości.

Następne kroki

Zbieranie danych wejściowych użytkownika