Proaktive Nachrichten

Eine proaktive Nachricht ist jede Nachricht, die von einem Agent gesendet wird und nicht auf eine Anforderung eines Benutzers erfolgt. Diese Nachricht kann Inhalte enthalten wie:

  • Willkommensnachrichten
  • Benachrichtigungen
  • Geplante Nachrichten

Um eine proaktive Nachricht an einen Benutzer, einen Gruppenchat oder ein Team zu senden, muss Ihr Agent über die erforderlichen Berechtigungen verfügen, um die Nachricht zu senden. Für einen Gruppenchat oder ein Team muss die App, die Ihren Agent enthält, zuerst an diesem Speicherort installiert werden.

Sie können Ihre App bei Bedarf proaktiv mithilfe von Microsoft Graph in einem Team installieren oder eine benutzerdefinierte App-Richtlinie verwenden, um eine App in Ihrem Teams und für die Benutzer der organization zu installieren. Für bestimmte Szenarien müssen Sie Ihre App proaktiv mithilfe von Graph installieren. Damit ein Benutzer proaktive Nachrichten erhält, installieren Sie die App für den Benutzer, oder machen Sie den Benutzer zu einem Teil eines Teams, in dem die App installiert ist.

Das Senden einer proaktiven Nachricht unterscheidet sich vom Senden einer regulären Nachricht. Proaktive Nachrichten werden per App gesendet. Send() außerhalb eines Aktivitätshandlers. Das SDK erstellt die Konversation automatisch, wenn Sie die App aufrufen. senden(). Sie benötigen einen conversationId, das SDK löst die Dienst-URL automatisch auf. Zum Beispiel ein neuer Einzelchat oder ein neuer Unterhaltungsthread in einem Kanal. Sie können keinen neuen Gruppenchat oder einen neuen Kanal in einem Team mit proaktivem Messaging erstellen.

Folgen Sie diesen Schritten, um eine proaktive Nachricht zu senden:

  1. Rufen Sie bei Bedarf die Microsoft Entra-Benutzer-ID, Benutzer-ID, Team-ID oder Kanal-ID ab.
  2. Erstellen der Unterhaltung, falls erforderlich.
  3. Abrufen der Konversations-ID.
  4. Senden der Nachricht.

Die Codeausschnitte im Beispielabschnitt dienen dazu, eine Eins-zu-Eins-Unterhaltung zu schaffen. Links zu Beispielen für Einzelunterhaltungen und Gruppen- oder Kanalnachrichten finden Sie unter Codebeispiele. Informationen zur effektiven Nutzung proaktiver Nachrichten finden Sie unter "Bewährte Methoden für proaktives Messaging".

Abrufen der Microsoft Entra-Benutzer-ID, Benutzer-ID, Team-ID oder Kanal-ID

Sie können eine neue Konversation mit einem Benutzer oder einem Unterhaltungsthread in einem Kanal erstellen und benötigen die richtige ID. Sie können diese ID auf eine der folgenden Arten erhalten oder abrufen:

  • Wenn Ihre App in einem bestimmten Kontext installiert wird, erhalten Sie eine onMembersAdded Aktivität.
  • Wenn ein neuer Benutzer zu einem Kontext hinzugefügt wird, in dem Ihre App installiert ist, erhalten Sie eine onMembersAdded Aktivität.
  • Jedes Ereignis, das der Agent erhält, enthält die erforderlichen Informationen, die Sie aus dem Agentenkontext (Aktivitätskontext) erhalten können.
  • Sie können in einem Team, in dem Ihre App installiert ist, die Liste der Kanäle abrufen.
  • Sie können die Liste der Mitglieder eines Teams abrufen, in dem Ihre App installiert ist.

Unabhängig davon, wie Sie an die Informationen gelangen, speichern Sie die tenantId und speichern Sie dann entweder die userIdchannelId oder um eine neue Unterhaltung zu erstellen. Sie können auch die teamId verwenden, um einen neuen Unterhaltungsthread im allgemeinen oder Standardkanal eines Teams zu erstellen. Stellen Sie sicher, dass der Agent im Team installiert ist, bevor Sie eine proaktive Nachricht an einen Kanal senden können.

  • Das aadObjectId ist für den Benutzer eindeutig und kann mithilfe der Graph-API abgerufen werden, um eine neue Unterhaltung im persönlichen Chat zu erstellen. Stellen Sie sicher, dass der Agent im persönlichen Bereich installiert ist, bevor Sie eine proaktive Nachricht senden können. Wenn der Agent beim Senden einer proaktiven Nachricht mithilfe des aadObjectIdnicht in einem persönlichen Bereich installiert ist, gibt der Agent einen 403 Fehler mit ForbiddenOperationException Nachricht zurück.

  • Das userId ist eindeutig für Ihre Agent-ID und einen bestimmten Benutzer. Sie können die userId Agents zwischen diesen nicht wiederverwenden.

  • Die channelId ist global.

Erstellen Sie die Unterhaltung, nachdem Sie die Benutzer- oder Kanalinformationen haben.

Hinweis

Das Senden proaktiver Nachrichten mit wird aadObjectId nur im persönlichen Bereich unterstützt.

Erstellen der Unterhaltung

Sie können die Unterhaltung erstellen, wenn sie nicht vorhanden ist oder wenn Sie die conversationId. Erstellen Sie die Unterhaltung nur einmal, und speichern Sie das Ergebnis conversationId für zukünftige proaktive Nachrichten.

Zum Erstellen der Unterhaltung benötigen Sie ein aadObjectId oder , userIdtenantId, und serviceUrl.

Hinweis

Um die Konversation zu erstellen, übergeben Sie Id den aadObjetId Wert im Parameter.

Verwenden Sie serviceUrlfür den Wert einer eingehenden Aktivität, die den Flow auslöst, oder eine der globalen Dienst-URLs. Wenn die serviceUrl für eine eingehende Aktivität, die das proaktive Szenario auslöst, nicht verfügbar ist, verwenden Sie die folgenden globalen URL-Endpunkte:

  • Öffentlich: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCC Hoch: https://smba.infra.gov.teams.microsoft.us/teams
  • DoD: https://smba.infra.dod.teams.microsoft.us/teams

Warnung

  • Diese URLs sind nur für proaktive Nachrichten gedacht. Vermeiden Sie es, sie fest zu codieren. Verwenden Sie serviceUrl stattdessen aus der eingehenden Aktivitäts- oder Unterhaltungsreferenz. Wenn sie nicht verfügbar ist, verwenden Sie globale URLs basierend auf Region und Cloud.

  • Verwenden Sie serviceURL für jede Antwort auf Nachrichten aus der eingehenden Anforderung. Weitere Informationen finden Sie unter Activity.ServiceUrl-Eigenschaft .

Sie können die Unterhaltung abrufen, wenn die App zum ersten Mal installiert wird. Nachdem die Unterhaltung erstellt wurde, rufen Sie die Unterhaltungs-ID ab. Die conversationId ist in den Aktualisierungsereignissen der Unterhaltung verfügbar.

Die Unterhaltungs-ID ist für jeden Agent innerhalb eines bestimmten Kanals eindeutig, auch in einer mehrinstanzenfähigen Umgebung. Diese ID stellt sicher, dass die Nachrichten des Telefonberaters an den richtigen Kanal weitergeleitet werden und nicht mit anderen Telefonberatern oder Kanälen innerhalb derselben oder in verschiedenen Organisationen unterbrochen werden.

Wenn Sie nicht über die conversationIdverfügen, können Sie Ihre App proaktiv mithilfe von Graph installieren , um die conversationId.

Abrufen der Konversations-ID

Verwenden Sie entweder das conversationReference-Objekt oder conversationId und tenantId, um die Nachricht zu senden. Sie können diese ID abrufen, indem Sie entweder die Konversation erstellen oder sie aus jeder Aktivität speichern, die aus diesem Kontext an Sie gesendet wird. Speichern Sie diese ID als Referenz.

Nachdem Sie die entsprechenden Adressinformationen erhalten haben, können Sie Ihre Nachricht senden.

Senden der Nachricht

Nachdem Sie nun über die richtigen Adressinformationen verfügen, können Sie Ihre Nachricht senden. Wenn Sie das SDK verwenden, müssen Sie die app.Send() Methode verwenden, und um conversationId einen direkten API-Aufruf durchzuführen. Um Ihre Nachricht zu senden, aktivieren Sie die conversationParameters. Weitere Informationen finden Sie im Abschnitt "Beispiele ", oder verwenden Sie eines der im Abschnitt "Codebeispiele " aufgeführten Beispiele.

Um eine Nachricht proaktiv als Antwort an einen Thread in einem Kanal zu senden, verwenden Sie app.Reply() sowohl mit der Unterhaltungs-ID als auch mit der ID der Stammnachricht des Threads.

Hinweis

Teams unterstützt nicht das Senden proaktiver Nachrichten per E-Mail oder Benutzerprinzipalname (UPN).

Nachdem Sie die proaktive Nachricht gesendet haben, müssen Sie diese bewährten Methoden befolgen, während Sie proaktive Nachrichten senden, um den Informationsaustausch zwischen Benutzern und dem Agent zu verbessern.

Verstehen, wer einen Agent blockiert, stummgeschaltet oder deinstalliert hat

Als Entwickler können Sie einen Bericht erstellen, um zu verstehen, welche Benutzer in Ihrer organization einen Agent blockiert, stummgeschaltet oder deinstalliert haben. Diese Informationen können den Administratoren Ihrer organization helfen, organisationsweite Nachrichten zu senden oder die App-Nutzung zu steigern.

Mit Teams können Sie eine proaktive Nachricht an den Agent senden, um zu überprüfen, ob ein Benutzer einen Agent blockiert oder deinstalliert hat. Wenn der Agent blockiert oder deinstalliert wird, gibt Teams einen 403 Antwortcode mit einem subCode: MessageWritesBlockedzurück. Diese Antwort gibt an, dass die vom Agent gesendete Nachricht nicht an den Benutzer zugestellt wird.

Der Antwortcode wird pro Benutzer gesendet und enthält die Identität des Benutzers. Sie können die Antwortcodes für jeden Benutzer zusammen mit seiner Identität kompilieren, um einen Bericht aller Benutzer zu erstellen, die den Agent blockiert haben.

Das folgende Codebeispiel ist ein Beispiel für einen 403-Antwortcode:

HTTP/1.1 403 Forbidden
Cache-Control: no-store, must-revalidate, no-cache
Pragma: no-cache
Content-Length: 196
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0
ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0
Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\n}"}

Bewährte Methoden für proaktives Messaging

Das Senden proaktiver Nachrichten an die Benutzer 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, markiert dies die erste Interaktion mit Ihrer App. Es ist wichtig, diese Funktion zu verwenden und dem Benutzer die vollständigen Informationen bereitzustellen, damit sie den Zweck dieser Nachricht verstehen.

Willkommensnachrichten

Wenn proaktives Messaging verwendet wird, um eine Willkommensnachricht an einen Benutzer zu senden, gibt es keinen Kontext dafür, warum der Benutzer die Nachricht erhält. Außerdem ist dies die erste Interaktion des Benutzers mit Ihrer App. Es ist eine Gelegenheit, für einen guten ersten Eindruck zu sorgen. Eine gute Benutzererfahrung sorgt für eine bessere Akzeptanz der App. Schlechte Begrüßungsnachrichten können dazu führen, dass die Benutzer Ihre App blockieren. Schreiben Sie eine klare Begrüßungsnachricht, und wiederholen Sie die Begrüßungsnachricht, wenn sie nicht die gewünschte Wirkung erzielt.

Eine gute Willkommensnachricht kann die folgenden Informationen enthalten:

  • Grund für die Meldung – Es muss für den Benutzer klar sein, warum er die Nachricht erhält. Wenn Ihr Agent in einem Kanal installiert wurde und Sie eine Willkommensnachricht an alle Benutzer gesendet haben, dann teilen Sie ihnen mit, in welchem Kanal er installiert wurde und wer ihn installiert hat.

  • Ihr Angebot: Benutzer müssen erkennen können, was sie mit Ihrer App tun können und welchen Wert Sie für sie bieten können.

  • Nächste Schritte: Benutzer sollten die nächsten Schritte verstehen. Laden Sie beispielsweise Benutzer ein, einen Befehl auszuprobieren oder mit Ihrer App zu interagieren.

Benachrichtigungen

Um Benachrichtigungen mit proaktivem Messaging zu senden, stellen Sie sicher, dass Ihre Benutzer einen eindeutigen Pfad haben, um allgemeine Aktionen basierend auf Ihrer Benachrichtigung auszuführen. Wenn Benutzeraktionen in einer Registerkarten-App erforderlich sind, verwenden Sie Aktivitätsfeedbenachrichtigungen anstelle eines Agents. Stellen Sie sicher, dass Benutzer über ein klares Verständnis dafür verfügen, warum sie eine Benachrichtigung erhalten haben. Gute Benachrichtigungen umfassen die folgenden Elemente:

  • Was ist geschehen? Klare Angaben dazu, wodurch die Benachrichtigung ausgelöst wurde.

  • Was war das Ergebnis? Es muss klar sein, welches Element aktualisiert wird, um die Benachrichtigung zu erhalten.

  • Wer oder was hat es ausgelöst? Wer oder was die Aktion ausgeführt hat, die dazu geführt hat, dass die Benachrichtigung gesendet wurde.

  • Was können die Benutzer als Reaktion darauf tun? Erleichtern Sie es Ihren Benutzern, Aktionen basierend auf Ihren Benachrichtigungen durchzuführen.

  • Wie können Benutzer sich vom Erhalt von Benachrichtigungen abmelden? Sie müssen einen Pfad bereitstellen, über den Benutzer weitere Benachrichtigungen deaktivieren können.

Um Nachrichten an eine große Gruppe von Benutzern zu senden, z. B. an Ihre Organisation, installieren Sie Ihre App proaktiv mithilfe von Graph.

So aktualisieren oder löschen Sie eine proaktive Nachricht, die von einem reinen Benachrichtigungs-Agent gesendet wurde:

  1. Behalten Sie den Überblick über die gesendeten Nachrichten, indem Sie ihre Nachrichten-IDs oder Unterhaltungsreferenzen speichern, wenn Sie die proaktive Nachricht senden.

  2. Verwenden context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity) Sie oder context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId) Methoden zum Aktualisieren oder Löschen der ursprünglichen Nachricht.

Geplante Nachrichten

Wenn Sie proaktives Messaging verwenden, um geplante Nachrichten an Benutzer zu senden, überprüfen Sie, ob Ihre Zeitzone auf ihre Zeitzone aktualisiert wurde. Dadurch wird sichergestellt, dass die Nachrichten zum entsprechenden Zeitpunkt an die Benutzer übermittelt werden. Zu den Planungsnachrichten gehören:

  • Warum erhält der Benutzer die Nachricht? Erleichtern Sie es Ihren Benutzern, zu verstehen, warum sie die Nachricht erhalten.

  • Was kann der Benutzer als Nächstes tun? Benutzer können die erforderliche Aktion basierend auf dem Nachrichteninhalt ausführen.

Proaktives Installieren Ihrer App mit Graph

Sie können die Graph-API verwenden, um Ihre App proaktiv für Ihre Benutzer zu installieren. Speichern Sie die erforderlichen Werte aus dem conversationUpdate Ereignis zwischen, das Ihre App bei der Installation empfängt.

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

Weitere Informationen finden Sie unter Installieren von Apps für Benutzer in der Graph-Dokumentation und proaktive Agent-Installation und Messaging in Teams mit Graph.

Beispiele

Stellen Sie sicher, dass Sie authentifiziert sind und über ein Bearertoken verfügen, bevor Sie eine neue Konversation mit der REST-API erstellen. Im Folgenden finden Sie REST-APIs zum Erstellen einer Konversation in verschiedenen Kontexten:

  • REST-API zum Erstellen einer Unterhaltung in einem Einzelchat.

  • REST-API zum Erstellen einer Unterhaltung in einem Kanal.

  • REST-API zum Aktualisieren der Nachricht in einer Konversation: Um eine vorhandene Aktivität in einer Konversation zu aktualisieren, fügen Sie die conversationId und activityId in den Anforderungsendpunkt ein. Um dieses Szenario abzuschließen, müssen Sie die vom ursprünglichen POST-Aufruf zurückgegebene Aktivitäts-ID zwischenspeichern.

    PUT {Service URL of your agent}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Um eine vorhandene Aktivität innerhalb einer Unterhaltung zu aktualisieren, schließen Sie conversationId und activityId in den Anforderungsendpunkt ein. Um dieses Szenario abzuschließen, müssen Sie die activity ID vom ursprünglichen POST-Aufruf zurückgegebenen Daten zwischenspeichern. Wenn der Aufruf erfolgreich ist, gibt die API mit dem folgenden Antwortobjekt zurück.

    {
    "id": "{{activityID}}"
}

Beispiele

Der folgende Code zeigt, wie Sie proaktive Nachrichten mithilfe des Teams SDK (Teams KI-Bibliothek) senden können:

// Save the conversation ID and schedule a proactive reminder on install
teams.OnInstall(async (context, cancellationToken) =>
{
    context.Storage.Set(context.Activity.From.AadObjectId!, context.Activity.Conversation.Id);
    await context.Send("Hi! I am going to remind you to say something to me soon!", cancellationToken);
    notificationQueue.AddReminder(context.Activity.From.AadObjectId!, Notifications.SendProactive, 10_000);
});
 
// Send proactive message using stored conversation ID
public static class Notifications
{
    public static async Task SendProactive(string userId)
    {
        var conversationId = (string?)storage.Get(userId);
        if (conversationId is null) return;
        await app.Send(conversationId, "Hey! It's been a while. How are you?");
    }
}

Codebeispiele

Die folgende Tabelle enthält Codebeispiele, die den grundlegenden Unterhaltungsfluss und proaktives Messaging in eine Teams-Anwendung mithilfe des Teams SDK integrieren:

Beispielname Beschreibung .NET Node.js Python Manifest
Grundlagen zu Teams-Unterhaltungen Diese Beispiel-App zeigt, wie Sie verschiedene Agent-Unterhaltungsereignisse verwenden, die im Teams SDK v2 für den persönlichen und Teams-Bereich verfügbar sind. View View View View
Proaktive Bot-Nachricht Dieses Beispiel zeigt, wie Sie eine Unterhaltungs-ID aus einer Installationsaktivität erfassen und speichern und sie verwenden, um sofortige und verzögerte proaktive Nachrichten an einen Benutzer zu senden. View View View –

Nächste Schritte

Formatieren von Agent-Nachrichten

Siehe auch

  • Last updated on