Proaktives Messaging für Bots

Artikel
04/02/2023

Wichtig

Dieser Artikel basiert auf dem Bot Framework SDK v3. Wenn Sie nach der aktuellen Dokumentationsversion 4.6 oder höher des SDK suchen, lesen Sie den Abschnitt Konversationsbots .

Eine proaktive Nachricht ist eine Nachricht, die von einem Bot gesendet wird, um eine Unterhaltung zu beginnen. Vielleicht möchten Sie, dass Ihr Bot aus vielen verschiedenen Gründen eine Unterhaltung beginnt, darunter:

Willkommensnachrichten für persönliche Botunterhaltungen.
Umfrageantworten.
Externe Ereignisbenachrichtigungen.

Das Senden einer Nachricht zum Starten eines neuen Konversationsthreads unterscheidet sich vom Senden einer Nachricht als Reaktion auf eine vorhandene Unterhaltung. Wenn Ihr Bot eine neue Unterhaltung beginnt, gibt es keine bereits laufende Unterhaltung, an die die Nachricht gesendet werden soll. Um eine proaktive Nachricht zu senden, müssen Sie Folgendes ausführen:

Entscheiden Sie, was Sie sagen werden
Abrufen der eindeutigen ID und Mandanten-ID des Benutzers
Senden der Nachricht

Beim Erstellen proaktiver Nachrichten müssen Sie aufrufen MicrosoftAppCredentials.TrustServiceUrlund die Dienst-URL übergeben, bevor Sie die ConnectorClient zum Senden der Nachricht verwendete erstellen. Andernfalls wird von Ihrer App eine 401: Unauthorized Antwort empfangen. Weitere Informationen finden Sie in den Beispielen.

Bewährte Methoden für proaktives Messaging

Das Senden proaktiver Nachrichten ist eine effektive Möglichkeit, mit Ihren Benutzern zu kommunizieren. Aus Sicht des Benutzers wird die Nachricht jedoch unaufgefordert angezeigt. Wenn eine Willkommensnachricht angezeigt wird, ist dies das erste Mal, dass sie mit Ihrer App interagiert haben. Es ist wichtig, diese Funktion zu verwenden und dem Benutzer die vollständigen Informationen bereitzustellen, damit sie den Zweck dieser Nachricht verstehen.

Proaktive Nachrichten können generell in zwei Kategorien unterteilt werden: Willkommensnachrichten und Benachrichtigungen.

Willkommensnachrichten

Wenn Sie proaktives Messaging verwenden, um eine Willkommensnachricht an einen Benutzer zu senden, stellen Sie sicher, dass die Nachricht aus der Perspektive des Benutzers unaufgelöst angezeigt wird. Wenn eine Willkommensnachricht angezeigt wird, ist dies das erste Mal, dass sie mit Ihrer App interagiert haben. Die besten Begrüßungsnachrichten sind:

Warum sie diese Nachricht erhalten: Es sollte dem Benutzer klar sein, warum er diese Nachricht empfängt. Wenn Ihr Bot in einem Kanal installiert wurde und Sie eine Begrüßungsnachricht an alle Benutzer gesendet haben, teilen Sie ihnen mit, in welchem Kanal er installiert wurde und möglicherweise von wem er installiert wurde.
Was bieten Sie an: Was können sie mit Ihrer App tun? Welchen Wert können Sie ihnen beibringen?
Was sollten sie als Nächstes tun: Laden Sie sie ein, einen Befehl auszuprobieren oder auf irgendeine Weise mit Ihrer App zu interagieren.

Benachrichtigungen

Wenn Sie proaktives Messaging zum Senden von Benachrichtigungen verwenden, müssen Sie sicherstellen, dass Ihre Benutzer über einen klaren Weg verfügen, um allgemeine Aktionen basierend auf Ihrer Benachrichtigung auszuführen, und ein klares Verständnis dafür haben, warum die Benachrichtigung erfolgt ist. Gute Benachrichtigungen umfassen im Allgemeinen:

Was passiert ist: Ein klarer Hinweis darauf, was die Benachrichtigung verursacht hat.
Was passiert ist: Es sollte klar sein, welches Element bzw. welche Sache aktualisiert wurde, um die Benachrichtigung zu verursachen.
Wer hat dies getan: Wer hat die Aktion ergriffen, die dazu geführt hat, dass die Benachrichtigung gesendet wurde?
Was sie dagegen tun können: Erleichtern Sie es Ihren Benutzern, aktionen basierend auf Ihren Benachrichtigungen zu ergreifen.
So können sie sich abmelden: Geben Sie einen Pfad an, über den Benutzer zusätzliche Benachrichtigungen deaktivieren können.

Abrufen der erforderlichen Benutzerinformationen

Bots können neue Unterhaltungen mit einem einzelnen Microsoft Teams-Benutzer erstellen, indem sie die eindeutige ID und Mandanten-ID des Benutzers abrufen. Sie können diese Werte mit einer der folgenden Methoden abrufen:

Durch Das Abrufen der Teamliste von einem Kanal wird Ihre App installiert.
Indem Sie sie zwischenspeichern, wenn ein Benutzer mit Ihrem Bot in einem Kanal interagiert.
Wenn ein Benutzer in einer Kanalunterhaltung @mentioned , an der der Bot beteiligt ist.
Indem Sie sie zwischenspeichern, wenn Sie das conversationUpdateEreignis empfangen, wenn Ihre App in einem persönlichen Bereich installiert wird oder neue Mitglieder zu einem Kanal oder Gruppenchat hinzugefügt werden.

Proaktives Installieren Ihrer App mit Graph

Hinweis

Die proaktive Installation von Apps mit Graph befindet sich in der Betaphase.

Gelegentlich kann es erforderlich sein, Benutzer proaktiv zu senden, die Ihre App zuvor nicht installiert oder mit ihr interagiert haben. Sie sollten beispielsweise den Unternehmens-Communicator verwenden, um Nachrichten an Ihre gesamte Organisation zu senden. In diesem Szenario können Sie die Graph-API verwenden, um Ihre App proaktiv für Ihre Benutzer zu installieren und dann die erforderlichen Werte aus dem Ereignis zwischenzuspeichern, das Ihre App bei der conversationUpdate Installation erhält.

Sie können nur Apps installieren, die sich im App-Katalog Ihrer Organisation oder im Microsoft Teams Store befinden.

Ausführliche Informationen finden Sie unter Installieren von Apps für Benutzer in der Graph-Dokumentation. Es gibt auch ein Beispiel in .NET.

Beispiele

Stellen Sie sicher, dass Sie sich authentifizieren und über ein Bearertoken verfügen, bevor Sie eine neue Unterhaltung mithilfe der REST-API erstellen.

POST {Service URL of your bot}/v3/conversations


{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Geben Sie id als Bot-App-ID und name als Botnamen an. Sie können die membersid aus Ihrem Bots-Objekt TurnContext abrufen, z turnContext.Activity.From.Id. B. . id Ähnlich gilt für den Mandanten aus Ihrem Bots-ObjektTurnContext, zturnContext.Activity.ChannelData.Tenant.Id. B. .

Sie müssen die Benutzer-ID und die Mandanten-ID angeben. Wenn der Aufruf erfolgreich ist, gibt die API das folgende Antwortobjekt zurück.

{
    "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"

}

Diese ID ist die eindeutige Konversations-ID des persönlichen Chats. Speichern Sie diesen Wert, und verwenden Sie ihn für zukünftige Interaktionen mit dem Benutzer.

Verwenden von .NET

In diesem Beispiel wird das NuGet-Paket Microsoft.Bot.Connector.Teams verwendet.

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

Verwenden von Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

Erstellen einer Kanalunterhaltung

Der von Ihrem Team hinzugefügte Bot kann Beiträge in einen Kanal versenden, um eine neue Antwortkette zu erstellen. Wenn Sie das Node.js Teams SDK verwenden, verwenden startReplyChain()Sie , wodurch Sie eine vollständig aufgefüllte Adresse mit der richtigen Aktivitäts-ID und Konversations-ID erhalten. Wenn Sie C# verwenden, sehen Sie sich das folgende Beispiel an.

Alternativ können Sie die REST-API verwenden und eine POST-Anforderung an die /conversations Ressource ausgeben.

Beispiele für das Erstellen einer Kanalunterhaltung

Das .NET-Beispiel stammt aus diesem Beispiel.

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

POST {Service URL of your bot}/v3/conversations


{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

Sie können das -Objekt TurnContext wie turnContext.Activity.ServiceURL den {Service URL of your bot} -Parameter abrufen.

Sie können das -Objekt TurnContext wie turnContext.Activity.TeamsChannelData den channelData -Parameter abrufen.

Geben Sie id als Bot-App-ID und name als Botnamen an. id Ähnlich gilt für den Mandanten aus Ihrem Bots-ObjektTurnContext, zturnContext.Activity.ChannelData.Tenant.Id. B. .

Ebenso können Sie den teamID Abschnitt für teamsChannelId, teamsTeamId, channelin teamchannelData bereitstellen, der die Nachricht an den allgemeinen Kanal des Teams sendet.

Wenn der Aufruf erfolgreich ist, gibt die API das folgende Antwortobjekt zurück:

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

Siehe auch

Bot Framework-Beispiele.

Freigeben über