Utiliser des boîtes de dialogue avec des bots

Appeler des boîtes de dialogue (appelées modules de tâche dans TeamsJS v1.x) à partir de bots Microsoft Teams à l’aide TaskFetchAction de boutons sur les cartes adaptatives. Les boîtes de dialogue fournissent une interaction ciblée en ouvrant une fenêtre contextuelle pour l’utilisateur, ce qui les rend idéales pour les formulaires complexes ou les flux de travail à plusieurs étapes.

Il existe deux façons d’appeler des boîtes de dialogue :

• Un nouveau message task/fetchd’appel : Utilisation de l’action de la carte pour les Action.Execute cartes adaptatives avec task/fetch, une boîte de dialogue HTML ou basée sur une carte adaptative est récupérée dynamiquement à partir de votre bot.
• URL de lien profond : à l’aide de la syntaxe de lien profond pour les boîtes de dialogue, vous pouvez utiliser l’action de Action.OpenUrl la carte pour les cartes adaptatives. Avec les URL de liens profonds, l’URL de boîte de dialogue ou le corps de la carte adaptative est déjà connu pour éviter un aller-retour serveur relatif à task/fetch.

Importante

Chaque url et fallbackUrl doit implémenter le protocole de chiffrement HTTPS.

Remarque

Dans le client Teams v1, les boîtes de dialogue étaient appelées modules de tâche. Ils peuvent parfois être utilisés comme synonymes.

Créer un lanceur de dialogue

Pour appeler une boîte de dialogue à partir d’un bot, envoyez une carte adaptative avec TaskFetchAction des boutons. Chaque bouton inclut des données que votre bot utilise pour déterminer le contenu de boîte de dialogue à renvoyer.

Avertissement

Les services cloud de Microsoft, y compris les versions web de Teams, Outlook et des domaines Microsoft 365, migrent vers le *.cloud.microsoft domaine. Effectuez les étapes suivantes dès que possible pour vous assurer que votre application continue à s’afficher sur les hôtes clients web Microsoft 365 pris en charge :

1. Mettez à jour la bibliothèque TeamsJS vers la version v.2.19.0 ou ultérieure. Vous devez appeler microsoftTeams.app.initialize() pour éviter de voir un avertissement dans le nouveau domaine. Pour plus d’informations sur la dernière version de TeamsJS, consultez la bibliothèque cliente JavaScript de Microsoft Teams.

2. Si vous avez défini des en-têtes de stratégie de sécurité du contenu (CSP) pour votre application, mettez à jour la directive frame-ancestors pour inclure le *.cloud.microsoft domaine. Pour garantir une compatibilité descendante pendant la migration, conservez les valeurs existantes frame-ancestors dans vos en-têtes CSP. Cette approche garantit que votre application continue de fonctionner sur les applications hôtes Microsoft 365 existantes et futures et réduit la nécessité de modifications ultérieures.

Mettez à jour le domaine suivant dans la frame-ancestors directive des en-têtes CSP de votre application :

https://*.cloud.microsoft

Les étapes suivantes fournissent des instructions sur la façon d’appeler une boîte de dialogue (appelée module de tâche dans TeamsJS v1.x) en utilisant task/fetch:

1. Cette image montre une carte adaptative avec une action AcheterAction.Execute une carte. La valeur de la propriété type est task/fetch et le reste de l’objet data peut être de votre choix.

2. Le bot reçoit une card.action activité. Dans le SDK Teams, vous gérez cela à l’aide du OnAdaptiveCardAction gestionnaire. Pour plus d’informations, voir Exécution d’actions.

3. Le bot crée un ActionResponse objet et le renvoie. Pour plus d’informations sur le schéma des réponses, consultez la discussion sur la tâche/l’envoi. Le code suivant fournit un exemple de corps de réponse qui contient un objet TaskInfo incorporé dans un objet wrapper :

   {
     "task": {
       "type": "continue",
       "value": {
         "title": "Task module title",
         "height": 500,
         "width": "medium",
         "url": "https://contoso.com/msteams/taskmodules/newcustomer",
         "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer"
       }
     }
   }
   

   L’événement task/fetch et sa réponse pour les bots sont similaires à la microsoftTeams.tasks.startTask() fonction dans la bibliothèque cliente JavaScript de Microsoft Teams (TeamsJS).

4. Microsoft Teams affiche la boîte de dialogue.

La section suivante fournit des détails sur l’envoi du résultat d’une boîte de dialogue.

Soumettre le résultat d’une boîte de dialogue

Lorsque l’utilisateur a terminé la boîte de dialogue, le résultat est renvoyé à votre application. Le fonctionnement de la soumission dépend du type de contenu de la boîte de dialogue :

• Carte adaptative (TaskInfo.carte) : lorsque l’utilisateur sélectionne un Action.Submit bouton, Teams envoie un événement d’envoi de boîte de dialogue à votre application. Le handler d’envoi de votre boîte de dialogue reçoit les données du formulaire de la carte. En C#, utilisez l’attribut [TaskSubmit] . Dans TypeScript, utilisez .app.on('dialog.submit', ...) En Python, utilisez @app.on_dialog_submit.
• Page Web (TaskInfo.url) : la page Web appelle microsoftTeams.tasks.submitTask(formData) à partir de la bibliothèque cliente TeamsJS, ce qui déclenche le même événement d’envoi de boîte de dialogue dans votre application.

Gérer les événements d’envoi de dialogue

Lorsque l’utilisateur envoie une boîte de dialogue, le bot reçoit un task/submit message d’appel. Vous disposez de plusieurs options pour répondre :

Type de réponse	Scénario
Aucune réponse	La réponse la plus simple n’est pas du tout une réponse. Votre bot n’est pas obligé de répondre lorsque l’utilisateur a terminé la boîte de dialogue.
MessageTask	Teams affiche un message dans une zone de message contextuelle de la boîte de dialogue.
ContinueTask	Vous permet de chaîner des séquences de Cartes adaptatives dans un Assistant ou une expérience en plusieurs étapes.

Les onglets suivants montrent comment gérer les événements d’envoi de dialogue dans .NET, TypeScript et Python :

SDK C# v2.1

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.TaskModules;

teams.OnTaskSubmit(async (context, cancellationToken) =>
{
  var data = context.Activity.Value?.Data as JsonElement?;
    if (data == null)
    {
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("No data found in the activity value")
      .Build();
    }

    var submissionType = data.Value.TryGetProperty("submissiondialogtype", out var submissionTypeObj) && submissionTypeObj.ValueKind == JsonValueKind.String
        ? submissionTypeObj.ToString()
        : null;

    string? GetFormValue(string key)
    {
        if (data.Value.TryGetProperty(key, out var val))
        {
            if (val is JsonElement element)
                return element.GetString();
            return val.ToString();
        }
        return null;
    }

    switch (submissionType)
    {
        case "simple_form":
            var name = GetFormValue("name") ?? "Unknown";
            await context.SendAsync($"Hi {name}, thanks for submitting the form!", cancellationToken);
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Form was submitted")
              .Build();
        default:
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Unknown submission type")
              .Build();
    }
      });

SDK<C# 2.1(hérité)

using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Activities.Invokes;
using Microsoft.Teams.Apps.Annotations;
using Microsoft.Teams.Common.Logging;

[TaskSubmit]
public async Task<Microsoft.Teams.Api.TaskModules.Response> OnTaskSubmit([Context] Tasks.SubmitActivity activity, [Context] IContext.Client client, [Context] ILogger log)
{
    var data = activity.Value?.Data as JsonElement?;
    if (data == null)
    {
        log.Info("[TASK_SUBMIT] No data found in the activity value");
        return new Microsoft.Teams.Api.TaskModules.Response(
            new Microsoft.Teams.Api.TaskModules.MessageTask("No data found in the activity value"));
    }

    var submissionType = data.Value.TryGetProperty("submissiondialogtype", out var submissionTypeObj) && submissionTypeObj.ValueKind == JsonValueKind.String
        ? submissionTypeObj.ToString()
        : null;

    string? GetFormValue(string key)
    {
        if (data.Value.TryGetProperty(key, out var val))
        {
            if (val is JsonElement element)
                return element.GetString();
            return val.ToString();
        }
        return null;
    }

    switch (submissionType)
    {
        case "simple_form":
            var name = GetFormValue("name") ?? "Unknown";
            await client.Send($"Hi {name}, thanks for submitting the form!");
            return new Microsoft.Teams.Api.TaskModules.Response(
                new Microsoft.Teams.Api.TaskModules.MessageTask("Form was submitted"));
        default:
            return new Microsoft.Teams.Api.TaskModules.Response(
                new Microsoft.Teams.Api.TaskModules.MessageTask("Unknown submission type"));
    }
}

TypeScript

import { App } from '@microsoft/teams.apps';
// ...

app.on('dialog.submit', async ({ activity, send, next }) => {
  const dialogType = activity.value.data?.submissiondialogtype;

  if (dialogType === 'simple_form') {
    const name = activity.value.data.name;
    await send(`Hi ${name}, thanks for submitting the form!`);
    return {
      task: {
        type: 'message',
        value: 'Form was submitted',
      },
    };
  }

  if (dialogType === 'webpage_dialog') {
    const name = activity.value.data.name;
    const email = activity.value.data.email;
    await send(`Hi ${name}, thanks for submitting the form! We got that your email is ${email}`);
    return {
      status: 200,
    };
  }
});

Python

from typing import Optional, Any
from microsoft_teams.api import TaskSubmitInvokeActivity, InvokeResponse, TaskModuleResponse, TaskModuleMessageResponse
from microsoft_teams.apps import ActivityContext

@app.on_dialog_submit
async def handle_dialog_submit(ctx: ActivityContext[TaskSubmitInvokeActivity]):
    data: Optional[Any] = ctx.activity.value.data
    dialog_type = data.get("submissiondialogtype") if data else None

    if dialog_type == "webpage_dialog":
        name = data.get("name") if data else None
        email = data.get("email") if data else None
        await ctx.send(f"Hi {name}, thanks for submitting the form! We got that your email is {email}")
        return InvokeResponse(
            body=TaskModuleResponse(task=TaskModuleMessageResponse(value="Form submitted successfully"))
        )

Chaînage de boîtes de dialogue en plusieurs étapes

Vous pouvez chaîner les cartes adaptatives dans un Assistant à plusieurs étapes en renvoyant une ContinueTask réponse du gestionnaire d’envoi. Chaque étape renvoie une nouvelle carte, et la dernière étape renvoie une MessageTask pour fermer la boîte de dialogue.

SDK C# v2.1

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Apps.TaskModules;
using Microsoft.Teams.Cards;

// Add these cases to your OnTaskSubmit method
case "webpage_dialog_step_1":
    var nameStep1 = GetFormValue("name") ?? "Unknown";
    var nextStepCardJson = $$"""
    {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
                "type": "TextBlock",
                "text": "Email",
                "size": "Large",
                "weight": "Bolder"
            },
            {
                "type": "Input.Text",
                "id": "email",
                "label": "Email",
                "placeholder": "Enter your email",
                "isRequired": true
            }
        ],
        "actions": [
            {
                "type": "Action.Submit",
                "title": "Submit",
                "data": {"submissiondialogtype": "webpage_dialog_step_2", "name": "{{nameStep1}}"}
            }
        ]
    }
    """;

    var nextStepCard = JsonSerializer.Deserialize<AdaptiveCard>(nextStepCardJson)
        ?? throw new InvalidOperationException("Failed to deserialize next step card");

    TeamsAttachment nextStepAttachment = TeamsAttachment.CreateBuilder()
      .WithAdaptiveCard(JsonSerializer.SerializeToElement(nextStepCard))
      .Build();

    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Continue)
      .WithTitle($"Thanks {nameStep1} - Get Email")
      .WithCard(nextStepAttachment)
      .Build();

case "webpage_dialog_step_2":
    var nameStep2 = GetFormValue("name") ?? "Unknown";
    var emailStep2 = GetFormValue("email") ?? "No email";
    await context.SendAsync($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}", cancellationToken);
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("Multi-step form completed successfully")
      .Build();

SDK<C# 2.1(hérité)

using System.Text.Json;
using Microsoft.Teams.Api;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Cards;

// Add these cases to your OnTaskSubmit method
case "webpage_dialog_step_1":
    var nameStep1 = GetFormValue("name") ?? "Unknown";
    var nextStepCardJson = $$"""
    {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
                "type": "TextBlock",
                "text": "Email",
                "size": "Large",
                "weight": "Bolder"
            },
            {
                "type": "Input.Text",
                "id": "email",
                "label": "Email",
                "placeholder": "Enter your email",
                "isRequired": true
            }
        ],
        "actions": [
            {
                "type": "Action.Submit",
                "title": "Submit",
                "data": {"submissiondialogtype": "webpage_dialog_step_2", "name": "{{nameStep1}}"}
            }
        ]
    }
    """;

    var nextStepCard = JsonSerializer.Deserialize<AdaptiveCard>(nextStepCardJson)
        ?? throw new InvalidOperationException("Failed to deserialize next step card");

    var nextStepTaskInfo = new TaskInfo
    {
        Title = $"Thanks {nameStep1} - Get Email",
        Card = new Attachment
        {
            ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
            Content = nextStepCard
        }
    };

    return new Response(new ContinueTask(nextStepTaskInfo));

case "webpage_dialog_step_2":
    var nameStep2 = GetFormValue("name") ?? "Unknown";
    var emailStep2 = GetFormValue("email") ?? "No email";
    await client.Send($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}");
    return new Response(new MessageTask("Multi-step form completed successfully"));

TypeScript

import { cardAttachment } from '@microsoft/teams.api';
import { AdaptiveCard, TextInput, SubmitAction } from '@microsoft/teams.cards';

// Return from dialog.submit handler to chain to the next step
const dialogCard = new AdaptiveCard(
  {
    type: 'TextBlock',
    text: 'This is a multi-step form',
    size: 'Large',
    weight: 'Bolder',
  },
  new TextInput()
    .withLabel('Name')
    .withIsRequired()
    .withId('name')
    .withPlaceholder('Enter your name')
)
  .withActions(
    new SubmitAction()
      .withTitle('Submit')
      .withData({ submissiondialogtype: 'webpage_dialog_step_1' })
  );

return {
  task: {
    type: 'continue',
    value: {
      title: 'Multi-step Form Dialog',
      card: cardAttachment('adaptive', dialogCard),
    },
  },
};

Python

# In your on_dialog_submit handler, return a ContinueTask to show the next step
from microsoft_teams.api import TaskModuleResponse, TaskModuleContinueResponse, CardTaskModuleTaskInfo
from microsoft_teams.cards import AdaptiveCard, TextInput, SubmitAction, Attachment

next_card = AdaptiveCard(
    body=[
        {"type": "TextBlock", "text": "Step 2: Enter Email", "size": "Large", "weight": "Bolder"},
        {"type": "Input.Text", "id": "email", "label": "Email", "placeholder": "Enter your email", "isRequired": True}
    ],
    actions=[
        {"type": "Action.Submit", "title": "Submit", "data": {"submissiondialogtype": "webpage_dialog_step_2", "name": name}}
    ]
)

return InvokeResponse(
    body=TaskModuleResponse(
        task=TaskModuleContinueResponse(
            value=CardTaskModuleTaskInfo(
                title=f"Thanks {name} - Get Email",
                card=Attachment(content_type="application/vnd.microsoft.card.adaptive", content=next_card)
            )
        )
    )
)

actions de carte Bot Framework et action de carte adaptative.Envoyer des actions

Le schéma des actions de carte Bot Framework est différent des actions de carte Action.Submit adaptative, et la façon d’appeler les boîtes de dialogue est également différente. L’objet data dans Action.Submit contient un msteams objet afin qu’il n’interfère pas avec d’autres propriétés de la carte. Le tableau suivant montre un exemple de chaque action de carte :

action de carte Bot Framework	Action de carte adaptative.Envoyer l’action
{ « type » : « invoke », « title » : « Buy », « value » : { « type » : « tâche/récupération », <...> } }	{ « type » : « Action.Submit », « id » : « btnBuy », « title » : « Buy », « data » : { <...>, « msteams » : { « type » : « tâche/récupération » } } }

Exemple de code

Exemple de nom	Description	.NET	Node.js	Manifeste	Python
Dialogue exemple bots-V4	Cet exemple d’application montre comment utiliser les boîtes de dialogue (appelées modules de tâche dans TeamsJS v1.x) à l’aide de Bot Framework v4.	View	View	N/A	View

Voir aussi

• Cartes et boîtes de dialogue
• Kit de développement logiciel (SDK) Teams Vue d’ensemble des boîtes de dialogue
• SDK Cartes adaptatives Teams - Exécution d’actions
• Migrer de BotBuilder vers le SDK Teams