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

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de messagerie - V3 SDK 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’soumission du module de tâche de l’utilisateur. Une fois qu’un utilisateur a soumis le module de tâche, votre service web reçoit un message d’appel avec l’ID de commande et les valeurs composeExtension/submitAction de paramètre. Votre application dispose de cinq secondes pour répondre à l’appel, sinon l’utilisateur reçoit un message d’erreur « Impossible d’atteindre l’application » et toute réponse à appeler est ignorée par le client Teams.

Vous avez les options suivantes pour répondre :

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

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

Notes

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

Si l’application contient un bot de conversation, 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 un bot de conversation, voir Demande d’installation de votre bot de conversation.

Événement d’appel submitAction

Voici quelques 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 composer un message

Le moyen le plus courant de répondre à la demande consiste à insérer une carte composeExtension/submitAction dans la zone de composition d’un message. L’utilisateur soumet la carte à la conversation. Pour plus d’informations sur l’utilisation des cartes, voir les cartes et les 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 à submitAction l’événement avec un module de tâche supplémentaire. Cela est utile lorsque vous devez :

  • Collecter de grandes quantités d’informations.
  • Modifiez dynamiquement la collection d’informations en fonction de l’entrée de l’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 pour répondre à l’événement fetchTask initial. Si vous utilisez le SDK Bot Framework, les mêmes déclencheurs d’événements pour les deux actions d’soumission. Pour que cela fonctionne, vous devez ajouter une logique qui détermine la réponse correcte.

Réponse du bot avec carte adaptative

Notes

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

Vous pouvez également y répondre en insérant un message avec une carte adaptative submitAction 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 messagerie 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 créer le sondage en tant que carte adaptative et l’envoie en réponse botMessagePreview au client.

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

    Notes

    • Les utilisateurs peuvent également sélectionner Edit le message, 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 Send a sélectionné le bot, il publie le message sur le canal.

Répondre à l’action d’soumission initiale

Votre module de tâche doit répondre au message initial avec un aperçu de la carte que le composeExtension/submitAction bot envoie au canal. L’utilisateur peut vérifier la carte avant l’envoi et essayer d’installer votre bot dans la conversation si le bot n’est pas 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 messagerie doit répondre à deux nouveaux types d’appel, composeExtension/submitActionvalue.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 l’envoi, en sélectionnant Modifier, vous recevez un composeExtension/submitAction appel avec value.botMessagePreviewAction = edit . Répondez en renvoyant 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 réentreérant les informations d’origine. Utilisez les informations disponibles pour mettre à jour le module de tâche afin que l’utilisateur n’a pas besoin de remplir toutes les informations de A à Z. Pour plus d’informations sur la réponse à l’événement initial, voir fetchTask répondre à l’événement fetchTask initial.

Répondre à l’envoi botMessagePreview

Une fois que l’utilisateur a sélectionné l’envoi, vous recevez un composeExtension/submitAction appel avec value.botMessagePreviewAction = send . Votre service web doit créer et envoyer un message proactif avec la carte adaptative à la conversation, ainsi que 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 des utilisateurs 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 facilite 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 de qui 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 mention à votre charge utile OnBehalfOf qui est envoyée à ChannelData Activity Teams.

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

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

La section suivante décrit les entités du OnBehalfOf tableau :

Champ Type Description
itemId Entier Décrit l’identification de l’élément. Sa valeur doit être 0 .
mentionType String Décrit la mention d’une « personne ».
mri String Identificateur de ressource de message (IRM) de la personne au nom de laquelle le message est envoyé. Le nom de l’expéditeur du message s’affiche comme « <user> <bot name> jusqu’à ».
displayName String Nom de la personne. Utilisé comme solution de retour en cas d’indisponibilité de la résolution des noms.

Exemple de code

Exemple de nom Description .NET Node.js
Teams d’extension de messagerie Décrit comment définir des commandes d’action, créer un module de tâche et répondre à une action d’soumission de module de tâche. View View
Teams d’extension de messagerie Décrit comment définir des commandes de recherche et répondre aux recherches. View View

Étape suivante

Voir aussi

Répondre à la commande de recherche