Kullanıcılara proaktif bildirimler gönderme

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Genellikle bot, kullanıcıdan bir ileti almaya yanıt olarak doğrudan kullanıcıya bir ileti gönderir. Bazen botların kullanıcıdan kaynaklanmayan uyaranlara yanıt olarak proaktif bir ileti göndermesi gerekebilir.

Proaktif iletiler çeşitli senaryolarda yararlı olabilir. Örneğin, kullanıcı daha önce botdan bir ürünün fiyatını izlemesini istediyse, ürünün fiyatı %20 düştüğünde bot kullanıcıyı uyarabilir. Veya bot, kullanıcının sorusuna yanıt derlemek için biraz zaman gerektiriyorsa, kullanıcıyı gecikme konusunda bilgilendirebilir ve bu arada konuşmanın devam etmesi için izin verebilir. Bot, soruya verilen yanıtı derlemeyi tamamladığında bu bilgileri kullanıcıyla paylaşır.

Bu makale, genel olarak botlara yönelik proaktif iletiler hakkındaki bilgileri kapsar. Microsoft Teams'de proaktif iletiler hakkında bilgi için bkz.

• C#, JavaScript, Java veya Python'da Teams konuşma botu örneği.
• Proaktif ileti gönderme hakkında Microsoft Teams belgeleri.

Not

Bot Framework JavaScript, C# ve Python SDK'ları desteklenmeye devam edecektir, ancak Java SDK'sı son uzun vadeli destek Kasım 2023'te sona erecek şekilde kullanımdan kaldırılacaktır.

Java SDK ile oluşturulan mevcut botlar çalışmaya devam edecektir.

Yeni bot derlemesi için Power Virtual Agents'ı kullanmayı göz önünde bulundurun ve doğru sohbet botu çözümünü seçme hakkında bilgi edinin.

Daha fazla bilgi için bkz . Bot oluşturmanın geleceği.

Önkoşullar

• Botla ilgili temel bilgileri anlama.
• C#, JavaScript, Java veya Python'daki proaktif iletilerin bir kopyası. Örnek, bu makalede proaktif mesajlaşmayı açıklamak için kullanılır.

Proaktif örnek hakkında

Genel olarak, bir uygulama olarak bot birkaç katmana sahiptir:

• HTTP isteklerini kabul edebilen ve özellikle bir mesajlaşma uç noktasını destekleyen web uygulaması.
• Kanallarla bağlantıyı işleyen bir bağdaştırıcı.
• Genellikle bot uygulamasının konuşma mantığını işleyen bir bot sınıfında kapsüllenmiş dönüş işleyicisi.

Kullanıcıdan gelen bir iletiye yanıt olarak uygulama bağdaştırıcının işlem etkinliği yöntemini çağırır. Bu yöntem bir dönüş ve bağlam oluşturur, ara yazılım işlem hattını çağırır ve ardından botunun dönüş işleyicisini çağırır.

Proaktif bir ileti başlatmak için bot uygulamasının başka girişler alabilmesi gerekir. Proaktif bir ileti başlatmaya yönelik uygulama mantığı SDK'nın kapsamı dışındadır. Bu örnek için, proaktif dönüşü tetikleme amacıyla standart ileti uç noktasına ek olarak bir bildirim uç noktası kullanılır.

Uygulama, bu bildirim uç noktasındaki bir GET isteğine yanıt olarak bağdaştırıcının işlem etkinliği yöntemine benzer şekilde davranan devam konuşma yöntemini çağırır. Konuşmaya devam et yöntemi:

• Kullanıcı ve proaktif dönüş için kullanılacak geri çağırma yöntemi için uygun bir konuşma başvurusu alır.
• Bir olay etkinliği oluşturur ve proaktif dönüş için bağlamı döndürün.
• Bağdaştırıcının ara yazılım işlem hattını çağırır.
• Sağlanan geri çağırma yöntemini çağırır.
• Dönüş bağlamı, kullanıcıya ileti göndermek için konuşma başvurusunu kullanır.

Örnekte, aşağıdaki çizimde gösterildiği gibi kullanıcıya proaktif iletiler göndermek için kullanılan bir bot, ileti uç noktası ve ek bir uç nokta vardır.

Konuşma başvuruyu alma ve depolama

Bot Framework Öykünücüsü bota bağlandığında, bot iki konuşma güncelleştirme etkinliği alır. Bot'un konuşma güncelleştirmesi etkinlik işleyicisinde, konuşma başvurusu aşağıda gösterildiği gibi alınır ve bir sözlükte depolanır.

C#

Botlar\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

botlar/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

botlar/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

Konuşma başvurusu, etkinliğin bulunduğu konuşmayı açıklayan bir konuşma özelliği içerir. Konuşma, konuşmaya katılan kullanıcıları listeleyen bir kullanıcı özelliği ve geçerli etkinliğe yönelik yanıtların nereye gönderilebileceğini gösteren bir hizmet URL'si özelliği içerir. Kullanıcılara proaktif iletiler göndermek için geçerli bir konuşma başvurusu gereklidir. (Teams kanalı için hizmet URL'si bölgeselleştirilmiş bir sunucuyla eşler.)

Not

Gerçek dünya senaryosunda, bellekte bir nesne kullanmak yerine konuşma başvurularını veritabanında kalıcı hale getirin.

Proaktif ileti gönderme

İkinci denetleyici olan bildirim denetleyicisi, kullanıcıya proaktif iletiyi göndermekle sorumludur. Proaktif bir ileti oluşturmak için aşağıdaki adımları kullanır.

1. Proaktif iletinin gönderildiği konuşmanın başvurularını alır.
2. Bağdaştırıcının konuşma devam etme yöntemini çağırarak konuşma başvurusunu ve kullanılacak dönüş işleyici temsilcisini sağlar. (Konuşmaya devam et yöntemi, başvuruda bulunan konuşma için bir dönüş bağlamı oluşturur ve ardından belirtilen dönüş işleyici temsilcisini çağırır.)
3. Temsilcide, proaktif iletiyi göndermek için dönüş bağlamını kullanır. Burada, temsilci bildirim denetleyicisinde tanımlanır ve kullanıcıya proaktif iletiyi gönderir.

Not

Her kanalın kararlı bir hizmet URL'si kullanması gerekirken, URL zaman içinde değişebilir. Hizmet URL'si hakkında daha fazla bilgi için Bot Framework Etkinlik Şeması'nın Temel etkinlik yapısı ve Hizmet URL'si bölümlerine bakın.

Hizmet URL'si değişirse, önceki konuşma başvuruları artık geçerli olmaz ve konuşmaya devam etmek için yapılan çağrılar bir hata veya özel durum oluşturur. Bu durumda botunuzun proaktif iletiler gönderebilmesi için önce kullanıcı için yeni bir konuşma başvurusu alması gerekir.

C#

Denetleyiciler\NotifyController .cs

Bot'un bildirim sayfası her istenişinde, bildirim denetleyicisi konuşma başvurularını sözlükten alır. Denetleyici daha sonra proaktif iletiyi göndermek için ve BotCallback yöntemlerini kullanırContinueConversationAsync.

[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

Sunucunun /api/notify sayfası her istenişinde, sunucu konuşma başvurularını sözlükten alır. Sunucu daha sonra proaktif iletiyi göndermek için yöntemini kullanır continueConversation . parametresi continueConversation , bu dönüş için bot'un dönüş işleyicisi olarak hizmet veren bir işlevdir.

    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

Bot'un bildirim sayfası her istenişinde, bildirim denetleyicisi konuşma başvurularını sözlükten alır. Denetleyici daha sonra proaktif iletiyi göndermek için yöntemini kullanır continueConversation .

@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

Bot'un bildirim sayfası her istenişinde, sunucu konuşma başvurularını sözlükten alır. Sunucu daha sonra proaktif iletiyi göndermek için öğesini _send_proactive_message kullanır.

    for conversation_reference in CONVERSATION_REFERENCES.values():
        await ADAPTER.continue_conversation(
            conversation_reference,
            lambda turn_context: turn_context.send_activity("proactive hello"),
            APP_ID,
        )


APP = web.Application(middlewares=[aiohttp_error_middleware])

Proaktif bir ileti göndermek için bağdaştırıcı, bot için bir uygulama kimliği gerektirir. Üretim ortamında bot uygulama kimliğini kullanabilirsiniz. Öykünücü ile botu yerel olarak test etmek için boş dizeyi ("") kullanabilirsiniz.

Botunuzu test etme

1. Henüz yapmadıysanız Bot Framework Öykünücüsü'ni yükleyin.
2. Örneği makinenizde yerel olarak çalıştırın.
3. Öykünücüyü başlatın ve botunuza bağlanın.
4. Botunuzun api/notify sayfasına yükleyin. Bu, Öykünücü'de proaktif bir ileti oluşturur.

Ek bilgi

Gereksinimler

Proaktif bir ileti gönderebilmeniz için botunuzun konuşma başvurusuna ihtiyacı vardır. Botunuz, kullanıcıdan aldığı herhangi bir etkinlikten konuşma başvurularını alabilir, ancak bu genellikle bot proaktif bir ileti göndermeden önce kullanıcının botla en az bir kez etkileşim kurmasını gerektirir.

Birçok kanal, kullanıcı bota en az bir kez mesaj göndermediği sürece botların kullanıcıya mesajlaşmasını yasaklar. Bazı kanallar özel durumlara izin verir. Örneğin, Teams kanalı botunuzun botu içeren önceden oluşturulmuş bir grup konuşmasında kişilere proaktif (veya 1'de 1) bir ileti göndermesine olanak tanır.

Tasarımla ilgili dikkat edilecek noktalar

Botunuzda proaktif iletiler uygularken kısa bir süre içinde birkaç proaktif ileti göndermeyin. Bazı kanallar, botların kullanıcıya ne sıklıkta ileti gönderebileceğine ilişkin kısıtlamalar uygular ve bu kısıtlamaları ihlal ederse botu devre dışı bırakır.

En basit proaktif ileti türü için bot, geçerli durum veya konuşma konusuna bakılmaksızın tetiklendiğinde iletiyi konuşmaya dahil eder. Bu senaryoda, proaktif ileti normal konuşma akışını kesintiye uğratır.

Bildirimleri daha sorunsuz işlemek için, konuşma durumunda bayrak ayarlama veya bildirimi kuyruğa ekleme gibi bildirimi konuşma akışıyla tümleştirmenin diğer yollarını göz önünde bulundurun.

Proaktif dönüş hakkında

Konuşmaya devam etme yöntemi, konuşma başvurusunu ve geri çağırma işleyicisini kullanarak:

1. Bot uygulamasının proaktif iletiyi gönderebileceği bir dönüş oluşturun. Bağdaştırıcı, bu dönüş için adı "ContinueConversation" olarak ayarlanmış bir event etkinlik oluşturur.
2. Dönüşü bağdaştırıcının ara yazılım işlem hattı üzerinden gönderin.
3. Özel mantık gerçekleştirmek için geri çağırma işleyicisini çağırın.

Proaktif iletiler örneğinde geri çağırma işleyicisi bildirim denetleyicisinde tanımlanır ve botunun normal dönüş işleyicisi aracılığıyla proaktif etkinliği göndermeden iletiyi doğrudan konuşmaya gönderir. Örnek kod ayrıca proaktif dönüşte bota erişmez veya bot durumunu güncelleştirmez.

Birçok bot durum bilgisi vardır ve birden çok dönüşte bir konuşmayı yönetmek için durum bilgisi kullanır. Konuşmaya devam et yöntemi bir dönüş bağlamı oluşturduğunda, sıra onunla ilişkili doğru kullanıcı ve konuşma durumuna sahip olur ve proaktif dönüşleri botunuzun mantığıyla tümleştirebilirsiniz. Bot mantığının proaktif iletiden haberdar olması gerekiyorsa, bunu yapmak için birkaç seçeneğiniz vardır. Şunları yapabilirsiniz:

• Geri çağırma işleyicisi olarak bot'un dönüş işleyicisini sağlayın. Bot daha sonra "ContinueConversation" olay etkinliğini alır.
• Önce dönüş bağlamı için bilgi eklemek için geri çağırma işleyicisini kullanın ve ardından bot'un dönüş işleyicisini çağırın.

Her iki durumda da proaktif olayı işlemek için bot mantığınızı tasarlamanız gerekir.

Sonraki adımlar

Sıralı konuşma akışını uygulama