Unterhaltung mit einem Microsoft Teams Bot

Wichtig

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

Eine Unterhaltung ist eine Reihe von Nachrichten, die zwischen Ihrem Bot und einem oder mehreren Benutzern gesendet werden. In Teams gibt es drei Arten von Unterhaltungen (auch als Bereiche bezeichnet):

  • teams Auch kanalunterhaltungen genannt, sichtbar für alle Mitglieder des Kanals.
  • personal Unterhaltungen zwischen Bots und einem einzelnen Benutzer.
  • groupChat Chatten Sie zwischen einem Bot und zwei oder mehr Benutzern.

Ein Bot verhält sich je nach Art der Unterhaltung, an der er beteiligt ist, geringfügig anders:

Damit der Bot in einem bestimmten Bereich funktioniert, sollte er als Unterstützung für diesen Bereich im Manifest aufgeführt werden. Bereiche werden in der Manifestreferenzdefiniert und weiter erläutert.

Proaktive Nachrichten

Bots können an einer Unterhaltung teilnehmen oder eine initiieren. Der Großteil der Kommunikation erfolgt als Reaktion auf eine andere Nachricht. Wenn ein Bot eine Unterhaltung initiiert, wird dies als proaktive Nachricht bezeichnet. Dazu gehören:

  • Willkommensnachrichten
  • Ereignisbenachrichtigungen
  • Abrufen von Nachrichten

Grundlagen zu Unterhaltungen

Jede Nachricht ist ein Activity-Objekt vom Typ messageType: message. Wenn ein Benutzer eine Nachricht sendet, postet Teams die Nachricht auf Ihrem Bot. Spezifisch erfolgt dies durch Senden eines JSON-Objekts an den Nachrichtenendpunkt des Bots. Ihr Bot überprüft die Nachricht, um ihren Typ zu ermitteln, und antwortet entsprechend.

Bots unterstützen auch Nachrichten im Ereignisstil. Weitere Informationen finden Sie unter Behandeln von Botereignissen in Microsoft Teams. Die Spracherkennung wird derzeit nicht unterstützt.

Nachrichten sind in allen Bereichen größtenteils gleich, aber es gibt Unterschiede in der Art und Weise, wie auf den Bot in der Benutzeroberfläche zugegriffen wird, und Unterschiede im Hintergrund, die Sie kennen müssen.

Grundlegende Unterhaltungen werden über den Bot Framework-Connector verarbeitet, eine einzelne REST-API, mit der Ihr Bot mit Teams und anderen Kanälen kommunizieren kann. Das Bot Builder SDK bietet einfachen Zugriff auf diese API, zusätzliche Funktionen zum Verwalten von Unterhaltungsfluss und -zustand sowie einfache Möglichkeiten, kognitive Dienste wie die Verarbeitung natürlicher Sprache (Natural Language Processing, NLP) zu integrieren.

Nachrichteninhalt

Ihr Bot kann Rich-Text, Bilder und Karten senden. Benutzer können Rich-Text und Bilder an Ihren Bot senden. Sie können den Inhaltstyp angeben, den Ihr Bot auf der Einstellungsseite Microsoft Teams für Ihren Bot verarbeiten kann.

Format Vom Benutzer zum Bot Vom Bot zum Benutzer Anmerkungen
Rich-Text
Bilder Maximal 1024×1024 und 1 MB im PNG-, JPEG- oder GIF-Format; Animierte GIF-Dateien werden nicht unterstützt.
Karten In der Teams Kartenreferenz finden Sie unterstützte Karten.
Emojis Teams unterstützt zurzeit Emojis über UTF-16, z. B. U+1F600 für graunendes Gesicht.

Weitere Informationen zu den Vom Bot Framework unterstützten Bot-Interaktionstypen, auf denen Bots in Teams basieren, finden Sie in der Bot Framework-Dokumentation zum Unterhaltungsfluss und verwandten Konzepten in der Dokumentation für das Bot Builder SDK für .NET und das Bot Builder SDK für Node.js.

Mitteilungsformatierung

Sie können die optionale TextFormat Eigenschaft von a message festlegen, um zu steuern, wie der Textinhalt Ihrer Nachricht gerendert wird. Eine ausführliche Beschreibung der unterstützten Formatierung in Botnachrichten finden Sie unter Nachrichtenformatierung. Sie können die optionale TextFormat Eigenschaft festlegen, um zu steuern, wie der Textinhalt Ihrer Nachricht gerendert wird.

Ausführliche Informationen dazu, wie Teams Textformatierungen in Teams unterstützt, finden Sie unter Textformatierung in Botnachrichten.

Weitere Informationen zum Formatieren von Karten in Nachrichten finden Sie unter Kartenformatierung.

Bildnachrichten

Bilder werden durch Hinzufügen von Anlagen zu einer Nachricht gesendet. Weitere Informationen zu Anlagen finden Sie in der Bot Framework-Dokumentation.

Bilder können höchstens 1024×1024 und 1 MB im PNG-, JPEG- oder GIF-Format sein. Animierte GIF-Dateien werden nicht unterstützt.

Es wird empfohlen, die Höhe und Breite jedes Bilds mithilfe von XML anzugeben. Wenn Sie Markdown verwenden, ist die Bildgröße standardmäßig 256×256. Beispiel:

  • Verwenden von <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • ![Duck on a rock](http://aka.ms/Fo983c) nicht verwenden

Empfangen von Nachrichten

Je nachdem, welche Bereiche deklariert werden, kann Ihr Bot Nachrichten in den folgenden Kontexten empfangen:

  • Persönlicher Chat Benutzer können in einer privaten Unterhaltung mit einem Bot interagieren, indem sie einfach den hinzugefügten Bot im Chatverlauf auswählen oder den Namen oder die App-ID in das Feld "An:" in einen neuen Chat eingeben.
  • Kanäle Ein Bot kann in einem Kanal erwähnt werden ("@Botname"), wenn er dem Team hinzugefügt wurde. Beachten Sie, dass für zusätzliche Antworten auf einen Bot in einem Kanal der Bot erwähnt werden muss. Sie antwortet nicht auf Antworten, in denen sie nicht erwähnt wird.

Bei eingehenden Nachrichten empfängt Ihr Bot ein Activity-Objekt vom Typ messageType: message . Obwohl das Activity Objekt andere Arten von Informationen enthalten kann, z. B. Kanalaktualisierungen, die an Ihren Bot gesendet werden, stellt der Typ die message Kommunikation zwischen Bot und Benutzer dar.

Ihr Bot empfängt eine Nutzlast, die die Benutzernachricht Text sowie andere Informationen über den Benutzer, die Quelle der Nachricht und Teams Informationen enthält. Beachten Sie Folgendes:

  • timestamp Datum und Uhrzeit der Nachricht in koordinierter Weltzeit (UTC).
  • localTimestamp Datum und Uhrzeit der Nachricht in der Zeitzone des Absenders.
  • channelId Immer "msteams". Dies bezieht sich auf einen Bot-Framework-Kanal, nicht auf einen Teams-Kanal.
  • from.id Eine eindeutige und verschlüsselte ID für diesen Benutzer für Ihren Bot; als Schlüssel geeignet, wenn Ihre App Benutzerdaten speichern muss. Es ist einzigartig für Ihren Bot und kann nicht direkt außerhalb Ihrer Bot-Instanz auf sinnvolle Weise verwendet werden, um diesen Benutzer zu identifizieren.
  • channelData.tenant.id Die Mandanten-ID für den Benutzer.

Hinweis

from.id ist eindeutig für Ihren Bot und kann nicht direkt außerhalb Ihrer Bot-Instanz auf sinnvolle Weise verwendet werden, um diesen Benutzer zu identifizieren.

Kombinieren von Kanal- und privaten Interaktionen mit Ihrem Bot

Bei der Interaktion in einem Kanal sollte Ihr Bot intelligent sein, bestimmte Unterhaltungen mit einem Benutzer offline zu schalten. Angenommen, ein Benutzer versucht, eine komplexe Aufgabe zu koordinieren, z. B. die Planung mit einer Gruppe von Teammitgliedern. Anstatt die gesamte Sequenz von Interaktionen für den Kanal sichtbar zu haben, sollten Sie erwägen, eine persönliche Chatnachricht an den Benutzer zu senden. Ihr Bot sollte in der Lage sein, den Benutzer problemlos zwischen persönlichen Unterhaltungen und Kanalunterhaltungen zu wechseln, ohne den Status zu verlieren.

Hinweis

Vergessen Sie nicht, den Kanal zu aktualisieren, wenn die Interaktion abgeschlossen ist, um die anderen Teammitglieder zu benachrichtigen.

Beispiel für ein vollständiges eingehendes Schema

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot",
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Hinweis

Das Textfeld für eingehende Nachrichten enthält manchmal Erwähnungen. Achten Sie darauf, diese ordnungsgemäß zu überprüfen und zu entfernen. Weitere Informationen finden Sie unter Erwähnungen.

Teams Kanaldaten

Das channelData Objekt enthält Teams-spezifische Informationen und ist die endgültige Quelle für Team- und Kanal-IDs. Sie sollten diese IDs zwischenspeichern und als Schlüssel für den lokalen Speicher verwenden.

Das channelData Objekt ist nicht in Nachrichten in persönlichen Unterhaltungen enthalten, da diese außerhalb eines Kanals stattfinden.

Ein typisches channelData-Objekt in einer Aktivität, die an Ihren Bot gesendet wird, enthält die folgenden Informationen:

  • eventTypeTeams Ereignistyp; wird nur in Fällen von Kanaländerungsereignissenübergeben.
  • tenant.idAzure Active Directory Mandanten-ID; in allen Kontexten übergeben.
  • team Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.
  • channel Wird nur in Kanalkontexten übergeben, wenn der Bot erwähnt wird, oder für Ereignisse in Kanälen in Teams, in denen der Bot hinzugefügt wurde.
  • channelData.teamsTeamId Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten.
  • channelData.teamsChannelId Veraltet. Diese Eigenschaft ist nur aus Gründen der Abwärtskompatibilität enthalten.

ChannelData-Beispielobjekt (channelCreated-Ereignis)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

.NET-Beispiel

Das Paket "Microsoft.Bot.Connector.Teams NuGet" stellt ein TeamsChannelData spezielles Objekt bereit, das Eigenschaften für den Zugriff auf Teams-spezifische Informationen verfügbar macht.

TeamsChannelData channelData = activity.GetChannelData<TeamsChannelData>();
string tenantId = channelData.Tenant.Id;

Senden von 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 verarbeitet alle Details.

Wenn Sie die REST-API verwenden, können Sie auch den /v3/conversations/{conversationId}/activities/{activityId} Endpunkt aufrufen.

Der Nachrichteninhalt selbst kann einfachen Text oder einige der vom Bot Framework bereitgestellten Karten und Kartenaktionenenthalten.

Bitte beachten Sie, dass Sie in Ihrem ausgehenden Schema immer dasselbe wie das empfangene Schema verwenden serviceUrl sollten. Beachten Sie, dass der Wert von serviceUrl Stabil eher stabil ist, sich aber ändern kann. Wenn eine neue Nachricht eintrifft, sollte Ihr Bot den gespeicherten Wert von serviceUrl überprüfen.

Aktualisieren von Nachrichten

Anstatt dass Ihre Nachrichten statische Momentaufnahmen von Daten sind, kann Ihr Bot Nachrichten nach dem Senden dynamisch inline aktualisieren. Sie können dynamische Nachrichtenupdates für Szenarien wie Abrufaktualisierungen, das Ändern verfügbarer Aktionen nach einem Tastendruck oder andere asynchrone Zustandsänderungen verwenden.

Die neue Nachricht muss nicht mit dem originalen Typ übereinstimmen. Wenn die ursprüngliche Nachricht beispielsweise eine Anlage enthielt, kann es sich bei der neuen Nachricht um eine einfache Textnachricht handeln.

Hinweis

Sie können nur Inhalte aktualisieren, die in Einzelanlagennachrichten und Karusselllayouts gesendet werden. Das Veröffentlichen von Updates für Nachrichten mit mehreren Anlagen im Listenlayout wird nicht unterstützt.

REST-API

Um eine Nachrichtenaktualisierung auszustellen, führen Sie einfach eine PUT-Anforderung für den /v3/conversations/<conversationId>/activities/<activityId>/ Endpunkt mithilfe einer bestimmten Aktivitäts-ID aus. Um dieses Szenario abzuschließen, sollten Sie die Aktivitäts-ID zwischenspeichern, die vom ursprünglichen POST-Aufruf zurückgegeben wird.

PUT /v3/conversations/19%3Aja0cu120i1jod12j%40skype.net/activities/012ujdo0128
{
    "type": "message",
    "text": "This message has been updated"
}

.NET-Beispiel

Sie können die UpdateActivityAsync Methode im Bot Builder SDK verwenden, um eine vorhandene Nachricht zu aktualisieren.

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
  if (activity.Type == ActivityTypes.Message)
  {
    ConnectorClient connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    Activity reply = activity.CreateReply($"You sent {activity.Text} which was {activity.Text.Length} characters");
    var msgToUpdate = await connector.Conversations.ReplyToActivityAsync(reply);
    Activity updatedReply = activity.CreateReply($"This is an updated message");
    await connector.Conversations.UpdateActivityAsync(reply.Conversation.Id, msgToUpdate.Id, updatedReply);
  }
}

Node.js Beispiel

Sie können die session.connector.update Methode im Bot Builder SDK verwenden, um eine vorhandene Nachricht zu aktualisieren.

function sendCardUpdate(bot, session, originalMessage, address) {

  var origAttachment = originalMessage.data.attachments[0];
  origAttachment.content.subtitle = 'Assigned to Larry Jin';

  var updatedMsg = new builder.Message()
    .address(address)
    .textFormat(builder.TextFormat.markdown)
    .addAttachment(origAttachment)
    .toMessage();

  session.connector.update(updatedMsg, function(err, addresses) {
    if (err) {
      console.log(`Could not update the message`);
    }
  });
}

Starten einer Unterhaltung (proaktives Messaging)

Sie können eine persönliche Unterhaltung mit einem Benutzer erstellen oder eine neue Antwortkette in einem Kanal für Ihren Team-Bot starten. Auf diese Weise können Sie Ihre Benutzer benachrichtigen, ohne dass sie zuerst kontakt mit Ihrem Bot initiieren müssen. Weitere Informationen finden Sie in den folgenden Themen:

Weitere allgemeine Informationen zu Unterhaltungen, die von Bots gestartet werden, finden Sie unter Proaktives Messaging für Bots.

Löschen von Nachrichten

Nachrichten können mithilfe der delete() Connectors-Methode im BotBuilder SDKgelöscht werden.

bot.dialog('BotDeleteMessage', function (session: builder.Session) {
  var msg = new teams.TeamsMessage(session).text("Bot will delete this message in 5 sec.")
  bot.send(msg, function (err, response) {
    if (err) {
      console.log(err);
      session.endDialog();
    }

    console.log('Proactive message response:');
    console.log(response);
    console.log('---------------------------------------------------')
    setTimeout(function () {
      var activityId: string = null;
      var messageAddress: builder.IChatConnectorAddress = null;
      if (response[0]){
        messageAddress = response[0];
        activityId = messageAddress.id;
      }

      if (activityId == null)
      {
        console.log('Message failed to send.');
        session.endDialog();
        return;
      }

      // Bot delete message
      let address: builder.IChatConnectorAddress  = {
        channelId: 'msteams',
        user: messageAddress.user,
        bot: messageAddress.bot,
        id : activityId,
        serviceUrl : (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
        conversation: {
          id: session.message.address.conversation.id
        }
      };

      connector.delete(address, function (err) {
        if (err)
        {
          console.log(err);
        }
        else
        {
          console.log("Message: " + activityId + " deleted successfully.");
        }

        // Try editing deleted message would fail
        var newMsg = new builder.Message().address(address).text("To edit message.");
        connector.update(newMsg.toMessage(), function (err, address) {
          if (err)
          {
            console.log(err);
            console.log('Deleted message can not be edited.');
          }
          else
          {
            console.log("There is something wrong. Message: " + activityId + " edited successfully.");
            console.log(address);
          }

          session.endDialog();
        });
      });
    }, 5000);
  });
})