Proaktives Messaging für Bots

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

• Willkommensnachrichten für persönliche Bot-Unterhaltungen.
• Antworten auf Umfragen.
• Externe Ereignisbenachrichtigungen.

Das Senden einer Nachricht zum Starten eines neuen Unterhaltungsthreads unterscheidet sich vom Senden einer Nachricht als Antwort auf eine vorhandene Unterhaltung. Wenn Ihr Bot eine neue Unterhaltung beginnt, gibt es keine bereits vorhandene Konversation, in der die Nachricht gepostet werden kann. Um eine proaktive Nachricht zu senden, müssen Sie:

1. Entscheiden Sie, was Sie sagen wollen
2. Abrufen der eindeutigen ID und Mandanten-ID des Benutzers
3. Senden der Nachricht

Beim Erstellen proaktiver Nachrichten müssenMicrosoftAppCredentials.TrustServiceUrlSie aufrufen und die Dienst-URL übergeben, bevor Sie die ConnectorClient zum Senden der Nachricht verwendete erstellen. Andernfalls erhält Ihre App eine 401: Unauthorized Antwort. Weitere Informationen finden Sie in den Beispielen.

Bewährte Methoden für proaktives Messaging

Das Senden proaktiver Nachrichten ist eine effektive Möglichkeit zur Kommunikation mit Ihren Benutzern. Aus Sicht des Benutzers erscheint die Nachricht jedoch ohne Aufforderung. Wenn es eine Willkommensnachricht gibt, ist es das erste Mal, dass sie mit Ihrer App interagiert haben. Es ist wichtig, diese Funktionalität zu nutzen und dem Benutzer alle Informationen zur Verfügung zu stellen, um den Zweck dieser Meldung zu verstehen.

Proaktive Nachrichten fallen im Allgemeinen in eine von zwei Kategorien: Willkommensnachrichten oder Benachrichtigungen.

Begrüßungsnachrichten

Wenn Sie proaktives Messaging verwenden, um eine Willkommensnachricht an einen Benutzer zu senden, stellen Sie sicher, dass die Nachricht aus Sicht des Benutzers unaufgefordert erscheint. Wenn es eine Willkommensnachricht gibt, ist es das erste Mal, dass sie mit Ihrer App interagiert haben. Zu den besten Willkommensnachrichten gehören:

• Warum sie diese Nachricht erhalten: Es sollte für den Benutzer klar sein, warum er diese Nachricht erhält. Wenn Ihr Bot in einem Kanal installiert wurde und Sie eine Willkommensnachricht an alle Benutzer gesendet haben, teilen Sie ihnen mit, in welchem Kanal er installiert wurde und wer ihn möglicherweise installiert hat.
• Was bieten Sie: Was können sie mit Ihrer App tun? Welchen Wert können Sie ihnen bieten?
• Was sollte der Leser als Nächstes tun: Laden Sie ihn 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 einen klaren Weg haben, um basierend auf Ihrer Benachrichtigung allgemeine Aktionen auszuführen, und ein klares Verständnis dafür haben, warum die Benachrichtigung erfolgt ist. Gute Benachrichtigungsnachrichten umfassen im Allgemeinen:

• Was ist geschehen? Ein eindeutiger Hinweis darauf, was die Benachrichtigung ausgelöst hat.
• Was es passiert ist: Es sollte klar sein, welcher Gegenstand/welches Gegenstand aktualisiert wurde, um die Benachrichtigung auszulösen.
• Wer hat es ausgeführt: Wer hat die Aktion ausgeführt, die dazu geführt hat, dass die Benachrichtigung gesendet wurde?
• Was sie dagegen tun können: Machen Sie es Ihren Benutzern leicht, Aktionen basierend auf Ihren Benachrichtigungen durchzuführen.
• Wie sie sich abmelden können: Bieten Sie Benutzern die Möglichkeit, zusätzliche Benachrichtigungen abzumelden.

Erforderliche Benutzerinformationen erhalten

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 aus 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 Kanalkonversation @mentioned wird, an der der Bot beteiligt ist.
• Indem Sie sie zwischenspeichern, wenn Sie das conversationUpdateEreignis erhalten, wenn Ihre App in einem persönlichen Bereich installiert ist oder neue Mitglieder zu einem Kanal oder Gruppenchat hinzugefügt werden, das.

Proaktive Installation Ihrer App mithilfe von Graph

Gelegentlich kann es erforderlich sein, Benutzern, die Ihre App noch nicht installiert oder damit interagiert haben, proaktiv Nachrichten zu senden. Beispielsweise möchten Sie den Unternehmens-Communicator verwenden, um Nachrichten an Ihre gesamte Organization 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 zwischenspeichern, das Ihre App bei der conversationUpdate Installation empfängt.

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

Vollständige Details 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 authentifiziert sind und über ein Bearertoken verfügen, bevor Sie eine neue Konversation 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 als Bot-App-ID und name als Bot-Namen anid. Sie können das membersid Objekt aus Ihren Bots TurnContext abrufen, z. B turnContext.Activity.From.Id. . id Ähnlich verhält es sich mit dem Mandanten aus Ihrem Botsobjekt TurnContext wie turnContext.Activity.ChannelData.Tenant.Id.

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

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

}

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

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

Ihr vom Team hinzugefügter Bot kann in einem Kanal posten, um eine neue Antwortkette zu erstellen. Wenn Sie das Node.js Teams SDK verwenden, verwenden startReplyChain()Sie , wodurch Sie eine vollständig ausgefüllte Adresse mit der richtigen Aktivitäts-ID und Unterhaltungs-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 senden.

Beispiele für das Erstellen einer Kanalunterhaltung

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}}"
}

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

from microsoft_teams.apps import App
from microsoft_teams.api import MessageActivityInput
import asyncio

# Bot credentials
app_id = "YOUR_BOT_APP_ID"
app_password = "YOUR_BOT_APP_SECRET"

# Conversation details (obtained from bot installation event)
conversation_id = "19:channelId@thread.tacv2"

# Initialize the Teams app
app = App(
    storage={},
    client_id=app_id,
    client_secret=app_password
)

# Create the message activity
activity = MessageActivityInput(text="Hello from proactive message!")

# Send proactive message using Teams SDK
# The SDK handles authentication, activity construction, and API calls
result = await app.send(
    conversation_id=conversation_id,
    activity=activity
)

Siehe auch

Bot Framework-Beispiele.