Freigeben über

Kanal- und Gruppenchatunterhaltungen mit einem Bot

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt bots – v3 SDK im Ordner Legacy SDKs der Dokumentation.

Um den Microsoft Teams-Bot in einem Team- oder Gruppenchat zu installieren, fügen Sie ihrem Bot den teams Bereich oder groupchat hinzu. Dadurch können alle Mitglieder der Unterhaltung mit Ihrem Bot interagieren. Nachdem der Bot installiert wurde, hat er Zugriff auf Metadaten zur Unterhaltung, z. B. die Liste der Unterhaltungsmitglieder. Wenn er in einem Team installiert ist, hat der Bot Außerdem Zugriff auf Details zu diesem Team und die vollständige Liste der Kanäle.

Bots in einer Gruppe oder einem Kanal empfangen nachrichten nur, wenn sie erwähnt @botnamewerden. Sie erhalten keine weiteren Nachrichten, die an die Unterhaltung gesendet werden. Der Bot muss direkt @mentioned werden. Ihr Bot empfängt keine Nachricht, wenn das Team oder der Kanal erwähnt wird oder wenn jemand auf eine Nachricht von Ihrem Bot ohne @mentioning diese antwortet.

Hinweis

  • RSC für alle Chatnachrichten ist nur in der öffentlichen Entwicklervorschau verfügbar.
  • Mithilfe der ressourcenspezifischen Zustimmung (Resource-Specific Consent, RSC) können Bots alle Kanalnachrichten in Teams empfangen, in denen sie installiert sind, ohne zu sein @mentioned. Weitere Informationen finden Sie unter Empfangen aller Kanalnachrichten mit RSC.
  • Das Veröffentlichen einer Nachricht oder einer adaptiven Karte in einem privaten Kanal wird nicht unterstützt.

Im folgenden Video erfahren Sie mehr über Kanal- und Gruppenchatunterhaltungen mit einem Bot:


Richtlinien für den Entwurf

Im Gegensatz zu persönlichen Chats muss Ihr Bot in Gruppenchats und Kanälen eine kurze Einführung bereitstellen. Sie müssen diese und weitere Botentwurfsrichtlinien befolgen. Weitere Informationen zum Entwerfen von Bots in Teams finden Sie unter Entwerfen von Botunterhaltungen in Kanälen und Chats.

Jetzt können Sie neue Konversationsthreads erstellen und verschiedene Unterhaltungen in Kanälen ganz einfach verwalten.

Erstellen neuer Konversationsthreads

Wenn Ihr Bot in einem Team installiert ist, müssen Sie einen neuen Konversationsthread erstellen, anstatt auf einen vorhandenen zu antworten. Manchmal ist es schwierig, zwischen zwei Unterhaltungen zu unterscheiden. Wenn die Unterhaltung einen Thread enthält, ist es einfacher, verschiedene Unterhaltungen in Kanälen zu organisieren und zu verwalten. Dies ist eine Form von proaktivem Messaging.

Als Nächstes können Sie Erwähnungen mithilfe des entities -Objekts abrufen und Ihren Nachrichten mithilfe des Mention -Objekts Erwähnungen hinzufügen.

Arbeiten mit Erwähnungen

Jede Nachricht an Ihren Bot von einer Gruppe oder einem Kanal enthält einen @mention mit seinem Namen im Nachrichtentext. Ihr Bot kann auch andere Benutzer abrufen, die in einer Nachricht erwähnt werden, und allen gesendeten Nachrichten Erwähnungen hinzufügen. Bots in Gruppenchats ermöglichen Benutzererwähnungen mithilfe von @mention. Sie unterstützen @everyone jedoch keine Erwähnungen.

Sie müssen auch die @mentions aus dem Inhalt der Nachricht entfernen, die Ihr Bot empfängt.

Abrufen von Erwähnungen

Erwähnungen werden im -Objekt in der entities Nutzlast zurückgegeben und enthalten sowohl die eindeutige ID des Benutzers als auch den Namen des erwähnten Benutzers. Der Text der Nachricht enthält auch die Erwähnung, z<at>@John Smith<at>. B. . Verlassen Sie sich jedoch nicht auf den Text in der Nachricht, um Informationen über den Benutzer abzurufen. Es ist möglich, dass die Person, die die Nachricht sendet, sie ändert. Verwenden Sie daher das entities -Objekt.

Sie können alle Erwähnungen in der Nachricht abrufen, indem Sie die GetMentions Funktion im Bot Builder SDK aufrufen, das ein Array von Mention -Objekten zurückgibt.

Der folgende Code zeigt ein Beispiel für das Abrufen von Erwähnungen:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Hinzufügen von Erwähnungen zu Ihren Nachrichten

Es gibt zwei Arten von Erwähnungen:

Hinweis

Benutzer-Erwähnung und Tag-Erwähnung werden sowohl für SMS als auch für adaptive Karten unterstützt.

benutzer Erwähnung

Ihr Bot kann andere Benutzer in Nachrichten Erwähnung, die in Kanälen gepostet wurden.

Das Mention -Objekt verfügt über zwei Eigenschaften, die Sie wie folgt festlegen müssen:

  • Fügen Sie @username in den Nachrichtentext ein.
  • Schließen Sie das Erwähnung -Objekt in die Entitätsauflistung ein.

Das Bot Framework SDK stellt Hilfsmethoden und -objekte zum Erstellen von Erwähnungen bereit.

Der folgende Code zeigt ein Beispiel für das Hinzufügen von Erwähnungen zu Ihren Nachrichten:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Jetzt können Sie eine Einführungsnachricht senden, wenn Ihr Bot zum ersten Mal installiert oder einer Gruppe oder einem Team hinzugefügt wird.

Unterstützung für Microsoft Entra Objekt-ID und UPN in Benutzer-Erwähnung

Bots unterstützen zusätzlich zu den vorhandenen IDs Erwähnung Benutzer-IDs, z. B. Microsoft Entra Objekt-ID und Benutzerprinzipalname (User Principle Name, UPN). Eingehende Webhooks unterstützen Erwähnung von Benutzern in adaptiver Karte mit der Microsoft Entra Objekt-ID und dem UPN.

Der folgende Codeausschnitt zeigt ein Beispiel für die Erwähnung von Benutzern mit Entra-Objekt-ID und UPN in einer SMS:

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };

// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);

Der folgende Codeausschnitt zeigt ein Beispiel für die Erwähnung von Benutzern mit Entra-Objekt-ID und UPN in einer adaptiven Karte:

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com" ,// User Principle Name
            "name": "Adele"
    }
}

Tag-Erwähnung

Ihr Bot kann Tags in SMS-Nachrichten und adaptive Karten in Kanälen Erwähnung. Wenn der Bot @mentions das Tag in einem Kanal verwendet, wird das Tag hervorgehoben, und die personen, die dem Tag zugeordnet sind, werden benachrichtigt. Wenn ein Benutzer mit der Maus auf das Tag zeigt, wird ein Popupfenster mit den Tagdetails angezeigt.

Erwähnen von Tags in einer SMS

Fügen Sie im mention.properties -Objekt die -Eigenschaft 'type': 'tag'hinzu. Wenn die Eigenschaft 'type': 'tag' nicht hinzugefügt wird, behandelt der Bot die Erwähnung als Benutzer Erwähnung.

Beispiel:

Wird type:tag als in Properties ChannelAccount hinzugefügt.

SDK-Referenz

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken);
Erwähnen von Tags in einer adaptiven Karte

Fügen Sie im Schema der adaptiven Karte unter dem mentioned -Objekt die "type": "tag" -Eigenschaft hinzu. Wenn die "type": "tag" Eigenschaft nicht hinzugefügt wird, behandelt der Bot die Erwähnung als Benutzer Erwähnung.

Sie können die Liste der im Kanal verfügbaren Tags mithilfe der LIST TEAMWORKTags-API abrufen.

Beispiel:

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​}
Abfrageparameter
Name Beschreibung
type Der Typ der Erwähnung. Der unterstützte Typ ist tag.
id Der eindeutige Bezeichner für das Tag. Weitere Informationen finden Sie unter teamworkTag.
Fehlercode
Statuscode Fehlercode Nachrichtenwerte Wiederholungsanforderung Entwickleraktion
400 Code: Bad Request Das erwähnte Tag mit der ID {id string} ist im aktuellen Team nicht vorhanden.
Tag kann nur im Kanal erwähnt werden
Ungültiges erwähntes Tag, da im Team kein Tag vorhanden ist		 Nein Erneutes Auswerten der Anforderungsnutzlast auf Fehler. Überprüfen Sie die zurückgegebene Fehlermeldung auf Details.
502 Code: Bad Gateway Ungültige Teamgruppen-ID
Falsch formatierte Mandanten-ID für das Tag
Erwähnungs-ID kann nicht aufgelöst werden		 Nein Wiederholen Sie den Vorgang manuell.
Einschränkungsgrenzwerte

Jede Anforderung kann anhand mehrerer Grenzwerte ausgewertet werden, abhängig vom Bereich, dem Fenstertyp (kurz und lang), der Anzahl der Tags pro Nachricht und anderen Faktoren. Die erste zu erreichende Einschränkung löst ein Einschränkungsverhalten aus.

Stellen Sie sicher, dass Sie die Drosselungsgrenzwerte nicht überschreiten, um eine fehlerhafte Nachrichtenübermittlung zu vermeiden. Beispielsweise kann ein Bot nur zwei Nachrichten mit Tags Erwähnung in einem Fünf-Sekunden-Fenster senden, und jede Nachricht kann nur bis zu 10 Tags enthalten.

In der folgenden Tabelle sind die Drosselungsgrenzwerte für Tagerwähnungen in einem Bot aufgeführt:

Umfang Fenstertyp Anzahl der Tags pro Nachricht Zeitfenster (Sek.) Maximale Anzahl von Nachrichten pro Zeitfenster
Pro Bot und Thread Kurz 10 5 2
  Lang 10 60 5
Alle Bots pro Thread Kurz 10 5 4
  Long 10 60 5
Begrenzungen
  • Tagerwähnungen werden nur im Bot-zu-Client-Nachrichtenfluss mit Text und adaptiver Karte unterstützt.
  • Tagerwähnungen werden in freigegebenen und privaten Kanälen nicht unterstützt.
  • Tagerwähnungen werden in Connectors nicht unterstützt.
  • Tagerwähnungen unterstützen den Aufrufflow in einem Bot nicht.

Senden einer Nachricht bei der Installation

Wenn Ihr Bot zum ersten Mal der Gruppe oder dem Team hinzugefügt wird, muss eine Einführungsnachricht gesendet werden. Die Nachricht muss eine kurze Beschreibung der Features des Bots und deren Verwendung enthalten. Sie müssen das conversationUpdate Ereignis mit dem teamMemberAdded EventType abonnieren. Das Ereignis wird gesendet, wenn ein neues Teammitglied hinzugefügt wird. Überprüfen Sie, ob das neu hinzugefügte Mitglied der Bot ist. Weitere Informationen finden Sie unter Senden einer Begrüßungsnachricht an ein neues Teammitglied.

Sie können eine persönliche Nachricht an jedes Mitglied des Teams senden, wenn der Bot hinzugefügt wird. Rufen Sie hierzu die Teamliste ab, und senden Sie jedem Benutzer eine direkte Nachricht.

Hinweis

Stellen Sie sicher, dass die vom Bot gesendete Nachricht relevant ist und der anfänglichen Nachricht einen Mehrwert bietet und die Benutzer nicht spamt.

Senden Sie in den folgenden Fällen keine Nachricht:

  • Wenn das Team groß ist, z. B. größer als 100 Mitglieder. Ihr Bot kann als Spam angesehen werden, und die Person, die ihn hinzugefügt hat, kann Beschwerden erhalten. Sie müssen das Wertversprechen Ihres Bots klar an alle Personen kommunizieren, die die Willkommensnachricht sehen.
  • Ihr Bot wird zuerst in einer Gruppe oder einem Kanal erwähnt, anstatt zuerst einem Team hinzugefügt zu werden.
  • Eine Gruppe oder ein Kanal wird umbenannt.
  • Ein Teammitglied wird einer Gruppe oder einem Kanal hinzugefügt.

Teams-Botbeispiele

Codebeispiel

Vollständige Arbeitsbeispiele zur Veranschaulichung der Funktionalität finden Sie in den folgenden Teams-Beispielen für Bot Framework:

Beispielname Beschreibung .NET Node.js Python Manifest
Teams-Unterhaltungsbot In diesem Beispiel wird gezeigt, wie Verschiedene Botunterhaltungsereignisse verwendet werden, die in Bot Framework v4 für den persönlichen Bereich und den Teams-Bereich verfügbar sind. View View View View
Authentifizierung mit OAuthPrompt Dieses Beispiel zeigt die Authentifizierung und grundlegendes Messaging in Bot Framework v4. View View View View
Teams-Dateiupload In diesem Beispiel wird gezeigt, wie Dateien mit einem Bot in einer 1:1-Konversation verwendet werden. View View View View
Dialog (in TeamsJS v1.x als Aufgabenmodul bezeichnet) In diesem Beispiel wird gezeigt, wie Sie ein Dialogfeld und Werte aus Karten darin für eine Nachrichtenerweiterung verwenden. View View View View
Starten eines neuen Threads in einem Kanal In diesem Beispiel wird die Verwendung eines neuen Threads in einem Kanal mithilfe eines Bots veranschaulicht. View View View View
Lokalisierung von Teams-Apps In diesem Beispiel wird gezeigt, wie Sie die Lokalisierung von Teams-Apps mithilfe eines Bots und einer Registerkarte verwenden. View View – View

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung zum Erstellen eines Teams-Konversationsbots.

Nächster Schritt

Abonnieren von Unterhaltungsereignissen

Siehe auch