Mengirim pemberitahuan proaktif kepada pengguna

BERLAKU UNTUK: SDK v4

Biasanya, bot mengirim pesan kepada pengguna secara langsung sebagai respons untuk menerima pesan dari pengguna. Terkadang, bot mungkin perlu mengirim pesan proaktif, pesan sebagai respons terhadap stimulus yang tidak berasal dari pengguna.

Pesan proaktif dapat berguna dalam berbagai skenario. Misalnya, jika pengguna sebelumnya telah meminta bot untuk memantau harga produk, bot dapat memperingatkan pengguna jika harga produk telah turun sebesar 20%. Atau, jika bot memerlukan beberapa waktu untuk mengompilasi respons terhadap pertanyaan pengguna, bot dapat memberi tahu pengguna tentang penundaan dan memungkinkan percakapan untuk melanjutkan sementara itu. Ketika bot selesai mengompilasi respons terhadap pertanyaan, bot akan membagikan informasi tersebut dengan pengguna.

Artikel ini membahas informasi tentang pesan proaktif untuk bot secara umum. Untuk informasi tentang pesan proaktif di Microsoft Teams, lihat

• Sampel bot percakapan Teams di C#, JavaScript, Java, atau Python.
• Dokumentasi Microsoft Teams tentang cara mengirim pesan proaktif.

Catatan

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Microsoft Copilot Studio dan baca tentang memilih solusi salinan yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

Prasyarat

• Memahami dasar-dasar bot.
• Salinan sampel pesan proaktif di C#, JavaScript, Java, atau Python. Sampel digunakan untuk menjelaskan olahpesan proaktif dalam artikel ini.

Tentang sampel proaktif

Secara umum, bot sebagai aplikasi memiliki beberapa lapisan:

• Aplikasi web yang dapat menerima permintaan HTTP dan secara khusus mendukung titik akhir olahpesan.
• Adaptor yang menangani konektivitas dengan saluran.
• Handler untuk giliran, biasanya dienkapsulasi di kelas bot yang menangani penalaran percakapan untuk aplikasi bot.

Sebagai respons terhadap pesan masuk dari pengguna, aplikasi memanggil metode aktivitas proses adaptor, yang membuat konteks giliran dan giliran, memanggil alur middleware-nya, dan kemudian memanggil handler giliran bot.

Untuk memulai pesan proaktif, aplikasi bot harus dapat menerima input lain. Logika aplikasi untuk memulai pesan proaktif berada di luar cakupan SDK. Untuk sampel ini, titik akhir pemberitahuan, selain titik akhir pesan standar, digunakan untuk memicu giliran proaktif.

Sebagai respons terhadap permintaan GET pada titik akhir pemberitahuan ini, aplikasi memanggil metode percakapan lanjutan adaptor, yang berperilaku mirip dengan metode aktivitas proses. Metode lanjutkan percakapan :

• Mengambil referensi percakapan yang sesuai untuk pengguna dan metode panggilan balik yang digunakan untuk giliran proaktif.
• Membuat aktivitas peristiwa dan mengubah konteks untuk giliran proaktif.
• Memanggil alur middleware adapter.
• Memanggil metode panggilan balik yang disediakan.
• Konteks giliran menggunakan referensi percakapan untuk mengirim pesan apa pun kepada pengguna.

Sampel memiliki bot, titik akhir pesan, dan titik akhir tambahan yang digunakan untuk mengirim pesan proaktif kepada pengguna, seperti yang ditunjukkan dalam ilustrasi berikut.

Mengambil dan menyimpan referensi percakapan

Saat Emulator Kerangka Kerja Bot terhubung ke bot, bot menerima dua aktivitas pembaruan percakapan. Di penanganan aktivitas pembaruan percakapan bot, referensi percakapan diambil dan disimpan dalam kamus seperti yang ditunjukkan di bawah ini.

C#

Bot\ProactiveBot.cs

private void AddConversationReference(Activity activity)
{
    var conversationReference = activity.GetConversationReference();
    _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
}

protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    AddConversationReference(turnContext.Activity as Activity);

    return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
}

JavaScript

bot/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

Java

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

Python

bot/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

Referensi percakapan menyertakan properti percakapan yang menjelaskan percakapan tempat aktivitas ada. Percakapan menyertakan properti pengguna yang mencantumkan pengguna yang berpartisipasi dalam percakapan, dan properti URL layanan yang menunjukkan tempat balasan aktivitas saat ini dapat dikirim. Referensi percakapan yang valid diperlukan untuk mengirim pesan proaktif kepada pengguna. (Untuk saluran Teams, URL layanan memetakan ke server regional.)

Catatan

Dalam skenario dunia nyata, Anda akan mempertahankan referensi percakapan dalam database alih-alih menggunakan objek dalam memori.

Mengirim pesan proaktif

Pengontrol kedua, pengontrol pemberitahuan , bertanggung jawab untuk mengirim pesan proaktif kepada pengguna. Ini menggunakan langkah-langkah berikut untuk menghasilkan pesan proaktif.

1. Mengambil referensi untuk percakapan yang akan dikirimi pesan proaktif.
2. Memanggil metode lanjutkan percakapan adaptor, menyediakan referensi percakapan dan delegasi pengatur giliran untuk digunakan. (Metode lanjutan percakapan menghasilkan konteks giliran untuk percakapan yang direferensikan lalu memanggil delegasi pengatur giliran yang ditentukan.)
3. Di delegasi, menggunakan konteks giliran untuk mengirim pesan proaktif. Di sini, delegasi ditentukan pada pengontrol pemberitahuan, dan mengirimkan pesan proaktif kepada pengguna.

Catatan

Meskipun setiap saluran harus menggunakan URL layanan yang stabil, URL dapat berubah dari waktu ke waktu. Untuk informasi selengkapnya tentang URL layanan, lihat bagian Struktur aktivitas dasar dan URL Layanan dari Skema Aktivitas Kerangka Kerja Bot.

Jika URL layanan berubah, referensi percakapan sebelumnya tidak akan lagi valid dan panggilan untuk melanjutkan percakapan akan menghasilkan kesalahan atau pengecualian. Dalam hal ini, bot Anda harus memperoleh referensi percakapan baru untuk pengguna sebelum dapat mengirim pesan proaktif lagi.

C#

Pengontrol\NotifyController .cs

Setiap kali halaman pemberitahuan bot diminta, pengontrol pemberitahuan mengambil referensi percakapan dari kamus. Pengontrol kemudian menggunakan ContinueConversationAsync metode dan BotCallback untuk mengirim pesan proaktif.

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

JavaScript

index.js

Setiap kali halaman server /api/notify diminta, server mengambil referensi percakapan dari kamus. Server kemudian menggunakan continueConversation metode untuk mengirim pesan proaktif. Parameter untuk continueConversation adalah fungsi yang berfungsi sebagai handler giliran bot untuk giliran ini.

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Java

NotifyController.java

Setiap kali halaman pemberitahuan bot diminta, pengontrol pemberitahuan mengambil referensi percakapan dari kamus. Pengontrol kemudian menggunakan continueConversation metode untuk mengirim pesan proaktif.

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

Python

Setiap kali halaman pemberitahuan bot diminta, server mengambil referensi percakapan dari kamus. Server kemudian menggunakan _send_proactive_message untuk mengirim pesan proaktif.

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

Untuk mengirim pesan proaktif, adaptor memerlukan ID aplikasi untuk bot. Di lingkungan produksi, Anda dapat menggunakan ID aplikasi bot. Untuk menguji bot secara lokal dengan Emulator, Anda dapat menggunakan string kosong ("").

Menguji bot

1. Jika Anda belum melakukannya, instal Bot Framework Emulator.
2. Jalankan sampel secara lokal di komputer Anda.
3. Mulai Emulator dan sambungkan ke bot Anda.
4. Muat ke halaman api/pemberitahuan bot Anda. Ini akan menghasilkan pesan proaktif di Emulator.

Informasi Tambahan

Persyaratan

Sebelum Anda dapat mengirim pesan proaktif, bot Anda memerlukan referensi percakapan. Bot Anda dapat mengambil referensi percakapan dari aktivitas apa pun yang diterimanya dari pengguna, tetapi ini biasanya mengharuskan pengguna untuk berinteraksi dengan bot setidaknya sekali sebelum bot dapat mengirim pesan proaktif.

Banyak saluran melarang bot mengirim pesan kepada pengguna kecuali pengguna telah mengirim pesan kepada bot setidaknya sekali. Beberapa saluran mengizinkan pengecualian. Misalnya, saluran Teams memungkinkan bot Anda mengirim pesan proaktif (atau 1-on-1) kepada individu dalam percakapan grup yang sudah dibuat yang menyertakan bot.

Pertimbangan Desain

Saat menerapkan pesan proaktif di bot Anda, jangan mengirim beberapa pesan proaktif dalam waktu singkat. Beberapa saluran memberlakukan pembatasan pada seberapa sering bot dapat mengirim pesan kepada pengguna, dan akan menonaktifkan bot jika melanggar batasan tersebut.

Untuk jenis pesan proaktif yang paling sederhana, bot menyuntikkan pesan ke dalam percakapan saat dipicu, tanpa memperhatikan status atau topik percakapan saat ini. Dalam skenario ini, pesan proaktif mengganggu alur percakapan normal.

Untuk menangani pemberitahuan dengan lebih lancar, pertimbangkan cara lain untuk mengintegrasikan pemberitahuan ke dalam alur percakapan, seperti mengatur bendera dalam status percakapan atau menambahkan pemberitahuan ke antrean.

Tentang giliran proaktif

Metode lanjutkan percakapan menggunakan referensi percakapan dan penangan panggilan balik untuk:

1. Buat giliran di mana aplikasi bot dapat mengirim pesan proaktif. Adaptor membuat event aktivitas untuk giliran ini, dengan namanya diatur ke "ContinueConversation".
2. Kirim belokan melalui alur middleware adapter.
3. Panggil handler panggilan balik untuk melakukan logika kustom.

Dalam sampel pesan proaktif, penangan panggilan balik didefinisikan dalam pengontrol pemberitahuan dan mengirim pesan langsung ke percakapan, tanpa mengirim aktivitas proaktif melalui handler giliran normal bot. Kode sampel juga tidak mengakses atau memperbarui status bot pada giliran proaktif.

Banyak bot yang stateful dan menggunakan status untuk mengelola percakapan selama beberapa giliran. Ketika metode percakapan lanjutan membuat konteks giliran, gilirannya akan memiliki status pengguna dan percakapan yang benar yang terkait dengannya, dan Anda dapat mengintegrasikan perubahan proaktif ke logika bot Anda. Jika Anda memerlukan logika bot untuk mengetahui pesan proaktif, Anda memiliki beberapa opsi untuk melakukannya. Anda dapat:

• Berikan handler giliran bot sebagai handler panggilan balik. Bot kemudian akan menerima aktivitas peristiwa "ContinueConversation".
• Gunakan handler panggilan balik untuk menambahkan informasi ke konteks giliran terlebih dahulu, lalu panggil handler giliran bot.

Dalam kedua kasus ini, Anda harus merancang logika bot Untuk menangani peristiwa proaktif.

Langkah berikutnya

Menerapkan alur percakapan berurutan