Senden und Empfangen von Nachrichten

Dialog-Agenten kommunizieren mit Benutzern über Messaging und ermöglichen so nahtlose Interaktionen. Es kann reale Unterhaltungen mit Benutzern durch Text- oder Sprachinteraktionen simulieren. Sie müssen sicherstellen, dass Agent-Unterhaltungen interaktiv, dynamisch, anpassungsfähig und benutzerfreundlich sind.

Nachrichteninhalt

Die Interaktion von Nachrichten zwischen Ihrem Agent und dem Benutzer kann verschiedene Arten von Nachrichteninhalten umfassen, die:

Verwenden von Rich-Text-Nachrichten und Emojis

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

Bildnachrichten verwenden

Um Agent-Nachrichten hervorzuheben, kann der Benutzer Bilder als Anhänge hinzufügen:

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

• Sie können die Höhe und Breite jedes Bildes mit XML angeben. In Markdown ist die Bildgröße standardmäßig 256×256 festgelegt. 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 von adaptiven Karten

Ein Gesprächsagent kann adaptive Karten enthalten, die Geschäftsabläufe vereinfachen. Adaptive Karten bieten umfangreiche, anpassbare Texte, Sprachausgaben, Bilder, Schaltflächen und Eingabefelder. Sie können adaptive Karten in einem Agent erstellen und in mehreren Apps wie Teams, Ihrer Website usw. angezeigt werden.

Weitere Informationen finden Sie unter:

• Adaptive Karten.
• Teams-Karten-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 Kernfunktionalität eines Agents.

In einem Chat ist jede Nachricht ein Activity Objekt vom Typ messageType: message. Wenn jemand eine Nachricht sendet, sendet Microsoft Teams sie an Ihren Agent. Teams sendet ein JSON-Objekt an den Messaging-Endpunkt Ihres Agents und lässt nur einen Endpunkt für das Messaging zu. Ihr Agent überprüft dann die Nachricht, um ihren Typ herauszufinden, 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 Agent, mit Teams und anderen Kanälen zu kommunizieren. Das Bot Builder SDK bietet die folgenden Features:

• Einfacher Zugriff auf den Teams SDK Framework-Konnektor.
• Tools zum Verwalten des Unterhaltungsflusses und -status.
• Einfache Möglichkeiten zum Hinzufügen kognitiver Dienste, wie z. B. die Verarbeitung natürlicher Sprache (NLP).

Ihr Agent erhält Nachrichten von Teams über die Text Eigenschaft und kann einzelne oder mehrere Antworten an Benutzer senden.

Weitere Informationen finden Sie unter Benutzerzuordnung für Agent-Nachrichten.

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

Nachrichtenaktivität empfangen

Verwenden Sie zum Empfangen einer Textnachricht die Text Eigenschaft eines Activity Objekts. Verwenden Sie im Aktivitätshandler des Agenten die Turn-Kontextobjekte Activity , 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 TestAgent"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestAgent.Sending bold-italic rich text",
    "attachments": [
      {
            "contentType": "text/html",
            "content": "<div><div>Hello Teams TestAgent. 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"
}

Erhalten einer Lesebestätigung

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

• Sie können Ihren Agent so konfigurieren, dass eine Folgenachricht gesendet wird, wenn der Benutzer der App die Nachricht im persönlichen Chat nicht gelesen hat.

• Sie können mithilfe von Lesebestätigungen eine Feedbackschleife erstellen, um die Erfahrung mit Ihren Telefonberatern zu optimieren.

Um Lesebestätigungsereignisse für Ihren Agent zu erhalten, stellen Sie Folgendes sicher:

• 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 die Graph-API hinzufügen. Weitere Informationen finden Sie unter consentedPermissionSet.

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

  Diese context.Activity.Value.LastReadMessageIdMethode ist hilfreich, um zu ermitteln, ob die Nachricht von den Empfängern gelesen wird. Wenn das compareMessageId kleiner als oder gleich dem LastReadMessageIdist, dann wurde die Nachricht gelesen. Außerkraftsetzung der Methode zum Empfangen von OnReadReceipt 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 agent's message");
  });
  

Das folgende Beispiel zeigt eine Ereignisanforderung mit Lesebestätigungen, die ein Agent 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 Agent"
        },
        "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 Agent die Lesebestätigungsereignisse empfängt. Der Administrator oder der Benutzer muss die Lesebestätigungseinstellung aktivieren oder deaktivieren.

Nachdem der Agent in einem Benutzer-zu-Agent-Chatszenario aktiviert wurde, erhält der Agent sofort ein Lesebestätigungsereignis, wenn der Benutzer die Nachricht des Agenten liest. Sie können das Benutzerengagement nachverfolgen, indem Sie die Anzahl der Ereignisse zählen, und Sie können auch eine kontextbezogene Nachricht senden.

Empfangen der Aktivität zum Bearbeiten von Nachrichten

Wenn Sie eine Nachricht bearbeiten, erhält der Agent eine Benachrichtigung über die Aktivität zum Bearbeiten von Nachrichten.

Um eine Aktivitätsbenachrichtigung zum Bearbeiten von Nachrichten in einem Agent zu erhalten, können Sie den Handler außer Kraft setzen OnMessageEdit .

Es folgt ein Beispiel für eine Benachrichtigung über die Aktivität "Nachricht bearbeiten", die verwendet OnMessageEdit wird, wenn eine gesendete Nachricht bearbeitet wird:

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":"TestAgent"
},
"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 agent}/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 Agenten die Methode des Turn-Kontextobjekts context.Send(...) , um eine einzelne Nachrichtenantwort zu senden. Verwenden Sie die Methode des Objekts multiple context.Send(...) calls , 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 TestAgent"
    },
    "conversation": {
        "id": "a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
   },
   "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My agent's reply",
    "replyToId": "1632474074231"
}

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

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

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

Aktivität zum Wiederherstellen von Nachrichten empfangen

Wenn Sie die Wiederherstellung einer Nachricht rückgängig machen, erhält der Agent eine Benachrichtigung über die Aktivität zum Wiederherstellen der Nachricht.

Um eine Benachrichtigung über die Aktivität zum Wiederherstellen einer Nachricht in einem Agent zu erhalten, können Sie den Handler außer Kraft setzen OnMessageUndelete .

Es folgt ein Beispiel für eine Aktivitätsbenachrichtigung zum Wiederherstellen einer Nachricht, die verwendet wird 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 agent}/v3/conversations/{conversationId}/activities/{activityId}

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

Vorläufiges Löschen von Nachrichtenaktivität empfangen

Wenn Sie eine Nachricht vorläufig löschen, erhält der Agent eine Benachrichtigung über die Aktivität der vorläufigen Löschnachricht.

Um eine Benachrichtigung über die Aktivität einer Nachricht für vorläufiges Löschen in einem Agent zu erhalten, können Sie den Handler außer Kraft setzen OnMessageSoftDelete .

Das folgende Beispiel zeigt eine Benachrichtigung über die Aktivität einer vorläufig gelöschten Nachricht, 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":"Testagent"
},
"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"
}  

Aktualisieren und Löschen von Nachrichten, die vom Agent gesendet wurden

Ihr Agent kann Nachrichten nach dem Senden dynamisch aktualisieren, anstatt sie als statische Momentaufnahmen von Daten zu haben. Nachrichten können auch mit der Methode des Teams SDK-Frameworks context.Api.Conversations.Activities.DeleteAsync(...) 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 die Karten aktualisiert haben, können Sie Nachrichten mithilfe des Teams SDK-Frameworks löschen.

Löschen von Nachrichten

Im Teams SDK-Framework hat jede Nachricht ihren eindeutigen Aktivitätsbezeichner. Nachrichten können mit der Methode des Teams SDK-Frameworks context.Api.Conversations.Activities.DeleteAsync(...) 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}

Zitierte Antworten

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

Antworten in Zitaten erhalten

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 Zitaten 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 Zitaten 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)

Nachrichten in Teams-Kanaldaten senden

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. Das App im SDK enthält wichtige Informationen aus dem channelData Objekt, um es zugänglich zu machen. Sie können jedoch jederzeit auf die Originaldaten des turnContext Objekts 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 Agent gesendet wird, enthält die folgenden Informationen:

• eventType: Der Teams-Ereignistyp wird nur bei Unterhaltungsereignissen in Ihrem Teams-Agent ü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 bei Umbenennungsereignissen des Teams übergeben wird.
• channel: Wird nur in Kanalkontexten übergeben, wenn der Agent erwähnt wird, oder für Ereignisse in Kanälen in Teams, in denen der Agent hinzugefügt wird.
  • id: GUID für den Kanal.
  • name: Kanalname, der nur bei Kanaländerungsereignissen übergeben wird.
• 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. Das App im SDK enthält wichtige Informationen aus dem channelData Objekt, um es zugänglich zu machen. Sie können jedoch jederzeit auf die Originaldaten des turnContext Objekts 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 Agent gesendet wird, enthält die folgenden Informationen:

• eventType: Der Teams-Ereignistyp wird nur bei 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 (how-to/conversations/subscribe-to-conversation-events.md#team-renamed) übergeben wurde.
• channel: Wird nur in Kanalkontexten übergeben, wenn der Agent erwähnt wird, oder für Ereignisse in Kanälen in Teams, in denen der Agent hinzugefügt wird.
  • id: GUID für den Kanal.
  • name: Kanalname, der nur bei Kanaländerungsereignissen übergeben wird.
• 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 Agent-Unterhaltungs-APIs

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

Statuscodes Anleitungen für Wiederholungsversuche

Die allgemeine Wiederholungsanleitung für jeden Statuscode ist in der folgenden Tabelle aufgeführt. Der Agent muss die Wiederholung von nicht angegebenen Statuscodes vermeiden:

Anforderungsheader des Agenten

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

Anforderungsheaderfelder

Allen an Agents gesendeten Anforderungen werden zwei nicht standardmäßige Anforderungsheaderfelder hinzugefügt, sowohl für den asynchronen Fluss als auch für den synchronen Fluss. Die folgende Tabelle enthält die Anforderungsheaderfelder und deren Werte:

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

Nur at-erwähnte Nachrichten empfangen

Damit Ihre Telefonberater nur die Kanal- oder Chatnachrichten erhalten, in denen sich Ihr Agent befindet @mentioned, müssen Sie die Nachrichten filtern. Verwenden Sie den folgenden Codeausschnitt, damit Ihr Agent nur die Nachrichten empfangen kann, in denen er @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 agent can receive messages across channels or chats in team without being @mentioned.");
});

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

Nächster Schritt

Kanal- und Gruppenchatunterhaltungen mit einem Agent

Siehe auch

Unterhaltungsereignisse in Ihrem Teams-Agent