Unterhaltung mit einem Microsoft Teams-Bot führen

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

• teams Sie werden auch als Kanalunterhaltungen bezeichnet und sind für alle Mitglieder des Kanals sichtbar.
• personal Unterhaltungen zwischen Bots und einem einzelnen Benutzer.
• groupChatChat zwischen einem Bot und zwei oder mehr Benutzern.

Ein Bot verhält sich etwas anders, je nachdem, an welcher Art von Unterhaltung er beteiligt ist:

• Bots in Kanal- und Gruppenchatunterhaltungen erfordern, dass @mention der Benutzer den Bot in einem Kanal aufruft.
• Bots in Einzelbenutzerunterhaltungen benötigen @mention keinen – der Benutzer kann einfach tippen.

Damit der Bot in einem bestimmten Bereich funktioniert, sollte er im Manifest als unterstützend für diesen Bereich aufgeführt werden. Bereiche werden in der Manifestreferenz definiert und näher erläutert.

Proaktive Nachrichten

Bots können an einer Unterhaltung teilnehmen oder eine initiieren. Die meiste Kommunikation erfolgt als Reaktion auf eine andere Nachricht. Wenn ein Bot eine Unterhaltung initiiert, spricht man von einer proaktiven Nachricht. B.:

• Begrüßungsnachrichten
• Ereignisbenachrichtigungen
• Abrufen von Nachrichten

Grundlagen der Unterhaltung

Jede Nachricht ist ein Activity Objekt vom Typ messageType: message. Wenn ein Benutzer eine Nachricht sendet, sendet Teams die Nachricht an Ihren Bot. Insbesondere sendet er ein JSON-Objekt an den Messagingendpunkt Ihres Bots. Ihr Bot untersucht die Nachricht, um ihren Typ zu bestimmen, und antwortet entsprechend.

Bots unterstützen auch Nachrichten im Ereignisstil. Weitere Informationen finden Sie unter Behandlung von Botereignissen in Microsoft Teams. Sprache wird nicht unterstützt.

Die Nachrichten sind in der Regel in allen Bereichen gleich, aber es gibt Unterschiede in der Art und Weise, wie auf den Bot in der Benutzeroberfläche zugegriffen wird, und Unterschiede hinter den Kulissen, die Sie kennen müssen.

Grundlegende Unterhaltungen werden über den Bot Framework Connector abgewickelt, eine einzelne REST-API, die es Ihrem Bot ermöglicht, mit Teams und anderen Kanälen zu kommunizieren. Das Bot Builder SDK bietet einfachen Zugriff auf diese API, zusätzliche Funktionen zum Verwalten des Konversationsflusses und -zustands sowie einfache Möglichkeiten, kognitive Dienste wie die Verarbeitung natürlicher Sprache (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, den Ihr Bot verarbeiten kann, auf der Seite mit den Microsoft Teams-Einstellungen für Ihren Bot angeben.

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

Nachrichtenformatierung

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 Bot-Nachrichten 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 die Textformatierung in Teams unterstützt, finden Sie unter Textformatierung in Bot-Nachrichten.

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 maximal 1024×1024 MB und 1 MB im PNG-, JPEG- oder GIF-Format groß sein. Animierte GIF-Dateien werden nicht unterstützt.

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

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

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 den hinzugefügten Bot im Chatverlauf auswählen oder seinen Namen oder seine App-ID in das Feld "An:" in einem neuen Chat eingeben.
• Kanäle Ein Bot kann ("@botname") in einem Kanal erwähnt werden, wenn er dem Team hinzugefügt wurde. Beachten Sie, dass zusätzliche Antworten an einen Bot in einem Kanal die Erwähnung des Bots erfordern. Sie reagiert nicht auf Antworten, in denen sie nicht erwähnt wird.

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

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

• timestamp Datum und Uhrzeit der Nachricht in koordinierter Weltzeit (UTC).
• localTimestamp Das Datum und die 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; geeignet als Schlüssel, wenn Ihre App Benutzerdaten speichern muss. Es ist einzigartig für Ihren Bot und kann nicht direkt außerhalb Ihrer Bot-Instance auf sinnvolle Weise verwendet werden, um diesen Benutzer zu identifizieren.
• channelData.tenant.id Die Mandanten-ID für den Benutzer.

Kombinieren von Kanal- und privaten Interaktionen mit Ihrem Bot

Bei der Interaktion in einem Kanal sollte Ihr Bot bestimmte Unterhaltungen mit einem Benutzer intelligent offline nehmen. instanceAngenommen, ein Benutzer versucht, eine komplexe Aufgabe zu koordinieren, z. B. die Terminplanung mit einer Reihe von Teammitgliedern. Anstatt die gesamte Abfolge von Interaktionen für den Kanal sichtbar zu machen, sollten Sie eine persönliche Chatnachricht an den Benutzer senden. Ihr Bot sollte in der Lage sein, den Benutzer problemlos zwischen persönlichen und Kanalunterhaltungen zu wechseln, ohne den Status zu verlieren.

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

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.

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

• eventType Teams-Ereignistyp; wird nur bei Kanaländerungsereignissen übergeben.
• tenant.idMicrosoft Entra Mandanten-ID; in allen Kontexten übergeben.
• team Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.
  • id GUID für den Kanal.
  • name Name des Teams; nur bei Teamumbenennungsereignissen bestanden.
• 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.
  • id GUID für den Kanal.
  • name Kanalname; wird nur bei Kanaländerungsereignissen übergeben.
• 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.

Beispiel für ein channelData-Objekt (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 NuGet-Paket Microsoft.Bot.Connector.Teams stellt ein spezielles TeamsChannelData 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 in .NET oder session.send in Node.js anReplyToActivity. 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 Kartenaktionen enthalten.

Beachten Sie, dass Sie in Ihrem ausgehenden Schema immer dasselbe serviceUrl verwenden sollten, wie Sie es erhalten haben. Beachten Sie, dass der Wert von serviceUrl in der Regel stabil ist, sich aber ändern kann. Wenn eine neue Nachricht eingeht, sollte der Bot den gespeicherten Wert von serviceUrlüberprüfen.

Nachrichten aktualisieren

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 Umfrageaktualisierungen, das Ändern verfügbarer Aktionen nach dem Drücken einer Taste oder jede andere asynchrone Statusänderung verwenden.

Die neue Nachricht muss nicht mit dem ursprünglichen Typ übereinstimmen. Wenn die ursprüngliche Nachricht beispielsweise eine Anlage enthielt, kann die neue Nachricht instance eine Textnachricht sein.

REST-API

Um eine Nachrichtenaktualisierung auszugeben, führen Sie eine PUT-Anforderung für den /v3/conversations/<conversationId>/activities/<activityId>/ Endpunkt mit 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 wurde.

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 Teambot starten. Auf diese Weise können Sie Ihrem Benutzer oder Ihren Benutzern Nachrichten senden, ohne dass sie zuerst Kontakt mit Ihrem Bot aufnehmen müssen. Weitere Informationen finden Sie in den folgenden Artikeln:

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

Nachrichten löschen

Nachrichten können mit der connector.delete() Methode im BotBuilder SDK gelö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);
  });
})