Utiliser des dialogues avec des bots

Appelez 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 des 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 workflows à plusieurs étapes.

Il existe deux façons d’appeler des dialogues :

• Nouveau message task/fetchd’appel : L’utilisation de l’action Action.Execute carte pour les cartes adaptatives avec task/fetch, une boîte de dialogue HTML ou basée sur une carte adaptative est extraite dynamiquement à partir de votre bot.
• URL de lien profond : à l’aide de la syntaxe de lien profond pour les dialogues, vous pouvez utiliser l’action Action.OpenUrl carte pour les cartes adaptatives. Avec les URL de lien profond, l’URL de boîte de dialogue ou le corps de la carte adaptative est déjà connu pour éviter un aller-retour de serveur par rapport à 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 la boîte de dialogue à retourner.

Avertissement

Les services cloud de Microsoft, y compris les versions web des domaines Teams, Outlook et 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 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 Bibliothèque de client JavaScript Microsoft Teams.

2. Si vous avez défini des en-têtes de stratégie de sécurité de contenu (CSP) pour votre application, mettez à jour la directive frame-ancestors pour inclure le *.cloud.microsoft domaine. Pour garantir la 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 le besoin 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 un dialogue (appelé module de tâche dans TeamsJS v1.x) à l’aide de task/fetch:

1. Cette image montre une carte adaptative avec une action AcheterAction.Execute 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 Kit de développement logiciel (SDK) Teams, vous gérez cela à l’aide du OnAdaptiveCardAction gestionnaire . Pour plus d’informations, consultez Exécution d’actions.

3. Le bot crée un ActionResponse objet et le retourne. 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 du corps de la 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 de client JavaScript 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’un dialogue.

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

Lorsque l’utilisateur a terminé avec 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. Votre gestionnaire d’envoi de 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', ...). Dans Python, utilisez @app.on_dialog_submit.
• Page web (TaskInfo.url) : la page web appelle microsoftTeams.tasks.submitTask(formData) à partir de la bibliothèque de client 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 boîte de dialogue

Lorsque l’utilisateur envoie une boîte de dialogue, le bot reçoit un message d’appel task/submit . 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 tenu de répondre lorsque l’utilisateur a terminé avec la boîte de dialogue.
MessageTask	Teams affiche un message dans une boîte de dialogue contextuelle.
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 boîte de dialogue dans .NET, TypeScript et Python :

.NET

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 dialogues en plusieurs étapes

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

.NET

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 carte Bot Framework est différent des actions de carte Action.Submit adaptative et la façon d’appeler des dialogues est également différente. L’objet data dans Action.Submit contient un msteams objet afin qu’il n’interfère pas avec les autres propriétés du 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 » : « task/fetch », <...> } }	{ « type » : « Action.Submit », « id » : « btnBuy », « title » : « Buy », « data » : { <...>, « msteams » : { « type » : « task/fetch » } } }

Exemple de code

Exemple de nom	Description	.NET	Node.js	Manifeste	Python
Exemple de boîte de dialogue bots-V4	Cet exemple d’application montre comment utiliser des 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
• Vue d’ensemble des boîtes de dialogue du KIT de développement logiciel (SDK)
• Cartes adaptatives du KIT de développement logiciel (SDK) Teams - Exécution d’actions
• Migrer de BotBuilder vers le Kit de développement logiciel (SDK) Teams