Freigeben über

Kanal und Gruppenchatunterhaltungen mit einem Microsoft Teams-Bot

  • Artikel

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 .

Mit Microsoft Teams können Benutzer Bots in ihre Kanal- oder Gruppenchatunterhaltungen einbinden. Durch das Hinzufügen eines Bots zu einem Team oder Chat können alle Benutzer der Unterhaltung die Botfunktionalität direkt in der Unterhaltung nutzen. Sie können auch auf Teams-spezifische Funktionen in Ihrem Bot zugreifen, z. B. das Abfragen von Teaminformationen und @mentioning Benutzern.

Chat in Kanälen und Gruppenchats unterscheidet sich von persönlichem Chat darin, dass der Benutzer den @mention Bot benötigt. Wenn ein Bot in mehreren Bereichen wie persönlichem Chat, Gruppenchat oder Kanal verwendet wird, müssen Sie ermitteln, aus welchem Bereich die Botnachrichten stammen, und sie entsprechend verarbeiten.

Entwerfen eines großartigen Bots für Kanäle oder Gruppen

Bots, die einem Team hinzugefügt werden, werden zu einem anderen Teammitglied und können teil der Unterhaltung sein @mentioned . Tatsächlich empfangen Bots Nachrichten nur, wenn sie sind @mentioned, sodass andere Unterhaltungen im Kanal nicht an den Bot gesendet werden.

Ein Bot in einer Gruppe oder einem Kanal sollte Informationen bereitstellen, die für alle Mitglieder relevant und geeignet sind. Ihr Bot kann zwar alle informationen bereitstellen, die für die Benutzererfahrung relevant sind, aber bedenken Sie, dass Unterhaltungen mit dem Bot für jeden sichtbar sind. Daher sollte ein großartiger Bot in einer Gruppe oder einem Kanal allen Benutzern einen Mehrwert verleihen und sicherlich nicht versehentlich Informationen teilen, die für eine 1:1-Unterhaltung besser geeignet sind.

Ihr Bot, so wie er ist, kann in allen Bereichen völlig relevant sein, ohne dass mehr Arbeit erforderlich ist. In Teams ist nicht davon auszugehen, dass Ihr Bot in allen Bereichen funktioniert, aber Sie sollten sicherstellen, dass Ihr Bot einen Benutzerwert in den Bereichen bietet, die Sie unterstützen möchten.

Die Entwicklung eines Bots, der in Gruppen oder Kanälen funktioniert, verwendet einen Großteil der gleichen Funktionen wie persönliche Unterhaltungen. Zusätzliche Ereignisse und Daten in der Nutzlast stellen Teams-Gruppen- und Kanalinformationen bereit. Diese Unterschiede sowie die wichtigsten Unterschiede in der allgemeinen Funktionalität werden in den folgenden Abschnitten beschrieben.

Erstellen von Nachrichten

Weitere Informationen zu Bots, die Nachrichten in Kanälen erstellen, finden Sie unter Proaktives Messaging für Bots und insbesondere Erstellen einer Kanalunterhaltung.

Nachrichten empfangen

Für einen Bot in einer Gruppe oder einem Kanal erhält Ihr Bot zusätzlich zum regulären Nachrichtenschema auch die folgenden Eigenschaften:

  • channelData Weitere Informationen finden Sie unter Teams-Kanaldaten. Enthält in einem Gruppenchat spezifische Informationen für diesen Chat.
  • conversation.id Die Antwortketten-ID, die aus der Kanal-ID und der ID der ersten Nachricht in der Antwortkette besteht.
  • conversation.isGroup Ist true für Botnachrichten in Kanälen oder Gruppenchats.
  • conversation.conversationType Entweder groupChat oder channel.
  • entities Kann eine oder mehrere Erwähnungen enthalten. Weitere Informationen finden Sie unter Erwähnungen.

Antworten auf Nachrichten

Um auf eine vorhandene Nachricht zu antworten, rufen Sie ReplyToActivity in .NET oder session.send in Node.js auf. Das Bot Builder SDK kümmert sich um alle Details.

Wenn Sie sich für die Verwendung der REST-API entscheiden, können Sie auch den /conversations/{conversationId}/activities/{activityId} Endpunkt aufrufen.

In einem Kanal wird die Antwort auf eine Nachricht als Antwort auf die initiierende Antwortkette angezeigt. enthält conversation.id den Kanal und die Nachrichten-ID der obersten Ebene. Obwohl sich bot Framework um die Details kümmert, können Sie diese conversation.id nach Bedarf für zukünftige Antworten auf diesen Konversationsthread zwischenspeichern.

Bewährte Methode: Willkommensnachrichten in Teams

Wenn Ihr Bot zum ersten Mal der Gruppe oder dem Team hinzugefügt wird, ist es nützlich, eine Begrüßungsnachricht zu senden, die den Bot an alle Benutzer einführt. Die Willkommensnachricht sollte eine Beschreibung der Funktionalität und der Benutzervorteile des Bots enthalten. Im Idealfall sollte die Nachricht auch Befehle enthalten, damit der Benutzer mit der App interagieren kann. Stellen Sie hierzu sicher, dass Ihr Bot auf die conversationUpdate Nachricht mit dem teamsAddMembers eventType im channelData -Objekt antwortet. Stellen Sie sicher, dass die memberAdded ID die App-ID des Bots selbst ist, da dasselbe Ereignis gesendet wird, wenn ein Benutzer einem Team hinzugefügt wird. Weitere Informationen finden Sie unter Hinzufügen von Teammitgliedern oder Bots.

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

Es wird empfohlen, dass Ihr Bot in den folgenden Situationen keine Willkommensnachricht sendet:

  • Das Team ist groß (offensichtlich subjektiv, z. B. mehr als 100 Mitglieder). Ihr Bot kann als "Spam" angesehen werden, und die Person, die ihn hinzugefügt hat, kann Beschwerden erhalten, es sei denn, Sie kommunizieren klar das Wertversprechen Ihres Bots an alle, 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.

@ Erwähnungen

Da Bots in einer Gruppe oder einem Kanal nur antworten, wenn sie in einer Nachricht erwähnt werden ("@botname"), enthält jede nachricht, die von einem Bot in einem Gruppenkanal empfangen wird, einen eigenen Namen, und Sie müssen sicherstellen, dass ihre Nachrichtenanalyse dies verarbeitet. Darüber hinaus können Bots andere erwähnte Benutzer analysieren und Benutzer als Teil ihrer Nachrichten erwähnen.

Abrufen von Erwähnungen

Erwähnungen werden im Objekt als entities Nutzlast zurückgegeben und enthalten sowohl die eindeutige ID des Benutzers als auch in den meisten Fällen den Namen des erwähnten Benutzers. Sie können alle Erwähnungen in der Nachricht abrufen, indem Sie die GetMentions Funktion im Bot Builder SDK für .NET aufrufen, das ein Array von Mentioned -Objekten zurückgibt.

.NET-Beispielcode: Suchen und Entfernen @bot von Erwähnungen

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

Hinweis

Sie können auch die Teams-Erweiterungsfunktion GetTextWithoutMentionsverwenden, die alle Erwähnungen, einschließlich des Bots, entfernt.

Node.js Beispielcode: Suchen und Entfernen @bot von Erwähnungen

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

Sie können auch die Teams-Erweiterungsfunktion getTextWithoutMentionsverwenden, die alle Erwähnungen, einschließlich des Bots, entfernt.

Erstellen von Erwähnungen

Ihr Bot kann andere Benutzer in Nachrichten erwähnen, die in Kanälen gepostet werden. Dazu muss Ihre Nachricht die folgenden Aktionen ausführen:

  • Fügen Sie <at>@username</at> in den Nachrichtentext ein.
  • Schließen Sie das mention -Objekt in die Entitätsauflistung ein.

.NET-Beispiel

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

// Create reply activity
Activity replyActivity = activity.CreateReply();

// Construct text of the form @sender Hello
replyActivity.Text = "Hello ";
replyActivity.AddMentionToText(activity.From, MentionTextLocation.AppendText);

// Send the reply activity
await client.Conversations.ReplyToActivityAsync(replyActivity);

Node.js Beispiel

// User to mention
var toMention: builder.IIdentity = {
    name: 'John Doe',
    id: userId
};

// Create a message and add mention to it
var msg = new teams.TeamsMessage(session).text(teams.TeamsMessage.getTenantId(session.message));
var mentionedMsg = msg.addMentionToText(toMention);

// Post the message
var generalMessage = mentionedMsg.routeReplyToGeneralChannel();
session.send(generalMessage);

Beispiel: Ausgehende Nachricht mit erwähntem Benutzer

{
    "type": "message", 
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "28:9e52142b-5e5e-4d7b-bb3e- e82dcf620000",
        "name": "SchemaTestBot"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Zugreifen auf groupChat oder Kanalbereich

Ihr Bot kann nicht nur Nachrichten in Gruppen und Teams senden und empfangen. Beispielsweise kann es auch die Liste der Mitglieder abrufen, einschließlich ihrer Profilinformationen und der Liste der Kanäle. Weitere Informationen finden Sie unter Abrufen von Kontext für Ihren Microsoft Teams-Bot.

Siehe auch

Bot Framework-Beispiele.