Bagikan melalui

Mulai cepat: Menambahkan bot ke aplikasi obrolan Anda

  • Artikel

Pelajari cara membangun pengalaman AI percakapan dalam aplikasi obrolan dengan menggunakan saluran pesan Obrolan Azure Communication Services yang tersedia di Azure Bot Service. Dalam mulai cepat ini, Anda membuat bot dengan menggunakan BotFramework SDK. Kemudian, Anda mengintegrasikan bot ke dalam aplikasi obrolan yang Anda buat dengan menggunakan SDK Obrolan Communication Services.

Dalam panduan mulai cepat ini, Anda belajar cara:

Prasyarat

  • Akun Azure dan langganan aktif. Membuat akun secara gratis.
  • Visual Studio 2019 atau versi yang lebih baru.
  • Versi terbaru .NET Core. Dalam mulai cepat ini, kami menggunakan .NET Core 3.1. Pastikan untuk menginstal versi yang sesuai dengan instans Visual Studio, 32-bit, atau 64-bit Anda.
  • SDK kerangka kerja bot

Membuat dan menyebarkan bot di Azure

Untuk menggunakan obrolan Azure Communication Services sebagai saluran di Azure Bot Service, pertama-tama sebarkan bot. Untuk menyebarkan bot, Anda menyelesaikan langkah-langkah berikut:

  • Membuat sumber daya Azure Bot Service
  • Mendapatkan ID aplikasi dan kata sandi bot
  • Membuat aplikasi web untuk menahan logika bot
  • Membuat titik akhir olahpesan untuk bot

Membuat sumber daya Azure Bot Service

Pertama, gunakan portal Azure untuk membuat sumber daya Azure Bot Service. Saluran Obrolan Communication Services mendukung bot penyewa tunggal, bot identitas terkelola, dan bot multi-penyewa. Untuk tujuan mulai cepat ini, kami akan menggunakan bot multi-penyewa .

Untuk menyiapkan bot identitas penyewa tunggal atau terkelola, tinjau Informasi identitas Bot.

Untuk bot identitas terkelola, Anda mungkin harus memperbarui identitas layanan bot.

Mendapatkan ID aplikasi bot dan kata sandi aplikasi

Selanjutnya, dapatkan ID aplikasi Microsoft dan kata sandi yang ditetapkan ke bot Anda saat disebarkan. Anda menggunakan nilai-nilai ini untuk konfigurasi selanjutnya.

Membuat aplikasi web untuk menahan logika bot

Untuk membuat aplikasi web untuk bot, Anda dapat merevisi sampel Bot Builder untuk skenario Anda atau menggunakan Bot Builder SDK untuk membuat aplikasi web. Salah satu sampel yang paling sederhana adalah Echo Bot.

Azure Bot Service biasanya mengharapkan Pengontrol Aplikasi Web Aplikasi Bot untuk mengekspos titik akhir dalam bentuk /api/messages. Titik akhir menangani semua pesan yang dikirim ke bot.

Untuk membuat aplikasi bot, gunakan Azure CLI untuk membuat sumber daya Azure App Service atau membuat aplikasi di portal Azure.

Untuk membuat aplikasi web bot dengan menggunakan portal Azure:

  1. Di portal, pilih Buat sumber daya. Dalam kotak pencarian, masukkan aplikasi web. Pilih petak peta Aplikasi Web.

    Screenshot that shows creating a web app resource in the Azure portal.

  2. Di Buat Aplikasi Web, pilih atau masukkan detail untuk aplikasi, termasuk wilayah tempat Anda ingin menyebarkan aplikasi.

    Screenshot that shows details to set to create a web app deployment.

  3. Pilih Tinjau + Buat untuk memvalidasi penyebaran dan meninjau detail penyebaran. Lalu, pilih Buat.

  4. Saat sumber daya aplikasi web dibuat, salin URL nama host yang ditampilkan dalam detail sumber daya. URL adalah bagian dari titik akhir yang Anda buat untuk aplikasi web.

    Screenshot that shows how to copy the web app endpoint URL.

Membuat titik akhir olahpesan untuk bot

Selanjutnya, di sumber daya bot, buat titik akhir olahpesan aplikasi web:

  1. Di portal Azure, buka sumber daya Azure Bot Anda. Di menu sumber daya, pilih Konfigurasi.

  2. Di Konfigurasi, untuk titik akhir Olahpesan, tempelkan URL nama host aplikasi web yang Anda salin di bagian sebelumnya. Tambahkan URL dengan /api/messages.

  3. Pilih Simpan.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

Menggunakan aplikasi web

Langkah terakhir untuk membuat bot adalah menyebarkan aplikasi web. Untuk mulai cepat ini, gunakan sampel Echo Bot. Fungsionalitas Echo Bot terbatas untuk menggemakan input pengguna. Berikut cara Anda menyebarkannya ke aplikasi web Anda di Azure:

  1. Gunakan Git untuk mengkloning repositori GitHub ini:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. Di Visual Studio, buka proyek Echo Bot.

  3. Di proyek Visual Studio, buka file Appsettings.json . Tempelkan ID aplikasi Microsoft dan kata sandi aplikasi yang Anda salin sebelumnya:

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    Selanjutnya, gunakan bot Visual Studio for C# untuk menyebarkan bot.

    Anda juga dapat menggunakan jendela Prompt Perintah untuk menyebarkan bot Azure.

  4. Di Visual Studio, di Penjelajah Solusi, klik kanan proyek EchoBot dan pilih Terbitkan:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Pilih Baru untuk membuat profil penerbitan baru. Untuk Target, pilih Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Untuk target tertentu, pilih Azure App Service:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. Dalam konfigurasi penyebaran, pilih aplikasi web di hasil yang muncul setelah Anda masuk ke akun Azure Anda. Untuk menyelesaikan profil, pilih Selesai, lalu pilih Terbitkan untuk memulai penyebaran.

    Screenshot that shows setting the deployment configuration with the web app name.

Mendapatkan sumber daya Communication Services

Sekarang setelah bot Anda dibuat dan disebarkan, buat sumber daya Communication Services untuk digunakan untuk menyiapkan saluran Communication Services:

  1. Selesaikan langkah-langkah untuk membuat sumber daya Communication Services.

  2. Buat pengguna Communication Services dan terbitkan token akses pengguna. Pastikan untuk mengatur cakupan ke obrolan. Salin string token dan string ID pengguna.

Mengaktifkan saluran Obrolan Communication Services

Saat Anda memiliki sumber daya Communication Services, Anda dapat menyiapkan saluran Communication Services di sumber daya bot. Dalam proses ini, ID pengguna dihasilkan untuk bot.

  1. Di portal Azure, buka sumber daya Azure Bot Anda. Di menu sumber daya, pilih Saluran. Dalam daftar saluran yang tersedia, pilih Azure Communications Services - Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Pilih Koneksi untuk melihat daftar sumber daya Communication Services yang tersedia di langganan Anda.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. Di panel Koneksi ion baru, pilih sumber daya obrolan Communication Services, lalu pilih Terapkan.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. Saat detail sumber daya diverifikasi, ID bot ditampilkan di kolom Id Bot Azure Communication Services. Anda dapat menggunakan ID bot untuk mewakili bot dalam utas obrolan dengan menggunakan API AddParticipant Obrolan Communication Services. Setelah Anda menambahkan bot ke obrolan sebagai peserta, bot mulai menerima aktivitas terkait obrolan, dan dapat merespons di utas obrolan.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Membuat aplikasi obrolan dan menambahkan bot sebagai peserta

Sekarang setelah Anda memiliki ID Communication Services bot, Anda dapat membuat utas obrolan dengan bot sebagai peserta.

Membuat aplikasi C# baru

  1. Jalankan perintah berikut untuk membuat aplikasi C#:

    dotnet new console -o ChatQuickstart

  2. Ubah direktori Anda ke folder aplikasi baru dan gunakan dotnet build perintah untuk mengkompilasi aplikasi Anda:

    cd ChatQuickstart
dotnet build

Pasang paket

Instal SDK Obrolan Communication Services untuk .NET:

dotnet add package Azure.Communication.Chat

Membuat klien obrolan

Untuk membuat klien obrolan, gunakan titik akhir Communication Services dan token akses pengguna yang Anda buat sebelumnya. CommunicationIdentityClient Gunakan kelas dari Identity SDK untuk membuat pengguna dan mengeluarkan token untuk diteruskan ke klien obrolan Anda. Token akses dapat dihasilkan di portal menggunakan instruksi berikut.

Salin kode berikut dan tempelkan di file sumber Program.cs :

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Memulai utas obrolan dengan bot

Gunakan metode aktif createChatThread chatClient untuk membuat utas obrolan. Ganti ID dengan ID Communication Services bot.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Mendapatkan klien utas obrolan

Metode mengembalikan GetChatThreadClient klien utas untuk utas yang sudah ada:

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Mengirim pesan ke utas obrolan

Untuk menggunakan SendMessage untuk mengirim pesan ke utas:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Menerima pesan obrolan dari utas obrolan

Anda bisa mendapatkan pesan obrolan dengan melakukan polling GetMessages metode pada klien utas obrolan pada interval yang ditetapkan:

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Periksa daftar pesan untuk balasan gema bot ke "Halo Dunia".

Anda dapat menggunakan JavaScript atau SDK seluler Azure untuk berlangganan pemberitahuan pesan masuk:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Membersihkan utas obrolan

Setelah selesai menggunakan utas obrolan, hapus utas:

chatClient.DeleteChatThread(threadId);

Menyebarkan aplikasi obrolan C#

Untuk menyebarkan aplikasi obrolan:

  1. Di Visual Studio, buka proyek obrolan.

  2. Klik kanan proyek ChatQuickstart dan pilih Terbitkan:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Setelah Anda menerbitkan solusi, jalankan dan periksa apakah Echobot menggemakan pesan pengguna pada prompt perintah. Sekarang setelah Anda memiliki solusi, Anda dapat melanjutkan untuk bermain dengan berbagai aktivitas yang diperlukan untuk skenario bisnis yang perlu Anda selesaikan.

Lebih banyak hal yang dapat Anda lakukan dengan bot

Bot dapat menerima lebih dari pesan teks biasa dari pengguna di saluran Obrolan Communications Services. Beberapa aktivitas yang dapat diterima bot dari pengguna meliputi:

  • Pembaruan percakapan
  • Pembaruan pesan
  • Penghapusan pesan
  • Indikator pengetikan
  • Aktivitas peristiwa
  • Berbagai lampiran, termasuk kartu adaptif
  • Data saluran bot

Bagian berikutnya memperlihatkan beberapa sampel untuk mengilustrasikan fitur-fitur ini.

Mengirim pesan selamat datang saat pengguna baru ditambahkan ke utas

Logika Echo Bot saat ini menerima input dari pengguna dan menggemakannya kembali. Jika Anda ingin menambahkan lebih banyak logika, seperti merespons peristiwa Communication Services yang ditambahkan peserta, salin kode berikut dan tempelkan di file sumber EchoBot.cs :

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Mengirim kartu adaptif

Catatan

Kartu adaptif hanya didukung dalam kasus penggunaan Azure Communication Services di mana semua peserta obrolan adalah pengguna Azure Communication Services, dan bukan untuk kasus penggunaan interoprability Teams.

Anda dapat mengirim kartu adaptif ke utas obrolan untuk meningkatkan keterlibatan dan efisiensi. Kartu adaptif juga membantu Anda berkomunikasi dengan pengguna dengan berbagai cara. Anda dapat mengirim kartu adaptif dari bot dengan menambahkan kartu sebagai lampiran aktivitas bot.

Berikut adalah contoh cara mengirim kartu adaptif:

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Dapatkan payload sampel untuk kartu adaptif di Sampel dan templat.

Untuk pengguna obrolan, saluran Obrolan Communication Services menambahkan bidang ke metadata pesan yang menunjukkan pesan memiliki lampiran. Dalam metadata, microsoft.azure.communication.chat.bot.contenttype properti diatur ke azurebotservice.adaptivecard.

Berikut adalah contoh pesan obrolan yang memiliki kartu adaptif yang terlampir:

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Mengirim pesan dari pengguna ke bot

Anda dapat mengirim pesan teks dasar dari pengguna ke bot dengan cara yang sama seperti Anda mengirim pesan teks ke pengguna lain.

Namun, saat Anda mengirim pesan yang memiliki lampiran dari pengguna ke bot, tambahkan bendera ini ke metadata Obrolan Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Untuk mengirim aktivitas peristiwa dari pengguna ke bot, tambahkan bendera ini ke metadata Obrolan Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Bagian berikut menunjukkan format sampel untuk pesan obrolan dari pengguna ke bot.

Pesan teks sederhana

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Pesan dengan lampiran

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Pesan dengan aktivitas peristiwa

Payload peristiwa mencakup semua bidang JSON dalam konten pesan kecuali Name. Bidang Name berisi nama peristiwa.

Dalam contoh berikut, nama endOfConversation peristiwa dengan payload "{field1":"value1", "field2": { "nestedField":"nestedValue" }} dikirim ke bot:

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

Bidang metadata microsoft.azure.communication.chat.bot.contenttype hanya diperlukan dalam pesan yang dikirim dari pengguna ke bot.

Bidang aktivitas bot yang didukung

Bagian berikut menjelaskan bidang aktivitas bot yang didukung untuk alur bot-ke-pengguna dan alur pengguna-ke-bot.

Alur bot-ke-pengguna

Bidang aktivitas bot berikut didukung untuk alur bot-ke-pengguna.

Aktivitas

  • Pesan
  • Mengetik

Bidang aktivitas pesan

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Dikonversi ke Communication Services SenderDisplayName.)
  • ChannelData (Dikonversi ke Communication Services Chat Metadata. Jika ada ChannelData nilai pemetaan adalah objek, nilai tersebut diserialisasikan dalam format JSON dan dikirim sebagai string.)

Alur pengguna-ke-bot

Bidang aktivitas bot ini didukung untuk alur pengguna ke bot.

Aktivitas dan bidang

  • Pesan

    • Id (ID pesan Obrolan Communication Services)
    • TimeStamp
    • Text
    • Attachments

  • Pembaruan percakapan

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Pembaruan pesan

    • Id (ID pesan Obrolan Communication Services yang Diperbarui)
    • Text
    • Attachments

  • Penghapusan pesan

    • Id (ID pesan Obrolan Communication Services yang Dihapus)

  • Aktivitas

    • Name
    • Value

  • Mengetik

Bidang umum lainnya

  • Recipient.Id dan Recipient.Name (ID pengguna dan nama tampilan Obrolan Communication Services)
  • From.Id dan From.Name (ID pengguna dan nama tampilan Obrolan Communication Services)
  • Conversation.Id (ID utas Obrolan Communication Services)
  • ChannelId (Obrolan Communication Services jika kosong)
  • ChannelData (Metadata pesan Obrolan Communication Services)

Pola serah terima bot

Terkadang, bot tidak memahami pertanyaan, atau tidak dapat menjawab pertanyaan. Pelanggan mungkin meminta dalam obrolan untuk terhubung ke agen manusia. Dalam skenario ini, utas obrolan harus diserahkan dari bot ke agen manusia. Anda dapat merancang aplikasi Anda untuk mentransisikan percakapan dari bot ke manusia.

Menangani komunikasi bot-ke-bot

Dalam beberapa kasus penggunaan, dua bot perlu ditambahkan ke utas obrolan yang sama untuk menyediakan layanan yang berbeda. Dalam skenario ini, Anda mungkin perlu memastikan bahwa bot tidak mengirim balasan otomatis ke pesan bot lain. Jika tidak ditangani dengan benar, interaksi otomatis bot antara mereka sendiri dapat mengakibatkan perulangan pesan yang tidak terbatas.

Anda dapat memverifikasi identitas pengguna Communication Services dari pengirim pesan di properti aktivitas From.Id . Periksa untuk melihat apakah itu milik bot lain. Kemudian, ambil tindakan yang diperlukan untuk mencegah alur komunikasi bot-ke-bot. Jika jenis skenario ini menghasilkan volume panggilan tinggi, saluran Obrolan Communication Services membatasi permintaan dan bot tidak dapat mengirim dan menerima pesan.

Pelajari selengkapnya tentang batas pembatasan.

Pemecahan masalah

Bagian berikut menjelaskan cara memecahkan masalah skenario umum.

Saluran obrolan tidak dapat ditambahkan

Di portal pengembang Microsoft Bot Framework, buka Olahpesan Bot Konfigurasi>untuk memverifikasi bahwa titik akhir telah diatur dengan benar.

Bot mendapatkan pengecualian terlarang saat membalas pesan

Verifikasi bahwa ID aplikasi dan kata sandi Microsoft bot disimpan dengan benar dalam file konfigurasi bot yang Anda unggah ke aplikasi web.

Bot tidak dapat ditambahkan sebagai peserta

Verifikasi bahwa ID Communication Services bot digunakan dengan benar saat permintaan dikirim untuk menambahkan bot ke utas obrolan.

Langkah berikutnya

Coba aplikasi demo bot obrolan untuk obrolan 1:1 antara pengguna obrolan dan bot melalui komponen UI WebChat BotFramework.