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 de boutons sur les cartes adaptatives et les cartes Bot Framework qui sont des héros, des miniatures et des connecteurs pour les groupes Microsoft 365. Les dialogues sont souvent une meilleure expérience utilisateur que plusieurs étapes de conversation. Effectuez le suivi de l’état du bot et autorisez l’utilisateur à interrompre ou annuler la séquence.

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

• Nouveau message task/fetchd’appel : l’utilisation de l’action invoke de carte pour les cartes Bot Framework ou de l’action Action.Submit de 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 openUrl de carte pour les cartes Bot Framework ou l’action Action.OpenUrl de carte pour les cartes adaptatives, respectivement. 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.

Appeler une boîte de dialogue à l’aide de task/fetch

Lorsque l’objet value de l’action de carte invoke ou Action.Submit est initialisé et lorsqu’un utilisateur sélectionne le bouton, un message invoke est envoyé au bot. Dans la réponse HTTP au invoke message, il y a un objet TaskInfo incorporé dans un objet wrapper, que Teams utilise pour afficher la boîte de dialogue (appelée module de tâche dans TeamsJS v1.x).

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 héros Bot Framework avec une action Acheterinvokeune carte. La valeur de la propriété type est task/fetch et le reste de l’objet value peut être de votre choix.

2. Le bot reçoit le message HTTP POST invoke HTTP POST.

3. Le bot crée un objet de réponse et le retourne dans le corps de la réponse POST avec un code de réponse HTTP 200. 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 la réponse HTTP 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, l’envoi du résultat au bot est similaire à la façon dont il fonctionne avec les onglets. Pour plus d’informations, consultez l’exemple d’envoi du résultat d’un dialogue. Il existe quelques différences comme suit :

• HTML ou JavaScript qui est TaskInfo.url: une fois que vous avez validé ce que l’utilisateur a entré, vous appelez la microsoftTeams.tasks.submitTask() fonction référencée ci-après à submitTask() des fins de lisibilité. Vous pouvez appeler submitTask() sans paramètre si vous souhaitez que Teams ferme la boîte de dialogue (appelée module de tâche dans TeamsJS v1.x), mais vous devez passer un objet ou une chaîne à votre submitHandler. Transmettez-le comme premier paramètre, result. Teams appelle submitHandler, err est null et result est l’objet ou la chaîne que vous avez passé à submitTask(). Si vous appelez submitTask() avec un paramètre result, vous devez passer un appId ou un tableau de chaînes appId. Cette action permet à Teams de vérifier que l’application qui envoie le résultat est la même que celle qui a appelé la boîte de dialogue. Votre bot reçoit un message task/submit incluant result. Pour plus d'informations, voir la rubrique charge utile detask/fetch et task/submitmessages.
• Carte adaptative qui est TaskInfo.card: le corps de la carte adaptative tel que rempli par l’utilisateur est envoyé au bot via un message task/submit lorsque l’utilisateur sélectionne un bouton Action.Submit.

La section suivante fournit des détails sur la façon de répondre aux task/submit messages.

Répond aux task/submit messages

Lorsque l’utilisateur termine avec une boîte de dialogue (appelée module de tâche dans TeamsJS v1.x) appelée à partir d’un bot, le bot reçoit toujours un task/submit invoke message. Vous avez plusieurs options pour répondre au message task/submit comme suit :

{
  « task » : {
    « type » : « message »,
    « value » : « Message text »
  }
}

{
  « task » : {
    « type » : « continue »,
    « value » : <objet TaskInfo>
  }
}

La section suivante fournit des détails sur la charge utile des messages task/fetch et task/submit.

Charge utile des task/fetch messages et task/submit

Cette section définit le schéma de ce que votre bot reçoit lorsqu’il reçoit un objet task/fetch ou task/submit Bot Framework Activity. Le tableau suivant fournit les propriétés de la charge utile des messages task/fetch et task/submit :

{
  « context » : {
    « theme » : « default » | « dark » | « contrast »,
  },
  « data » : [champ de valeur de la carte Bot Framework] | [champ de données de la carte adaptative]
}

La section suivante fournit un exemple de réception et de réponse à task/fetch et task/submit appeler des messages dans Node.js.

Les onglets suivants fournissent et task/submit appellent task/fetch des messages dans Node.js et C# :

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

protected override Task<TaskModuleResponse> OnTeamsTaskModuleFetchAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var asJobject = JObject.FromObject(taskModuleRequest.Data);
    var value = asJobject.ToObject<CardTaskFetchValue<string>>()?.Data;

    var taskInfo = new TaskModuleTaskInfo();
    switch (value)
    {
        case TaskModuleIds.YouTube:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.YouTube;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
            break;
        case TaskModuleIds.CustomForm:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.CustomForm;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
            break;
        case TaskModuleIds.AdaptiveCard:
            taskInfo.Card = CreateAdaptiveCardAttachment();
            SetTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
            break;
        default:
            break;
    }

    return Task.FromResult(taskInfo.ToTaskModuleResponse());
}

protected override async Task<TaskModuleResponse> OnTeamsTaskModuleSubmitAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var reply = MessageFactory.Text("OnTeamsTaskModuleSubmitAsync Value: " + JsonConvert.SerializeObject(taskModuleRequest));
    await turnContext.SendActivityAsync(reply, cancellationToken);

    return TaskModuleResponseFactory.CreateResponse("Thanks!");
}

private static void SetTaskInfo(TaskModuleTaskInfo taskInfo, UISettings uIConstants)
{
    taskInfo.Height = uIConstants.Height;
    taskInfo.Width = uIConstants.Width;
    taskInfo.Title = uIConstants.Title.ToString();
}

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 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 de la carte. Le tableau suivant montre un exemple de chaque action de carte :

{
  « type » : « invoke »,
  « title » : « Buy »,
  « value » : {
    « type » : « task/fetch »,
    
              <...>
  }
}

{
  « type » : « Action.Submit »,
  « id » : « btnBuy »,
  « title » : « Buy »,
  « data » : {
    
              <...>,
    « msteams » : {
      « type » : « task/fetch »
    }
  }
}

Exemple de code

Guide pas à pas

Suivez le guide pas à pas pour créer et extraire un bot de dialogue dans Teams.

Voir aussi

• Cartes et boîtes de dialogue
• Exemple de code de boîte de dialogue Microsoft Teams dans Node.js
• Exemples Bot Framework