Dynamisches Führen von Benutzern mit vorgeschlagenen Aktionen

Um einer Nachricht vorgeschlagene Aktionen hinzuzufügen, geben Sie eine Liste von Karte Aktionsobjekten an, die die Schaltflächen darstellen, die dem Benutzer für die suggestedActions -Eigenschaft des Aktivitätsobjekts angezeigt werden sollen.

Es folgt ein Beispiel zum Implementieren vorgeschlagener Aktionen mit imBack:

{
  "type": "message",
  "from": {
    "id": "12345678",
    "name": "sender's name"
  },
  "conversation": {
    "id": "abcd1234",
    "name": "conversation's name"
  },
  "recipient": {
    "id": "1234abcd",
    "name": "recipient's name"
  },
  "text": "What are the tasks for the day.",
  "inputHint": "expectingInput",
  "suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Create a new query identifying overdue tasks",
        "value": "Create a new query identifying overdue tasks"
      },
      {
        "type": "imBack",
        "title": "Create a new work item for this feature",
        "value": "Create a new work item for this feature"
      }
    ]
  },
  "replyToId": "5d5cdc723"
}

Sie können verwenden Action.Compose , um eine Nachricht in das Feld zum Verfassen einzufügen, wodurch Sie einen neuen Aktionstyp hinzufügen können. Mit dieser Aktion können Sie semantische Objekte wie Tags, Erwähnung Benutzer im Chat oder Kanal und andere umfangreiche Objekte wie Emojis und GIFs einschließen.

Der folgende Codeausschnitt zeigt ein Beispiel für die Implementierung Action.Composevon :

{ 
  Type: “Action.Compose”, 
  Title: “button title”, 
  Value: { 
      type: “Teams.chatMessage”, 
      data: <GraphAPI Chat Message Object> 
  } 
}

Das Wertobjekt muss dem chatMessage -Objekt im Graph-API folgen.

Weitere Informationen finden Sie im Codebeispiel.

Verwenden Sie diese Option Action.Submit für vorgeschlagene Aktionsschaltflächen, die serverseitige Agent- oder Botlogik ausführen, ohne eine vom Benutzer sichtbare Nachricht zu veröffentlichen. Wenn ein Benutzer die Schaltfläche auswählt, sendet Teams eine Aufrufaktivität anstelle einer normalen Nachrichtenaktivität. Fügen Sie eine strukturierte Nutzlast in ein value , damit Ihre App die Aktion konsistent über vorhandene Aufrufhandler weiterleiten und verarbeiten kann.

Verwenden Sie Action.Submit , um vorgeschlagene Aktionsschaltflächen zu Agentantworten auf Schrägstrichbefehle hinzuzufügen, damit Benutzer einen nächsten Schritt auswählen können, ohne die Unterhaltung zu unterbrechen.

Dieses Muster ist besonders nützlich für den Workflow für Zielnachrichten, bei dem ein Agent fragt, ob eine Zielnachricht als öffentlich erneut gesendet werden soll. Weitere Informationen finden Sie unter Gezielte Nachrichten in Teams.

Botnutzlast (ausgehend vom Bot):

{
  "suggestedActions": {
    "actions": [{
      "type": "Action.Submit",
      "title": "Approve",
      "value": {
        "vote": "approve"
      }
    }]
  }
}

Bothandler (eingehender Bot):

Der Agent oder Bot empfängt eine Standardmäßige Botaufrufaktivität:

case "suggestedAction/submit":
  const vote = context.activity.value;  // { vote: "approve" }
  // Process the action...
  return { status: 200 };

Der Agent oder Bot kann die strukturierte Nutzlast in senden activity.name und aus activity.valuelesen. Dies entspricht der Behandlung anderer benannter Aufrufe durch Agents und Bots, z adaptiveCard/action . B. und handoff/action.

Implementierung des Teams SDK

Verwenden Sie den Seiten pivot, um Teams SDK-Codeausschnitte zum Erstellen und Behandeln Action.Submit vorgeschlagener Aktionen anzuzeigen.

#pragma warning disable ExperimentalTeamsSuggestedAction
using System.Text.Json;
using Microsoft.Teams.Api;
using Microsoft.Teams.Api.Activities;
using CardAction = Microsoft.Teams.Api.Cards.Action;
using CardActionType = Microsoft.Teams.Api.Cards.ActionType;

var reply = new MessageActivity("Approve or reject the request:")
{
    SuggestedActions = new SuggestedActions
    {
        Actions =
        {
            new CardAction(CardActionType.Submit) { Title = "Approve", Value = new { vote = "approve" } },
            new CardAction(CardActionType.Submit) { Title = "Reject", Value = new { vote = "reject" } }
        }
    }
};

await context.Send(reply);

teams.OnSuggestedActionSubmit(async (ctx, cancellationToken) =>
{
    var payload = ctx.Activity.Value is JsonElement value
        ? value.GetRawText()
        : "<none>";
    await ctx.Send($"Got vote: {payload}", cancellationToken);
});

import { MessageActivity, type SuggestedActions } from "@microsoft/teams.api";

const reply = new MessageActivity("Approve or reject the request:");
reply.suggestedActions = {
  to: [],
  actions: [
    { type: "Action.Submit", title: "Approve", value: { vote: "approve" } },
    { type: "Action.Submit", title: "Reject", value: { vote: "reject" } }
  ]
} satisfies SuggestedActions;

await send(reply);

app.on("suggested-action.submit", async ({ send, activity }) => {
  const payload = activity.value != null ? JSON.stringify(activity.value) : "<none>";
  await send(`Got vote: ${payload}`);
});

import json
from microsoft_teams.api import MessageActivityInput
from microsoft_teams.api.models.card.card_action import CardAction
from microsoft_teams.api.models.card.card_action_type import CardActionType
from microsoft_teams.api.models.suggested_actions import SuggestedActions

reply = MessageActivityInput(text="Approve or reject the request:").with_suggested_actions(
    SuggestedActions(
        to=[],
        actions=[
            CardAction(type=CardActionType.SUBMIT, title="Approve", value={"vote": "approve"}),
            CardAction(type=CardActionType.SUBMIT, title="Reject", value={"vote": "reject"}),
        ],
    )
)

await ctx.send(reply)

@app.on_suggested_action_submit
async def handle_suggested_action_submit(ctx):
    payload = json.dumps(ctx.activity.value)
    await ctx.send(f"Got vote: {payload}")