Skicka proaktiva meddelanden till användare

GÄLLER FÖR: SDK v4

Vanligtvis skickar en robot ett meddelande till en användare direkt som svar på att ta emot ett meddelande från användaren. Ibland kan en robot behöva skicka ett proaktivt meddelande, ett meddelande som svar på stimulanser som inte kommer från användaren.

Proaktiva meddelanden kan vara användbara i olika scenarier. Om användaren till exempel tidigare har bett roboten att övervaka priset på en produkt kan roboten varna användaren om priset på produkten har sjunkit med 20 %. Om en robot kräver lite tid för att kompilera ett svar på användarens fråga kan den informera användaren om fördröjningen och tillåta att konversationen fortsätter under tiden. När roboten är klar med kompileringen av svaret på frågan delar den informationen med användaren.

Den här artikeln beskriver information om proaktiva meddelanden för robotar i allmänhet. Information om proaktiva meddelanden i Microsoft Teams finns i

• Exempel på Teams-konversationsrobot i C#, JavaScript, Java eller Python.
• Microsoft Teams-dokumentationen om hur du skickar proaktiva meddelanden.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot bör du överväga att använda Power Virtual Agents och läsa om hur du väljer rätt chattrobotlösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

• Förstå grunderna i roboten.
• En kopia av exemplet med proaktiva meddelanden i C#, JavaScript, Java eller Python. Exemplet används för att förklara proaktiva meddelanden i den här artikeln.

Om det proaktiva exemplet

I allmänhet har en robot som ett program några lager:

• Webbprogrammet som kan acceptera HTTP-begäranden och specifikt stöder en slutpunkt för meddelanden.
• Ett kort som hanterar anslutningen till kanalerna.
• En hanterare för svängen, vanligtvis inkapslad i en robotklass som hanterar konversationsskälet för robotappen.

Som svar på ett inkommande meddelande från användaren anropar appen adapterns processaktivitetsmetod , som skapar en sväng- och svängkontext, anropar dess pipeline för mellanprogram och anropar sedan robotens turhanterare.

För att initiera ett proaktivt meddelande måste robotprogrammet kunna ta emot andra indata. Programlogiken för att initiera ett proaktivt meddelande ligger utanför SDK:ns omfång. I det här exemplet används en aviseringsslutpunkt , förutom en standardslutpunkt för meddelanden , för att utlösa den proaktiva svängen.

Som svar på en GET-begäran på den här aviseringsslutpunkten anropar appen nätverkskortets fortsätt-konversationsmetod , som fungerar på samma sätt som processaktivitetsmetoden . Metoden fortsätt konversation :

• Tar en lämplig konversationsreferens för användaren och motringningsmetoden som ska användas för den proaktiva svängen.
• Skapar en händelseaktivitet och aktiverar kontexten för den proaktiva svängen.
• Anropar adapterns pipeline för mellanprogram.
• Anropar den angivna återanropsmetoden.
• Turkontexten använder konversationsreferensen för att skicka meddelanden till användaren.

Exemplet har en robot, en slutpunkt för meddelanden och en extra slutpunkt som används för att skicka proaktiva meddelanden till användaren, enligt följande bild.

Hämta och lagra konversationsreferensen

När Bot Framework-emulatorn ansluter till roboten tar roboten emot två konversationsuppdateringsaktiviteter. I robotens aktivitetshanterare för konversationsuppdatering hämtas konversationsreferensen och lagras i en ordlista enligt nedan.

C#

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

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

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

Konversationsreferensen innehåller en konversationsegenskap som beskriver konversationen där aktiviteten finns. Konversationen innehåller en användaregenskap som visar de användare som deltar i konversationen och en egenskap för tjänst-URL som anger var svar på den aktuella aktiviteten kan skickas. En giltig konversationsreferens krävs för att skicka proaktiva meddelanden till användare. (För Teams-kanalen mappar tjänstens URL till en regionaliserad server.)

Kommentar

I ett verkligt scenario skulle du spara konversationsreferenser i en databas i stället för att använda ett objekt i minnet.

Skicka proaktivt meddelande

Den andra kontrollanten, den meddelande kontrollanten, ansvarar för att skicka det proaktiva meddelandet till användaren. Den använder följande steg för att generera ett proaktivt meddelande.

1. Hämtar referensen för konversationen som det proaktiva meddelandet ska skickas till.
2. Anropar nätverkskortets fortsätt-konversationsmetod och tillhandahåller konversationsreferensen och den turhanterardelegat som ska användas. (Metoden fortsätt konversation genererar en turkontext för den refererade konversationen och anropar sedan det angivna turn handler-ombudet.)
3. I ombudet använder du turkontexten för att skicka det proaktiva meddelandet. Här definieras ombudet på meddelandekontrollanten och skickar det proaktiva meddelandet till användaren.

Kommentar

Varje kanal bör använda en stabil tjänst-URL, men URL:en kan ändras över tid. Mer information om tjänstens URL finns i avsnitten Grundläggande aktivitetsstruktur och Tjänst-URL i Bot Framework-aktivitetsschemat.

Om tjänstens URL ändras är tidigare konversationsreferenser inte längre giltiga och anrop för att fortsätta konversationen genererar ett fel eller undantag. I det här fallet måste roboten skaffa en ny konversationsreferens för användaren innan den kan skicka proaktiva meddelanden igen.

C#

Controllers\NotifyController .cs

Varje gång robotens meddelandesida begärs hämtar meddelandekontrollanten konversationsreferenserna från ordlistan. Styrenheten använder ContinueConversationAsync sedan metoderna och BotCallback för att skicka det proaktiva meddelandet.

[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

Varje gång serverns sida begärs hämtar servern konversationsreferenserna /api/notify från ordlistan. Servern använder continueConversation sedan metoden för att skicka det proaktiva meddelandet. Parametern till continueConversation är en funktion som fungerar som robotens turhanterare för den här svängen.

    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

Varje gång robotens meddelandesida begärs hämtar meddelandekontrollanten konversationsreferenserna från ordlistan. Styrenheten använder continueConversation sedan metoden för att skicka det proaktiva meddelandet.

@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

Varje gång robotens meddelandesida begärs hämtar servern konversationsreferenserna från ordlistan. Servern använder _send_proactive_message sedan för att skicka det proaktiva meddelandet.

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

För att kunna skicka ett proaktivt meddelande kräver adaptern ett app-ID för roboten. I en produktionsmiljö kan du använda robotens app-ID. Om du vill testa roboten lokalt med emulatorn kan du använda den tomma strängen ("").

Testa din robot

1. Om du inte redan har gjort det installerar du Bot Framework-emulatorn.
2. Kör exemplet lokalt på datorn.
3. Starta emulatorn och anslut till din robot.
4. Läs in på robotens api/notify-sida. Detta genererar ett proaktivt meddelande i emulatorn.

Ytterligare information

Krav

Innan du kan skicka ett proaktivt meddelande behöver roboten en konversationsreferens. Din robot kan hämta konversationsreferensen från alla aktiviteter som den har tagit emot från användaren, men detta kräver vanligtvis att användaren interagerar med roboten minst en gång innan roboten kan skicka ett proaktivt meddelande.

Många kanaler förbjuder en robot från att skicka meddelanden till en användare om inte användaren har skickat meddelanden till roboten minst en gång. Vissa kanaler tillåter undantag. Teams-kanalen tillåter till exempel att din robot skickar ett proaktivt (eller 1-mot-1)-meddelande till individer i en redan etablerad gruppkonversation som innehåller roboten.

Utformningsbeaktanden

När du implementerar proaktiva meddelanden i roboten ska du inte skicka flera proaktiva meddelanden på kort tid. Vissa kanaler tillämpar begränsningar för hur ofta en robot kan skicka meddelanden till användaren och inaktiverar roboten om den bryter mot dessa begränsningar.

För den enklaste typen av proaktivt meddelande interjects roboten meddelandet i konversationen när det utlöses, utan hänsyn till aktuellt tillstånd eller samtalsämne. I det här scenariot avbryter det proaktiva meddelandet det normala konversationsflödet.

Om du vill hantera meddelanden på ett smidigare sätt bör du överväga andra sätt att integrera meddelandet i konversationsflödet, till exempel att ange en flagga i konversationstillståndet eller lägga till meddelandet i en kö.

Om den proaktiva vändningen

Metoden fortsätt konversation använder konversationsreferensen och en återställningshanterare för att:

1. Skapa en tur där robotprogrammet kan skicka det proaktiva meddelandet. Adaptern skapar en event aktivitet för den här svängen med namnet inställt på "ContinueConversation".
2. Skicka svängen genom adapterns pipeline för mellanprogram.
3. Anropa hanteraren för återanrop för att utföra anpassad logik.

I exemplet med proaktiva meddelanden definieras svarsanropshanteraren i meddelandekontrollanten och skickar meddelandet direkt till konversationen, utan att skicka den proaktiva aktiviteten via robotens normala turhanterare. Exempelkoden får inte heller åtkomst till eller uppdaterar robotens tillstånd på den proaktiva svängen.

Många robotar är tillståndskänsliga och använder tillstånd för att hantera en konversation över flera varv. När metoden fortsätt konversation skapar en turkontext har svängningen rätt användar- och konversationstillstånd associerat med den, och du kan integrera proaktiva svängar i robotens logik. Om du behöver robotlogik för att vara medveten om det proaktiva meddelandet har du några alternativ för att göra det. Du kan:

• Ange robotens turhanterare som svarsanropshanterare. Roboten får sedan händelseaktiviteten "ContinueConversation".
• Använd återanropshanteraren för att lägga till information i turkontexten först och anropa sedan robotens turhanterare.

I båda dessa fall måste du utforma robotlogik för att hantera den proaktiva händelsen.

Nästa steg

Implementera sekventiellt konversationsflöde