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. 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 Senden von Nachrichten und Anlagen.

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.

Beschränkungen der Nachrichtengröße

Die Größe der Agent-Nachricht wurde auf 100 KB beschränkt. Dies ist ein ungefährer Grenzwert, da er die Nachricht selbst (Text, Bildlinks usw.), @Erwähnungen und als UTF-16 codierte Reaktionen umfasst. Die Größenbeschränkung von 100 KB umfasst keine Base64-codierten Bilder. Stellen Sie während der Implementierung sicher, dass die Größe der Nachricht selbst 80 KB überschreitet, um eine erfolgreiche Nachrichtenübermittlung zu gewährleisten.

Wenn die Meldung des Agenten die Größenbeschränkung überschreitet, erhält der Agent einen 413 Status (RequestEntityTooLarge), der den Fehlercode MessageSizeTooBigenthält.

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 das Teams SDK verwaltet, das das Aktivitätsprotokoll zwischen Ihrem Agent und Teams verarbeitet. Das Teams-SDK bietet die folgenden Features:

• Typisierte Aktivitätshandler für eingehende Nachrichten und Ereignisse.
• Tools zum Verwalten des Unterhaltungsflusses und -status.
• Ein Teams-API-Client zum Senden, Aktualisieren und Löschen von Aktivitäten.

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 Eigenschaft des Aktivitätskontextobjekts Activity , um eine einzelne Nachrichtenanforderung zu lesen.

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

teams.OnMessage(async (context, cancellationToken) =>
{
    await context.SendAsync($"Echo: {context.Activity.Text}", cancellationToken);
});

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-8097-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:

teams.OnReadReceipt(async (context, cancellationToken) =>
{
    var lastReadMessageId = context.Activity.Value.LastReadMessageId;
    await context.SendAsync("User read the agent's message", cancellationToken);
});

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, registrieren Sie den OnMessageUpdate Handler.

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

teams.OnMessageUpdate(async (context, cancellationToken) =>
{
    var eventType = context.Activity.ChannelData?.EventType;
    if (eventType == "editMessage")
        await context.SendAsync("message is updated", cancellationToken);
    else if (eventType == "undeleteMessage")
        await context.SendAsync("message is undeleted", cancellationToken);
});

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://smba.trafficmanager.net/amer/",
"from": {
    "id":"29:1BLjP9j3_PM4mubmQZsYPx7jDyLeLf_YVA9sVPV08KMAFMjJWB_EUGveb9EVDh9TslNp9qjnzEBy3kgw01Jf1Kg",
    "name":"Mike Wilber",
    "aadObjectId":"520e4d1e-2108-43ee-a092-46a9507c6200"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1pweuGJ44RkB90tiJNQ_I6g3vyuP4CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqRPB"
},
"recipient":{
    "id":"28:0d569679-ab4c-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.SendAsync(...) , um eine einzelne Nachrichtenantwort zu senden. Verwenden Sie die Methode des Objekts multiple context.SendAsync(...) 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:

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

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 Teams 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.

Wiederherstellungsaktivitäten kommen über den OnMessageUpdate Handler in Teams SDK 2.1.0 an.

Es folgt ein Beispiel für eine Benachrichtigung über die Aktivität einer wiederhergestellten Nachricht, wenn eine gelöschte Nachricht wiederhergestellt wird:

teams.OnMessageUpdate(async (context, cancellationToken) =>
{
    if (context.Activity.ChannelData?.EventType == "undeleteMessage")
    {
        await context.SendAsync("message is undeleted", cancellationToken);
    }
});

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://smba.trafficmanager.net/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.

Vorläufige Löschaktivitäten kommen über den OnMessageDelete Handler in Teams SDK 2.1.0 an.

Das folgende Beispiel zeigt eine Benachrichtigung über die Aktivität einer Nachricht für vorläufiges Löschen, wenn eine Nachricht vorläufig gelöscht wird:

teams.OnMessageDelete(async (context, cancellationToken) =>
{
    var eventType = context.Activity.ChannelData?.EventType;
    if (eventType == "softDeleteMessage")
        await context.SendAsync("message is soft deleted", cancellationToken);
});

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://smba.trafficmanager.net/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 Teams SDK-Methode 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.

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

    var updatedActivity = new MessageActivityInput().WithText("The new text for the activity");

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

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.

teams.OnMessage(async (context, cancellationToken) =>
{
    var conversationId = context.Activity.Conversation.Id;
    var activityId = context.Activity.ReplyToId;

    TeamsAttachment attachment = TeamsAttachment.CreateBuilder()
        .WithAdaptiveCard(JsonSerializer.SerializeToElement(card))
        .Build();
    var updatedActivity = new MessageActivityInput().AddAttachment(attachment);

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

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 löschen.

Löschen von Nachrichten

Im Teams SDK hat jede Nachricht ihren eindeutigen Aktivitätsbezeichner. Nachrichten können mit der context.Api.Conversations.Activities.DeleteAsync(...) Methode gelöscht werden.

teams.OnMessage(async (context, cancellationToken) =>
{
    var conversationId = context.Activity.Conversation.Id;

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

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

teams.OnMessage(async (context, cancellationToken) =>
{
    var quotes = context.Activity.GetQuotedMessages();

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

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

teams.OnMessage(async (context, cancellationToken) =>
{
    // ReplyAsync() automatically quotes the inbound message
    await context.ReplyAsync("Got it!", cancellationToken);
});

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

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

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 MessageActivityInput()
    .WithText("Here is my response")
    .AddQuote(parentMessageId);
await teams.SendAsync(conversationId, msg, cancellationToken: cancellationToken);

// Multiple quotes with interleaved responses
msg = new MessageActivityInput()
    .WithText("response to first")
    .AddQuote(firstMessageId)
    .AddQuote(secondMessageId, "response to second");
await teams.SendAsync(conversationId, msg, cancellationToken: cancellationToken);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivityInput()
    .WithText("see below for previous messages")
    .AddQuote(firstMessageId)
    .AddQuote(secondMessageId, "response to both");
await teams.SendAsync(conversationId, msg, cancellationToken: cancellationToken);

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)

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 über das Aktivitätskontextobjekt auf die Originaldaten 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 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.
• app: Verfügbar in Einzelunterhaltungen (persönliche App). Enthält die App-ID und die installierte Manifestversion der App, die mit der Aktivität verknüpft ist. In einigen Szenarien channelData.app werden sie möglicherweise nicht bereitgestellt, z. B. wenn der Agent nicht für den Benutzer installiert ist oder wenn mehrere Apps einer einzigen Bot-ID zugeordnet sind. Ihr Agent muss den Fall behandeln, in dem dieses Feld nicht vorhanden ist.
  • id: Die App-ID.
  • version: Die Manifestversion der installierten App.

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:

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

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

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