Répondre à l’action d’envoi du module de tâche

  • Article
  • 12 minutes de lecture

Importante

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de message - Kit de développement logiciel (SDK) v3 dans le dossier Ressources de la documentation.

Ce document vous guide sur la façon dont votre application répond aux commandes d’action, telles que l’action d’envoi du module de tâche de l’utilisateur. Une fois qu’un utilisateur a envoyé le module de tâche, votre service web reçoit un message composeExtension/submitAction appeler avec l’ID de commande et les valeurs de paramètre. Votre application dispose de cinq secondes pour répondre à l’appel.

Vous disposez des options suivantes pour répondre :

Si l’application ne répond pas dans les cinq secondes, le client Teams retentera la demande deux fois avant d’envoyer un message d’erreur Impossible d’atteindre l’application. Si le bot répond après le délai d’expiration, la réponse est ignorée.

Remarque

L’application doit différer toutes les actions de longue durée une fois que le bot a répondu à la demande d’appel. Les résultats de l’action de longue durée peuvent être remis sous forme de message.

Pour l’authentification ou la configuration, une fois que l’utilisateur a terminé le processus, l’appel d’origine est renvoyé à votre service web. Le tableau suivant indique les types de réponses disponibles, en fonction de l’emplacement commandContext d’appel de l’extension de message :

Type de réponse Composition Barre de commandes Message
Réponse de la carte ✔️ ✔️ ✔️
Un autre module de tâche ✔️ ✔️ ✔️
Bot avec carte adaptative ✔️ ❌ ✔️
Aucune réponse ✔️ ✔️ ✔️

Remarque

  • Lorsque vous sélectionnez Action.Submit via des cartes ME, il envoie l’activité invoke avec le nom composeExtension, où la valeur est égale à la charge utile habituelle.
  • Lorsque vous sélectionnez Action.Submit via la conversation, vous recevez une activité de message portant le nom onCardButtonClicked, où la valeur est égale à la charge utile habituelle.

Si l’application contient un bot conversationnel, installez-le dans la conversation, puis chargez le module de tâche. Le bot est utile pour obtenir un contexte supplémentaire pour le module de tâche. Pour installer le bot conversationnel, consultez Demande d’installation de votre bot conversationnel.

Événement d’appel submitAction

Voici des exemples de réception du message d’appel :

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
  //code to handle the submit action
}

Répondre avec une carte insérée dans la zone de composition du message

La méthode la plus courante pour répondre à la demande de composeExtension/submitAction consiste à insérer une carte dans la zone de composition du message. L’utilisateur envoie la carte à la conversation. Pour plus d’informations sur l’utilisation des cartes, consultez cartes et actions de carte.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
    var response = new MessagingExtensionActionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            AttachmentLayout = "list",
            Type = "result",
        },
    };
    var createCardData = ((JObject)action.Data).ToObject<CreateCardData>();
var card = new HeroCard
{
     Title = createCardData.Title,
     Subtitle = createCardData.Subtitle,
     Text = createCardData.Text,
};
    var attachments = new List<MessagingExtensionAttachment>();
    attachments.Add(new MessagingExtensionAttachment
    {
        Content = card,
        ContentType = HeroCard.ContentType,
        Preview = card.ToAttachment(),
    });
    response.ComposeExtension.Attachments = attachments;
    return response;
}

Répondre avec un autre module de tâche

Vous pouvez choisir de répondre à l’événement submitAction avec un module de tâche supplémentaire. Cela est utile lorsque vous avez besoin des éléments suivants :

  • Collectez de grandes quantités d’informations.
  • Modifiez dynamiquement la collecte d’informations en fonction de l’entrée utilisateur.
  • Validez les informations envoyées par l’utilisateur et renvoyez le formulaire avec un message d’erreur en cas de problème.

La méthode de réponse est la même que réponse à l’événement fetchTask initial. Si vous utilisez le SDK Bot Framework, les mêmes déclencheurs d’événements sont utilisés pour les deux actions d’envoi. Pour que cela fonctionne, vous devez ajouter une logique qui détermine la réponse correcte.

Réponse du bot avec carte adaptative

Remarque

La condition préalable pour obtenir la réponse du bot avec une carte adaptative est que vous devez ajouter l’objet bot au manifeste de votre application et définir l’étendue requise pour le bot. Utilisez le même ID que votre extension de message pour votre bot.

Vous pouvez également répondre au submitAction en insérant un message avec une carte adaptative dans le canal avec un bot. L’utilisateur peut afficher un aperçu du message avant de l’envoyer. Cela est utile dans les scénarios où vous collectez des informations auprès des utilisateurs avant de créer une réponse de carte adaptative, ou lorsque vous mettez à jour la carte après qu’une personne interagit avec elle.

Le scénario suivant montre comment l’application Polly configure un sondage sans inclure les étapes de configuration dans la conversation de canal :

Pour configurer le sondage :

  1. L’utilisateur sélectionne l’extension de message pour appeler le module de tâche.

  2. L’utilisateur configure le sondage avec le module de tâche.

  3. Après avoir soumis le module de tâche, l’application utilise les informations fournies pour générer le sondage en tant que carte adaptative et l’envoie en tant que réponse botMessagePreview au client.

  4. L’utilisateur peut ensuite afficher un aperçu du message de carte adaptative avant que le bot ne l’insère dans le canal. Si l’application n’est pas membre du canal, sélectionnez Send pour l’ajouter.

    Remarque

    • Les utilisateurs peuvent également choisir de Edit le message, ce qui les renvoie au module de tâche d’origine.
    • L’interaction avec la carte adaptative modifie le message avant de l’envoyer.

  5. Une fois que l’utilisateur a Sendsélectionné , le bot publie le message sur le canal.

Répondre à l’action d’envoi initiale

Votre module de tâche doit répondre au message de composeExtension/submitAction initial avec un aperçu de la carte que le bot envoie au canal. L’utilisateur peut vérifier la carte avant de l’envoyer et essayer d’installer votre bot dans la conversation si le bot est déjà installé.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  dynamic createCardData = ((JObject) action.Data).ToObject(typeof(JObject));
  var response = new MessagingExtensionActionResponse
  {
    ComposeExtension = new MessagingExtensionResult
    {
      Type = "botMessagePreview",
      ActivityPreview = MessageFactory.Attachment(new Attachment
      {
        Content = new AdaptiveCard("1.0")
        {
          Body = new List<AdaptiveElement>()
          {
            new AdaptiveTextBlock() { Text = "FormField1 value was:", Size = AdaptiveTextSize.Large },
            new AdaptiveTextBlock() { Text = Data["FormField1"] as string }
          },
          Height = AdaptiveHeight.Auto,
          Actions = new List<AdaptiveAction>()
          {
            new AdaptiveSubmitAction
            {
              Type = AdaptiveSubmitAction.TypeName,
              Title = "Submit",
              Data = new JObject { { "submitLocation", "messagingExtensionFetchTask" } },
            },
          }
        },
        ContentType = AdaptiveCard.ContentType
      }) as Activity
    }
  };

  return response;
}

Événements d’envoi et de modification botMessagePreview

Votre extension de message doit répondre à deux nouveaux types de l’appel composeExtension/submitAction , où value.botMessagePreviewAction = "send"et value.botMessagePreviewAction = "edit".

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewEditAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

Répondre à la modification botMessagePreview

Si l’utilisateur modifie la carte avant de l’envoyer, en sélectionnant Modifier, vous recevez un appel composeExtension/submitAction avec value.botMessagePreviewAction = edit. Répondez en retournant le module de tâche que vous avez envoyé, en réponse à l’appel initial composeExtension/fetchTask qui a commencé l’interaction. Cela permet à l’utilisateur de démarrer le processus en entrant à nouveau les informations d’origine. Utilisez les informations disponibles pour mettre à jour le module de tâche afin que l’utilisateur n’ait pas besoin de renseigner toutes les informations à partir de zéro. Pour plus d’informations sur la réponse à l’événement de fetchTask initial, consultez réponse à l’événement fetchTask initial.

Répondre à botMessagePreview envoyer

Une fois que l’utilisateur a sélectionné Envoyer, vous recevez un appel composeExtension/submitAction avec value.botMessagePreviewAction = send. Votre service web doit créer et envoyer un message proactif avec la carte adaptative à la conversation, et également répondre à l’appel.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  var activityPreview = action.BotActivityPreview[0];
  var attachmentContent = activityPreview.Attachments[0].Content;
  var previewedCard = JsonConvert.DeserializeObject<AdaptiveCard>(attachmentContent.ToString(),
          new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
  
  previewedCard.Version = "1.0";

  var responseActivity = Activity.CreateMessageActivity();
  Attachment attachment = new Attachment()
  {
    ContentType = AdaptiveCard.ContentType,
    Content = previewedCard
  };
  responseActivity.Attachments.Add(attachment);
  
  // Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };
  
  await turnContext.SendActivityAsync(responseActivity);

  return new MessagingExtensionActionResponse();
}

Attribution d’utilisateur pour les messages de bots

Dans les scénarios où un bot envoie des messages pour le compte d’un utilisateur, l’attribution du message à cet utilisateur aide à l’engagement et présente un flux d’interaction plus naturel. Cette fonctionnalité vous permet d’attribuer un message de votre bot à un utilisateur au nom duquel il a été envoyé.

Dans l’image suivante, à gauche se trouve un message de carte envoyé par un bot sans attribution d’utilisateur et à droite une carte envoyée par un bot avec attribution d’utilisateur.

Bots d’attribution d’utilisateur

Pour utiliser l’attribution d’utilisateur dans teams, vous devez ajouter l’entité de mentionOnBehalfOf à ChannelData dans votre charge utile Activity envoyée à Teams.

    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }

Détails du schéma d’entité OnBehalfOf

La section suivante est une description des entités dans le tableau OnBehalfOf :

Champ Type Description
itemId Entier Décrit l’identification de l’élément. Sa valeur doit être 0.
mentionType Chaîne Décrit la mention d’une « personne ».
mri Chaîne Identificateur de ressource de message (MRI) de la personne au nom de laquelle le message est envoyé. Le nom de l’expéditeur du message s’affiche sous la forme «< utilisateur> via <le nom du> bot ».
displayName Chaîne Nom de la personne. Utilisé comme solution de secours dans le cas où la résolution de noms n’est pas disponible.

Exemple de code

Exemple de nom Description .NET Node.js
Action d’extension de message Teams Décrit comment définir des commandes d’action, créer un module de tâche et répondre à l’action d’envoi du module de tâche. View View
Recherche d'extension des messages Teams Décrit comment définir les commandes de recherche et répondre aux recherches. View View

Étape suivante

Définir les commandes de recherche

Voir aussi