Kanal- und Gruppenchatunterhaltungen für Agents

Damit Benutzer einen Agent in einem Team- oder Gruppenchat installieren können, fügen Sie den teams Bereich oder groupchat hinzu. Dadurch können alle Mitglieder der Unterhaltung mit Ihrem Agent interagieren. Nachdem der Agent installiert wurde, hat er Zugriff auf Metadaten zur Unterhaltung, z. B. die Liste der Konversationsmitglieder. Außerdem hat der Agent bei der Installation in einem Team Zugriff auf Details zu diesem Team und die vollständige Liste der Kanäle.

Standardmäßig empfangen Agents in Gruppenchats und -kanälen nachrichten nur, wenn sie direkt sind @mentioned. Sie erhalten keine weiteren Nachrichten, die an die Unterhaltung gesendet werden. Ihr Agent empfängt beispielsweise keine Nachricht, wenn das Team oder der Kanal erwähnt wird oder wenn jemand auf eine Nachricht von Ihrem Agent ohne @mentioning diese antwortet. Das Teams SDK bietet eine dedizierte mention Aktivitätsroute zum Verarbeiten von @mention Ereignissen.

Richtlinien für den Entwurf

Entwerfen Sie in Gruppenchats und Kanälen Ihren Agent für gemeinsame Unterhaltungen mit klarem Wert, präzisen Antworten und minimalem Rauschen.

Unterhaltungen im Thread

app.OnMessage(async (context, cancellationToken) =>
{
    // Send in the same thread, no quote
    await context.Send("Acknowledged", cancellationToken);

    // Send in the same thread with a visual quote of the inbound message
    await context.Reply("Got it!", cancellationToken);
});

app.on('message', async ({ send, reply }) => {
  // Send in the same thread, no quote
  await send('Acknowledged');

  // Send in the same thread with a visual quote of the inbound message
  await reply('Got it!');
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Send in the same thread, no quote
    await ctx.send("Acknowledged")

    # Send in the same thread with a visual quote of the inbound message
    await ctx.reply("Got it!")

Informationen zum proaktiven Senden von Nachrichten an einen Thread finden Sie unter Proaktive Nachrichten.

Senden einer Nachricht bei der Installation

Wenn Ihr Agent zum ersten Mal einer Gruppe oder einem Team hinzugefügt wird, können Sie mithilfe der install.add Lebenszyklusroute eine Einführungsnachricht senden. Weitere Informationen finden Sie unter Proaktives Messaging.

Wenn Sie eine Einführungsnachricht senden, geben Sie eine kurze Beschreibung der Features des Agents und deren Verwendung an.

Sie können die auch während der conversationId Installation speichern, um proaktives Messaging später zu aktivieren.

Der folgende Code zeigt ein Beispiel für das Senden von Begrüßungsnachrichten bei der Installation:

app.OnInstall(async context => 
{ 
    await context.Send("Hello! I'm your agent. Here's what I can do..."); 
}); 

app.on('install.add', async ({ send }) => 
{ 
    await send('Hello! I\'m your agent. Here\'s what I can do...'); 
}); 

@app.on_install_add 
async def handle_install_add(ctx: ActivityContext[InstalledActivity]): 
    await ctx.send("Hello! I'm your agent. Here's what I can do...") 

Senden Sie keine proaktiven Begrüßungsnachrichten an Benutzer einzeln, wenn der Agent in einem Team- oder Gruppenchat installiert ist. Wenn Sie eine Begrüßungsnachricht senden, posten Sie sie in der installierten Unterhaltung und Erwähnung der Person, die den Agent hinzugefügt hat.

Senden Sie in den folgenden Fällen keine Nachricht:

• Wenn das Team groß ist, z. B. größer als 100 Mitglieder. Ihr Agent kann als Spam angesehen werden, und die Person, die ihn hinzugefügt hat, kann Beschwerden erhalten. Sie müssen jedem, der die Willkommensnachricht sieht, das Wertversprechen Ihres Agenten klar kommunizieren.
• Ihr Agent wird zuerst in einer Gruppe oder einem Kanal erwähnt, anstatt zuerst einem Team hinzugefügt zu werden.
• Eine Gruppe oder ein Kanal wird umbenannt.
• Ein Teammitglied wird einer Gruppe oder einem Kanal hinzugefügt.

Arbeiten mit Erwähnungen

In Gruppenchats und -kanälen enthalten Nachrichten, die @mention Ihr Agent im Nachrichtentext eine Erwähnung Entität enthält. Wenn Ihr Agent so konfiguriert ist, dass er alle Nachrichten empfängt, z. B. mit RSC, enthalten @mentioneinige eingehende Nachrichten möglicherweise keine . Ihr Agent kann andere Benutzer abrufen, die in einer Nachricht erwähnt werden, und Nachrichten, die er sendet, Erwähnungen hinzufügen. Agents in Gruppenchats ermöglichen Benutzererwähnungen mithilfe von @mention. Sie unterstützen @everyone jedoch keine Erwähnungen.

Bei Nachrichten, die enthalten@mentions, enthält der Nachrichtentext Erwähnung Markup, z<at>@agentname</at>. B. .

Abrufen von Erwähnungen

Erwähnungen werden im -Objekt in der entities Aktivitätsnutzlast zurückgegeben und enthalten sowohl die eindeutige ID des Benutzers als auch den Namen des angegebenen Benutzers. Der Text der Nachricht enthält auch die Erwähnung, z<at>@John Smith<at>. B. . Verlassen Sie sich jedoch nicht auf den Text in der Nachricht, um Informationen über den Benutzer abzurufen. Es ist möglich, dass die Person, die die Nachricht sendet, sie ändert. Verwenden Sie daher das entities -Objekt.

Sie können alle Erwähnungen in der Nachricht abrufen, indem Sie das entities Array in der Aktivität nach Einträgen filtern, die type auf festgelegt sind mention.

Der folgende Code zeigt ein Beispiel für das Abrufen von Erwähnungen:

app.OnMessage(async context =>
{
    var mentions = context.Activity.Entities?
        .Where(e => e.Type == "mention")
        .ToList();

    if (mentions != null && mentions.Any())
    {
        var firstMention = mentions[0].Properties["mentioned"]?["name"]?.ToString();
        await context.Send($"Hello {firstMention}");
    }
    else
    {
        await context.Send("Aw, no one was mentioned.");
    }
});

app.on('message', async ({ activity, send }) => {
    const mentions = activity.entities?.filter(e => e.type === 'mention');

    if (mentions && mentions.length > 0) {
        const firstMention = mentions[0].mentioned;
        await send(`Hello ${firstMention.name}.`);
    } else {
        await send('Aw, no one was mentioned.');
    }
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    mentions = [e for e in (ctx.activity.entities or []) if e.type == "mention"]

    if mentions:
        first_mention = mentions[0].mentioned
        await ctx.send(f"Hello {first_mention.name}")
    else:
        await ctx.send("Aw, no one was mentioned.")

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Überprüfen auf und Streifen @mention

In Kanälen und Gruppenchats adressiert der Benutzer einen Agent oder eine App in der Regel mit einem @mention. Bevor Sie die Nachricht interpretieren, überprüfen Sie, ob der Erwähnung auf Ihren Agent oder Ihre App abzielt, entfernen Sie dann den Erwähnung Text, und kürzen Sie Leerzeichen. Dadurch bleibt nur der Befehl oder die Eingabeaufforderung des Benutzers für die Verarbeitung übrig.

Das Entfernen der Erwähnung verhindert, dass der Agent- oder App-Name den Befehlsabgleich, die Absichtserkennung, die Suche oder die Verarbeitung natürlicher Sprache beeinträchtigt. Außerdem kann derselbe Handler Nachrichten konsistent in persönlichen Chats, Gruppenchats und Kanälen verarbeiten. Behalten Sie andere Erwähnungen bei, wenn sie Teil der Anforderung des Benutzers sind.

string StripMentions(MessageActivity msg)
{
    var text = msg.Text ?? "";
    if (msg.Entities == null) return text;

    foreach (var entity in msg.Entities)
    {
        if (entity is MentionEntity mention && mention.Text != null)
        {
            text = text.Replace(mention.Text, "");
        }
    }

    return text.Trim();
}

app.on('message', async ({ activity, send }) => {
  const clean = activity.stripMentionsText().text;
  await send(`You said: ${clean}`);
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    clean = ctx.activity.strip_mentions_text().text
    await ctx.send(f"You said: {clean}")

Hinzufügen von Erwähnungen zu Ihren Nachrichten

Ihr Agent kann andere Benutzer in Nachrichten Erwähnung, die in Kanälen gepostet werden. Um eine Erwähnung inline in Ihre Nachricht einzuschließen, platzieren Sie die Erwähnung im Nachrichtentext, und fügen Sie die Erwähnung Details zum Entitätsarray hinzu. Das text Feld in der Erwähnung Entität muss mit dem genauen Text im Nachrichtentext übereinstimmen.

Der folgende Code zeigt ein Beispiel für das Hinzufügen von Erwähnungen zu Ihren Nachrichten:

app.OnMessage(async context =>
{
    var user = context.Activity.From;
    var message = new MessageActivity($"Hello <at>{user.Name}</at>!").AddMention(user);
    await context.Send(message);
});

app.on('message', async ({ send, activity }) => {
    const user = activity.from;
    const message = new MessageActivity(`Hello <at>${user.name}</at>!`).addMention(user);
    await send(message);
});

@app.on_message 
async def handle_message(ctx: ActivityContext[MessageActivity]): 
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=ctx.activity.from_))

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Sie können Benutzer auch anhand ihrer Microsoft Entra Objekt-ID oder des Benutzerprinzipalnamens (User Principal Name, UPN) und Erwähnung Tags in Kanalnachrichten Erwähnung.

Unterstützung für Microsoft Entra Objekt-ID und UPN in Benutzer-Erwähnung

Bots können Benutzer über Microsoft Entra Objekt-ID oder Benutzerprinzipalnamen (User Principal Name, UPN) zusätzlich zu Benutzer-IDs Erwähnung. Eingehende Webhooks unterstützen auch Benutzererwähnungen in adaptiven Karten, die diese ID-Typen verwenden.

Der folgende Codeausschnitt zeigt ein Beispiel für die Erwähnung von Benutzern mit Entra Objekt-ID und UPN mithilfe des Teams SDK:

app.OnMessage(async context =>
{
    // Mention a user by their User Principal Name (UPN)
    var user = new Account { Id = "Adele@microsoft.com", Name = "Adele" };
    await context.Send(new MessageActivity("Hello!").AddMention(user));
});

app.on('message', async ({ send }) => {
    // Mention a user by their User Principal Name (UPN)
    const user = { id: 'Adele@microsoft.com', name: 'Adele' };
    await send(new MessageActivity('Hello!').addMention(user));
});

from microsoft_teams.api import Account, MessageActivityInput

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a user by their User Principal Name (UPN)
    user = Account(id="Adele@microsoft.com", name="Adele")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=user))

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com",
            "name": "Adele"
    }
}

Tag-Erwähnung

Ihr Agent kann Tags in SMS-Nachrichten und adaptive Karten in Kanälen Erwähnung. Wenn der Agent @mentions das Tag in einem Kanal verwendet, wird das Tag hervorgehoben, und die personen, die dem Tag zugeordnet sind, werden benachrichtigt. Wenn ein Benutzer mit der Maus auf das Tag zeigt, wird ein Popupfenster mit den Tagdetails angezeigt.

Erwähnen von Tags in einer SMS

Um ein Tag zu Erwähnung, fügen Sie eine Erwähnung Entität mit "type": "tag" in Ihre Nachricht ein. Das id Feld muss die base64-codierte Tag-ID aus der List teamworkTags-API sein.

app.OnMessage(async context =>
{
    // Mention a tag using the tag's Graph API ID
    var tag = new Account { Id = "<base64-encoded-tag-id>", Name = "Test Tag" };
    await context.Send(new MessageActivity("Hello!").AddMention(tag));
});

app.on('message', async ({ send }) => {
    // Mention a tag using the tag's Graph API ID
    const tag = { id: '<base64-encoded-tag-id>', name: 'Test Tag' };
    await send(new MessageActivity('Hello!').addMention(tag));
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a tag using the tag's Graph API ID
    tag = Account(id="<base64-encoded-tag-id>", name="Test Tag")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=tag))

Erwähnen von Tags in einer adaptiven Karte

Fügen Sie im Schema der adaptiven Karte unter dem mentioned -Objekt die "type": "tag" -Eigenschaft hinzu. Wenn die "type": "tag" Eigenschaft nicht hinzugefügt wird, behandelt der Agent die Erwähnung als Benutzer Erwähnung.

Sie können die Liste der im Kanal verfügbaren Tags mithilfe der LIST TEAMWORKTags-API abrufen.

Beispiel:

{
    "type": "mention",
    "text": "<at>Test Tag</at>",
    "mentioned": {
            "id": "base64 encoded id",
            "name": "Test Tag",
            "type": "tag"
    }
}

Abfrageparameter

Fehlercode

Einschränkungsgrenzwerte

Jede Anforderung kann anhand mehrerer Grenzwerte ausgewertet werden, abhängig vom Bereich, dem Fenstertyp (kurz und lang), der Anzahl der Tags pro Nachricht und anderen Faktoren. Die erste zu erreichende Einschränkung löst ein Einschränkungsverhalten aus.

Stellen Sie sicher, dass Sie die Drosselungsgrenzwerte nicht überschreiten, um eine fehlerhafte Nachrichtenübermittlung zu vermeiden. Beispielsweise kann ein Agent nur zwei Nachrichten mit Tag-Erwähnung in einem Fünf-Sekunden-Fenster senden, und jede Nachricht kann nur bis zu 10 Tags enthalten.

In der folgenden Tabelle sind die Drosselungsgrenzwerte für Tagerwähnungen in einem Agent aufgeführt:

Begrenzungen

• Tagerwähnungen werden nur im Agent-zu-Client-Nachrichtenfluss mit Text und adaptiver Karte unterstützt.
• Tagerwähnungen werden in freigegebenen und privaten Kanälen nicht unterstützt.
• Tagerwähnungen werden in Connectors nicht unterstützt.
• Tagerwähnungen unterstützen den Aufrufflow in einem Agent nicht.

Nächster Schritt

Siehe auch

• Teams SDK – API-Client
• Teams SDK – Microsoft Graph-Integration
• Senden und Empfangen von Gezieltnachrichten in Gruppenunterhaltungen
• Verfügbarmachen von Schrägstrichbefehlen aus Agents und Apps
• Erstellen eines privaten Kanals im Namen des Benutzers
• Teams SDK – Übersicht über die Teams-Integration