Senden und Empfangen von Nachrichten

Konversationsbots kommunizieren mit Benutzern über Messaging und ermöglichen so nahtlose Interaktionen. Es kann reale Unterhaltungen mit Benutzern über Text- oder Sprachinteraktionen simulieren. Sie müssen sicherstellen, dass Botunterhaltungen interaktiv, dynamisch, adaptiv und benutzerfreundlich sind.

Sie können auch Zielnachrichten mit Ihrem Agent oder Ihrer Bot-App senden.

Nachrichteninhalt

Die Nachrichteninteraktion zwischen Ihrem Bot und dem Benutzer kann verschiedene Arten von Nachrichteninhalten umfassen, die:

Verwenden von Rich-Text-Nachrichten und Emojis

Ihr Teams-Bot kann Rich-Text und Emojis senden. Teams unterstützt Emojis über UTF-16, z. B. U+1F600 für ein grinsendes Gesicht.

Verwenden von Bildmeldungen

Damit bot-Nachrichten angezeigt werden, kann der Benutzer Bilder als Anlagen hinzufügen:

• Bilder können bis zu 1024 × 1.024 Pixel und 1 MB im PNG-, JPEG- oder GIF-Format sein. Animierte GIFs werden nicht unterstützt.

• Sie können die Höhe und Breite jedes Bilds mithilfe von XML angeben. In Markdown ist die Bildgröße standardmäßig 256×256. Zum Beispiel:

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

Weitere Informationen zu Anlagen finden Sie unter Hinzufügen von Medienanlagen zu Nachrichten.

Verwenden adaptiver Karten

Ein Konversationsbot kann adaptive Karten enthalten, die Geschäftsworkflows vereinfachen. Adaptive Karten bieten umfangreiche anpassbare Text-, Sprach-, Bild-, Schaltflächen- und Eingabefelder. Sie können adaptive Karten in einem Bot erstellen und in mehreren Apps wie Teams, Ihrer Website usw. angezeigt werden.

Weitere Informationen finden Sie unter:

• Adaptive Karten.
• Teams Karte Referenz für unterstützte Karten.

Der folgende Code zeigt ein Beispiel für das Senden einer einfachen adaptiven Karte:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": "Simple Adaptive Card example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Senden und Empfangen von Nachrichten

Das Senden und Empfangen von Nachrichten ist die Kernfunktion eines Bots.

In einem Chat ist jede Nachricht ein Activity Objekt vom Typ messageType: message. Wenn jemand eine Nachricht sendet, wird diese von Microsoft Teams an Ihren Bot gesendet. Teams sendet ein JSON-Objekt an den Messagingendpunkt Ihres Bots und lässt nur einen Endpunkt für Messaging zu. Ihr Bot überprüft dann die Nachricht, um ihren Typ zu ermitteln, und antwortet entsprechend.

Grundlegende Unterhaltungen werden über den Teams SDK Framework-Connector verwaltet, bei dem es sich um eine einzelne REST-API handelt. Diese API ermöglicht Es Ihrem Bot, mit Teams und anderen Kanälen zu kommunizieren. Das Bot Builder SDK bietet die folgenden Features:

• Einfacher Zugriff auf den Teams SDK Framework-Connector.
• Tools zum Verwalten des Konversationsflusses und -zustands.
• Einfache Möglichkeiten zum Hinzufügen von Cognitive Services, z. B. Verarbeitung natürlicher Sprache (Natural Language Processing, NLP).

Ihr Bot ruft Mithilfe der Text -Eigenschaft Nachrichten von Teams ab und kann einzelne oder mehrere Antworten an Benutzer zurücksenden.

Weitere Informationen finden Sie unter Benutzerzuordnung für Botnachrichten.

In der folgenden Tabelle sind die Aktivitäten aufgeführt, die Ihr Bot empfangen und maßnahmen ergreifen kann:

Empfangen einer Nachrichtenaktivität

Verwenden Sie die Text -Eigenschaft eines Activity -Objekts, um eine SMS zu empfangen. Verwenden Sie im Aktivitäts-Handler des Bots die Activity des Turn-Kontextobjekts, um eine einzelne Nachrichtenanforderung zu lesen.

Der folgende Code zeigt ein Beispiel für den Empfang einer Nachrichtenaktivität:

app.OnMessage(async context =>
{
    await context.Send($"Echo: {context.Activity.Text}");
});

app.on('message', async ({ activity, send }) => {
    await send(`Echo: '${activity.text}'`);
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    await ctx.send(f"Echo: {ctx.activity.text}")

{
    "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.Sending bold-italic rich text",
    "attachments": [
      {
            "contentType": "text/html",
            "content": "<div><div>Hello Teams TestBot. Sending <strong>bold</strong>-<em>italic</em> rich text.</div>\n</div>"
      } 
    ],
    "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"
}

Empfangen einer Lesebestätigung

Mit der Einstellung Lesebestätigungen in Teams kann der Absender einer Chatnachricht benachrichtigt werden, wenn seine Nachricht vom Empfänger in Einzel- und Gruppenchats gelesen wurde. Nachdem der Empfänger die Nachricht gelesen hat, wird neben der Nachricht das Angezeigte angezeigt. Sie haben auch die Möglichkeit, Ihren Bot für den Empfang von Lesebestätigungsereignissen über die Einstellung Lesebestätigungen zu konfigurieren. Das Lesebestätigungsereignis hilft Ihnen, die Benutzererfahrung auf folgende Weise zu verbessern:

• Sie können Ihren Bot so konfigurieren, dass er eine Folgenachricht sendet, wenn Ihr App-Benutzer die Nachricht im persönlichen Chat nicht gelesen hat.

• Sie können eine Feedbackschleife mithilfe von Lesebestätigungen erstellen, um die Benutzererfahrung Ihres Bots zu optimieren.

Stellen Sie Folgendes sicher, um Lesebestätigungsereignisse für Ihren Bot zu empfangen:

• Fügen Sie die RSC-BerechtigungChatMessageReadReceipt.Read.Chat wie folgt im App-Manifest hinzu:

  • App-Manifest v1.12 oder höher
  • App-Manifest v1.11 oder früher

  
  "webApplicationInfo": {
  
       "id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
       "resource": ""
  },
  "authorization": {
      "permissions": {
      "orgwide": [],
       "resourceSpecific": [
          {
          "name": "ChatMessageReadReceipt.Read.Chat",
          "type": "Application"
          }
          ]
       }
   }
  
  

Sie können RSC-Berechtigungen auch über Graph-API hinzufügen. Weitere Informationen finden Sie unter consentedPermissionSet.

• Überschreiben Sie die -Methode OnReadReceipt mit context.Activity.Value.LastReadMessageId.

  Die context.Activity.Value.LastReadMessageId-Methode ist nützlich, um zu bestimmen, ob die Nachricht von den Empfängern gelesen wird. Wenn kleiner compareMessageId oder gleich LastReadMessageIdist, wurde die Nachricht gelesen. Überschreiben Sie die OnReadReceipt -Methode zum Empfangen von Lesebestätigungen mit context.Activity.Value.LastReadMessageId der -Methode:

  app.OnReadReceipt(async context =>
  
  {
      var lastReadMessageId = context.Activity.Value.LastReadMessageId;
      await context.Send("User read the bot's message");
  });
  

Das folgende Beispiel zeigt eine Ereignisanforderung für Lesebestätigungen, die ein Bot empfängt:

    {
        "name": "application/vnd.microsoft.readReceipt",
        "type": "event",
        "timestamp": "2023-08-16T17:23:11.1366686Z",
        "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007",
        "channelId": "msteams",
        "serviceUrl": "https://smba.trafficmanager.net/amer/",
        "from": {
            "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw",
            "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5"
        },
        "conversation": {
            "conversationType": "personal",
            "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f",
            "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z"
        },
        "recipient": {
            "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb",
            "name": "Test Bot"
        },
        "channelData": {
            "tenant": {
                "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
            }
        },
        "value": {
            "lastReadMessageId": "1692206589131"
        }
    }
    

• Die Administratoreinstellung für Lesebestätigungen oder die Benutzereinstellung ist für den Mandanten aktiviert, damit der Bot die Lesebestätigungsereignisse empfängt. Der Administrator oder der Benutzer muss die Einstellung für Lesebestätigungen aktivieren oder deaktivieren.

Nachdem der Bot in einem Benutzer-zu-Bot-Chatszenario aktiviert wurde, empfängt der Bot sofort ein Lesebestätigungsereignis, wenn der Benutzer die Nachricht des Bots liest. Sie können die Benutzerbindung nachverfolgen, indem Sie die Anzahl der Ereignisse zählen, und Sie können auch eine kontextbezogene Nachricht senden.

Aktivität "Nachricht bearbeiten empfangen"

Wenn Sie eine Nachricht bearbeiten, erhält der Bot eine Benachrichtigung über die Nachrichtenbearbeitungsaktivität.

Um eine Benachrichtigung zur Nachrichtenaktivität in einem Bot zu erhalten, können Sie den Handler überschreiben OnMessageEdit .

Es folgt ein Beispiel für eine Benachrichtigung zur Nachrichtenaktivität bearbeiten mit, wenn eine gesendete Nachricht bearbeitet wird:The following is an example of a edit message activity notification using OnMessageEdit when a sent message is edited:

app.OnMessageEdit(async context =>
{
    await context.Send("message is updated");
}); 

app.on('messageEdit', async ({ activity, send }) => {
    const editedMessage = activity.text;
    await send(`The edited message is ${editedMessage}`);
});

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_PM4mubmQZsYPx7jDyLeLf_YVA9sVPV08KMAFMjJWB_EUGveb9EVDh9TslNp9qjnzEBy3kgw01Jf1Kg",
    "name":"Mike Wilber",
    "aadObjectId":"520e4d1e-2108-43ee-a092-46a9507c6200"caching
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1pweuGJ44RkB90tiJNQ_I6g3vyuP4CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqRPB"
},
"recipient":{
    "id":"28:0d569679-gb4j-479a-b0d8-238b6e6b1149",
    "name":"TestBot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"editMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

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

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

Senden einer Nachricht

Um eine SMS zu senden, geben Sie die Zeichenfolge an, die Sie als Aktivität senden möchten. Verwenden Sie im Aktivitätshandler des Bots die Methode des Turn-Kontextobjekts context.Send(...) , um eine einzelne Nachrichtenantwort zu senden. Verwenden Sie die -Methode des multiple context.Send(...) calls -Objekts, um mehrere Antworten zu senden.

Der folgende Code zeigt ein Beispiel für das Senden einer Nachricht, wenn ein Benutzer zu einer Unterhaltung hinzugefügt wird:

app.OnMembersAdded(async context =>
{
    foreach (var member in context.Activity.MembersAdded)
    {
        if (member.Id != context.Activity.Recipient.Id)
        {
            await context.Send("Hello and welcome!");
        }
    }
});

   app.on('membersAdded', async ({ activity, send }) => {
    for (const member of activity.membersAdded ?? []) {
        if (member.id !== activity.recipient.id) {
            await send(`Welcome to the team ${member.name}`);
        }
    }
});

@app.on_members_added
async def handle_members_added(ctx: ActivityContext):
    for member in ctx.activity.members_added:
        if member.id != ctx.activity.recipient.id:
            await ctx.send(f"Welcome your new team member {member.id}")

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "conversation": {
        "id": "a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
   },
   "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My bot's reply",
    "replyToId": "1632474074231"
}

HTTP Request: {Service URL of your bot}/v3/conversations/{conversationId}/activities

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "conversation": {
        "id":"a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
    },
    "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My bot's reply"
}

Nachrichten, die zwischen Benutzern und Bots gesendet werden, enthalten interne Kanaldaten in der Nachricht. Diese Daten ermöglichen es dem Bot, auf diesem Kanal ordnungsgemäß zu kommunizieren. Mit dem Bot Builder SDK können Sie die Nachrichtenstruktur ändern.

Aktivität "Empfangen von Nachrichten wiederherstellen"

Wenn Sie eine Nachricht wiederherstellen, erhält der Bot eine Benachrichtigung über die Wiederherstellen der Nachrichtenaktivität.

Um eine Benachrichtigung zur Wiederherstellen der Nachrichtenaktivität in einem Bot zu erhalten, können Sie den Handler überschreiben OnMessageUndelete .

Es folgt ein Beispiel für eine Wiederherstellen einer Nachrichtenaktivitätsbenachrichtigung mit OnMessageUndelete , wenn eine gelöschte Nachricht wiederhergestellt wird:

app.OnMessageUndelete(async context =>
{
    await context.Send("message is undeleted");
});

app.on('messageUndelete', async ({ activity, send }) => {
    const undeletedMessage = activity.text;
    await send(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
});

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1234",
    "name":"Testbot"
},
"entities":[
    {
           "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"undeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

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

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

Aktivität zum vorläufigen Löschen von Nachrichten empfangen

Wenn Sie eine Nachricht vorläufig löschen, erhält der Bot eine Benachrichtigung über die Aktivität des vorläufigen Löschens von Nachrichten.

Um eine Meldungsaktivitätsbenachrichtigung für vorläufiges Löschen in einem Bot zu erhalten, können Sie den Handler überschreiben OnMessageSoftDelete .

Das folgende Beispiel zeigt eine Meldungsaktivitätsbenachrichtigung mit vorläufigem Löschen, wenn OnMessageSoftDelete eine Nachricht vorläufig gelöscht wird:

app.OnMessageSoftDelete(async context =>
{
    await context.Send("message is soft deleted");
}); 

app.on('messageSoftDelete', async ({ activity, send }) => {
    const messageId = activity.id;
    await send(`The deleted message id is ${messageId}`);
});

{
"type":"messageDelete",
"timestamp":"2022-10-28T17:19:43.1612052Z",
"localTimestamp":"2022-10-28T10:19:43.1612052-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1235",
    "name":"Testbot"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"softDeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

Vom Bot gesendete Nachrichten aktualisieren und löschen

Ihr Bot kann Nachrichten nach dem Senden dynamisch aktualisieren, anstatt sie als statische Momentaufnahmen von Daten zu behalten. Nachrichten können auch mithilfe der -Methode des context.Api.Conversations.Activities.DeleteAsync(...) Teams SDK-Frameworks gelöscht werden.

Nachricht aktualisieren

Sie können dynamische Nachrichtenaktualisierungen für Szenarien wie Umfrageaktualisierungen, das Ändern verfügbarer Aktionen nach einem Tastendruck oder jede andere asynchrone Zustandsänderung verwenden.

Es ist nicht erforderlich, dass die neue Nachricht mit dem ursprünglichen Typ übereinstimmt. Wenn die ursprüngliche Nachricht beispielsweise einen Anhang enthielt, kann die neue Nachricht eine einfache Textnachricht sein.

app.OnMessage(async context =>
{
    // Send initial message
    var response = await context.Send("Your Message");
    var conversationId = context.Activity.Conversation.Id;
    var activityId = response.Id;

    var updatedActivity = new MessageActivity("The new text for the activity");

    await context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity);
});

app.on('message', async ({ activity, api, send }) => {
    // Send initial message
    const response = await send('Your Message');
    const conversationId = activity.conversation.id;
    const activityId = response.id;

    await api.conversations.activities(conversationId).update(activityId, {
        type: 'message',
        text: 'The new text for the activity'
    });
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Send initial message
    response = await ctx.send("Your Message")
    conversation_id = ctx.activity.conversation.id
    activity_id = response.id

    await ctx.api.conversations.activities(conversation_id).update(
        activity_id, MessageActivityInput(text="The new text for the activity")
    )

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 vom ursprünglichen POST-Aufruf zurückgegebene Aktivitäts-ID zwischenspeichern.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Nachdem Sie Nachrichten aktualisiert haben, aktualisieren Sie die vorhandene Karte bei der Schaltflächenauswahl für eingehende Aktivitäten.

Karten aktualisieren

Um die vorhandene Karte bei der Schaltflächenauswahl zu aktualisieren, können Sie ReplyToId von eingehenden Aktivitäten verwenden.

app.OnMessage(async context =>
{
    var conversationId = context.Activity.Conversation.Id;
    var activityId = context.Activity.ReplyToId;

    var updatedActivity = new MessageActivity();
    updatedActivity.Attachments.Add(card.ToAttachment());

    await context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity);
});

app.on('message', async ({ activity, api }) => {
    const conversationId = activity.conversation.id;
    const activityId = activity.replyToId;

    await api.conversations.activities(conversationId).update(activityId, {
        type: 'message',
        attachments: [card]
    });
});

@app.on_message
async def handle_update_card(ctx: ActivityContext[MessageActivity]):
    conversation_id = ctx.activity.conversation.id
    activity_id = ctx.activity.reply_to_id

    await ctx.api.conversations.activities(conversation_id).update(
        activity_id, MessageActivityInput().add_card(card)
    )

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 vom ursprünglichen POST-Aufruf zurückgegebene Aktivitäts-ID zwischenspeichern.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Nachdem Sie nun über aktualisierte Karten verfügen, können Sie Nachrichten mithilfe des Teams SDK-Frameworks löschen.

Löschen von Nachrichten

Im Teams SDK-Framework verfügt jede Nachricht über einen eindeutigen Aktivitätsbezeichner. Nachrichten können mithilfe der -Methode des context.Api.Conversations.Activities.DeleteAsync(...) Teams SDK-Frameworks gelöscht werden.

app.OnMessage(async context =>
{
    var conversationId = context.Activity.Conversation.Id;

    foreach (var activityId in _list)
    {
        await context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId);
    }
});

app.on('message', async ({ activity, api }) => {
    const conversationId = activity.conversation.id;

    for (const activityId of activityIds) {
        await api.conversations.activities(conversationId).delete(activityId);
    }
});

@app.on_message
async def handle_delete(ctx: ActivityContext[MessageActivity]):
    conversation_id = ctx.activity.conversation.id

    for activity_id in _list:
        await ctx.api.conversations.activities(conversation_id).delete(activity_id)

Um eine vorhandene Aktivität innerhalb einer Unterhaltung zu löschen, schließen Sie conversationId und activityId in den Anforderungsendpunkt ein.

DELETE /v3/conversations/{conversationId}/activities/{activityId}

Antworten in Anführungszeichen

Antworten in Anführungszeichen ermöglichen es Ihrem Agent, auf eine vorherige Nachricht in der Unterhaltung zu verweisen. Wenn ein Benutzer eine Nachricht sendet, die eine andere Nachricht angibt, erhält Ihr Agent strukturierte Metadaten zu den Inhalten in Anführungszeichen. Ihr Agent kann auch Nachrichten senden, die frühere Nachrichten zitieren.

Empfangen von Antworten in Anführungszeichen

app.OnMessage(async context =>
{
    var quotes = context.Activity.GetQuotedMessages();

    if (quotes.Count > 0)
    {
        var quote = quotes[0].QuotedReply;
        await context.Reply(
            $"You quoted message {quote.MessageId} from {quote.SenderName}: \"{quote.Preview}\"");
    }
});

app.on('message', async ({ activity, reply }) => {
  const quotes = activity.getQuotedMessages();

  if (quotes.length > 0) {
    const quote = quotes[0].quotedReply;
    await reply(
      `You quoted message ${quote.messageId} from ${quote.senderName}: "${quote.preview}"`
    );
  }
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    quotes = ctx.activity.get_quoted_messages()

    if quotes:
        quote = quotes[0].quoted_reply
        await ctx.reply(
            f"You quoted message {quote.message_id} from {quote.sender_name}: \"{quote.preview}\""
        )

Antworten in Anführungszeichen senden

app.OnMessage(async context =>
{
    // Reply() automatically quotes the inbound message
    await context.Reply("Got it!");
});

app.OnMessage(async context =>
{
    // Quote a specific message by its ID
    var parentMessageId = "1772050244572";
    await context.Quote(parentMessageId, "Referencing an earlier message");
});

app.on('message', async ({ reply }) => {
  // reply() automatically quotes the inbound message
  await reply('Got it!');
});

app.on('message', async ({ quote }) => {
  // Quote a specific message by its ID
  const parentMessageId = '1772050244572';
  await quote(parentMessageId, 'Referencing an earlier message');
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # reply() automatically quotes the inbound message
    await ctx.reply("Got it!")

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Quote a specific message by its ID
    parent_message_id = "1772050244572"
    await ctx.quote(parent_message_id, "Referencing an earlier message")

Erstellen von Antworten in Anführungszeichen zum proaktiven Senden von Nachrichten

var parentMessageId = "1772050244572";
var firstMessageId = "1772050244573";
var secondMessageId = "1772050244574";

// Single quote with response below it
var msg = new MessageActivity()
    .AddQuote(parentMessageId, "Here is my response");
await app.Send(conversationId, msg);

// Multiple quotes with interleaved responses
msg = new MessageActivity()
    .AddQuote(firstMessageId, "response to first")
    .AddQuote(secondMessageId, "response to second");
await app.Send(conversationId, msg);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivity("see below for previous messages")
    .AddQuote(firstMessageId)
    .AddQuote(secondMessageId, "response to both");
await app.Send(conversationId, msg);

import { MessageActivity } from '@microsoft/teams.api';

const parentMessageId = '1772050244572';
const firstMessageId = '1772050244573';
const secondMessageId = '1772050244574';

// Single quote with response below it
let msg = new MessageActivity()
  .addQuote(parentMessageId, 'Here is my response');
await app.send(conversationId, msg);

// Multiple quotes with interleaved responses
msg = new MessageActivity()
  .addQuote(firstMessageId, 'response to first')
  .addQuote(secondMessageId, 'response to second');
await app.send(conversationId, msg);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivity('see below for previous messages')
  .addQuote(firstMessageId)
  .addQuote(secondMessageId, 'response to both');
await app.send(conversationId, msg);

from microsoft_teams.api.activities.message import MessageActivityInput

parent_message_id = "1772050244572"
first_message_id = "1772050244573"
second_message_id = "1772050244574"

# Single quote with response below it
msg = (MessageActivityInput()
    .add_quote(parent_message_id, "Here is my response"))
await app.send(conversation_id, msg)

# Multiple quotes with interleaved responses
msg = (MessageActivityInput()
    .add_quote(first_message_id, "response to first")
    .add_quote(second_message_id, "response to second"))
await app.send(conversation_id, msg)

# Grouped quotes — omit response to group quotes together
msg = (MessageActivityInput(text="see below for previous messages")
    .add_quote(first_message_id)
    .add_quote(second_message_id, "response to both"))
await app.send(conversation_id, msg)

Senden von Nachrichten in Teams-Kanaldaten

Das channelData Objekt enthält Teams-spezifische Informationen und ist eine definitive Quelle für Team- und Kanal-IDs. Optional können Sie diese IDs zwischenspeichern und als Schlüssel für den lokalen Speicher verwenden. Der App im SDK ruft wichtige Informationen aus dem channelData Objekt ab, um es zugänglich zu machen. Sie können jedoch immer über das -Objekt auf die turnContext ursprünglichen Daten zugreifen.

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:

• eventType: Der Teams-Ereignistyp wird nur in Fällen von Konversationsereignissen in Ihrem Teams-Bot übergeben.
• tenant.id: Microsoft Entra Mandanten-ID, die in allen Kontexten übergeben wird.
• team: Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.
  • id: GUID für den Kanal.
  • name: Name des Teams wird nur in Fällen von Teambenennungsereignissen übergeben.
• 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 wird.
  • id: GUID für den Kanal.
  • name: Kanalname wird nur in Fällen von 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.

Der folgende Code zeigt ein 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"
    }
}

Teams-Kanaldaten

Das channelData Objekt enthält Teams-spezifische Informationen und ist eine definitive Quelle für Team- und Kanal-IDs. Optional können Sie diese IDs zwischenspeichern und als Schlüssel für den lokalen Speicher verwenden. Der App im SDK ruft wichtige Informationen aus dem channelData Objekt ab, um es zugänglich zu machen. Sie können jedoch immer über das -Objekt auf die turnContext ursprünglichen Daten zugreifen.

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:

• eventType: Teams-Ereignistyp wird nur in Fällen von Kanaländerungsereignissen übergeben.
• tenant.id: Microsoft Entra Mandanten-ID, die in allen Kontexten übergeben wird.
• team: Wird nur in Kanalkontexten übergeben, nicht im persönlichen Chat.
  • id: GUID für den Kanal.
  • name: Name des Teams, das nur in Fällen von übergeben wird (how-to/conversations/subscribe-to-conversation-events.md#team-renamed).
• 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 wird.
  • id: GUID für den Kanal.
  • name: Kanalname wird nur in Fällen von 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

Der folgende Code zeigt ein 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"
    }
}

Statuscodes von Bot-Konversations-APIs

Stellen Sie sicher, dass Sie diese Fehler in Ihrer Teams-App entsprechend behandeln. In der folgenden Tabelle sind die Fehlercodes und die Beschreibungen aufgeführt, unter denen die Fehler generiert werden:

Anleitung zur Wiederholung von Statuscodes

Die allgemeine Wiederholungsanleitung für jeden status Code ist in der folgenden Tabelle aufgeführt. Bot muss vermeiden, dass status Codes wiederholt werden, die nicht angegeben sind:

Anfordern von Kopfzeilen des Bots

Die aktuellen ausgehenden Anforderungen an den Bot enthalten im Header oder der URL keine Informationen, die Bots dabei helfen, den Datenverkehr weiterzuleiten, ohne die gesamte Nutzlast zu entpacken. Die Aktivitäten werden über eine URL ähnlich wie https://< your_domain>/api/messages an den Bot gesendet. Anforderungen werden empfangen, um die Unterhaltungs-ID und Mandanten-ID in den Headern anzuzeigen.

Anforderungsheaderfelder

Zwei nicht standardmäßige Anforderungsheaderfelder werden allen Anforderungen hinzugefügt, die an Bots gesendet werden, sowohl für asynchronen Fluss als auch für synchronen Fluss. Die folgende Tabelle enthält die Anforderungsheaderfelder und deren Werte:

Wenn die Mandanten- oder Konversations-ID nicht in der Aktivität vorhanden ist oder dienstseitig nicht überprüft wurde, ist der Wert leer.

Nur erwähnte Nachrichten empfangen

Damit Ihre Bots nur die Kanal- oder Chatnachrichten abrufen können, in denen sich Ihr Bot befindet @mentioned, müssen Sie die Nachrichten filtern. Verwenden Sie den folgenden Codeausschnitt, damit Ihr Bot nur die Nachrichten empfangen kann, in denen er sich befindet @mentioned:

  app.OnMessage(async context =>
{
    if (!context.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(context.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
    {
        return;
    }

    await context.Send("Using RSC the bot can receive messages across channels or chats in team without being @mentioned.");
});

Wenn Ihr Bot alle Nachrichten empfangen soll, müssen Sie die @mention Nachrichten nicht filtern.

Nächster Schritt

Kanal- und Gruppenchatunterhaltungen mit einem Bot

Siehe auch

Unterhaltungsereignisse in Ihrem Teams-Bot