Répondre à l’action d’envoi du dialogue

  • Article

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 la boîte de dialogue de l’utilisateur (appelée module de tâche dans TeamsJS v1.x) action d’envoi. Une fois qu’un utilisateur a envoyé la boîte de dialogue, votre service web reçoit un message d’appel composeExtensions/submitAction 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 retente 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.
  • Votre application dispose de cinq secondes pour répondre au message d’appel.

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 ✔️ ✔️ ✔️
Une autre boîte de dialogue ✔️ ✔️ ✔️
Bot avec carte adaptative ✔️ ❌ ✔️
Aucune réponse ✔️ ✔️ ✔️

Remarque

  • Lorsque vous sélectionnez Action.Envoyer via les cartes ME, il envoie l’activité d’appel avec le nom composeExtensions, 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 la boîte de dialogue. Le bot est utile pour obtenir plus de contexte pour le dialogue. 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 composeExtensions/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 une autre boîte de dialogue

Vous pouvez choisir de répondre à l’événement avec une submitAction boîte de dialogue supplémentaire. Il est utile dans les scénarios 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.

  • Outlook ne prend pas en charge la réponse du bot avec la carte adaptative.

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. Il 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 le carte après qu’une personne a interagi 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 la boîte de dialogue.

  2. L’utilisateur configure le sondage avec la boîte de dialogue .

  3. Lorsque l’utilisateur envoie la boîte de dialogue, l’application utilise les informations fournies pour générer le sondage en tant que carte adaptative et l’envoie en tant que botMessagePreview réponse 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 sélectionner Edit le message, ce qui les renvoie à la boîte de dialogue 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 boîte de dialogue doit répondre au message initial composeExtensions/submitAction avec un aperçu du carte que le bot envoie au canal. L’utilisateur peut vérifier le 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 composeExtensions/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 composeExtensions/submitAction avec value.botMessagePreviewAction = edit. Répondez en retournant la boîte de dialogue que vous avez envoyée, en réponse à l’appel initial composeExtensions/fetchTask qui a commencé l’interaction. L’utilisateur peut démarrer le processus en entrant de nouveau les informations d’origine. Utilisez les informations disponibles pour mettre à jour la boîte de dialogue afin que l’utilisateur n’ait pas besoin de remplir 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 composeExtensions/submitAction avec value.botMessagePreviewAction = send. Votre service web doit créer et envoyer un message 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 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 facilite l’engagement et affiche un flux d’interaction plus naturel. Cette fonctionnalité permet au bot d’afficher les messages au nom d’un utilisateur avec le nom de l’utilisateur affiché dans l’en-tête de réponse carte adaptative.

Les images suivantes affichent un message de carte adaptative envoyé par un bot. L’image de gauche est sans attribution d’utilisateur et l’image de droite est avec l’attribution utilisateur. L’image avec attribution utilisateur affiche le nom de l’utilisateur au format : username via bot (Megan Bowen via Poll) dans l’en-tête de carte adaptative.

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.

// 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
      }  
    }
  };

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 Manifeste
Action d’extension de message Teams Cet exemple montre comment définir des commandes d’action, créer un dialogue et répondre à l’action d’envoi du dialogue. View View View
Aperçu de l’action d’extension de message Cet exemple montre comment utiliser l’aperçu de l’action dans Les extensions de messagerie à l’aide de Bot Framework v4. View View View
Recherche d'extension des messages Teams Cet exemple montre comment générer une extension de message basée sur Recherche. Il recherche les packages NuGet et affiche les résultats dans l’extension de messagerie basée sur la recherche. View View View

Étape suivante

Définir les commandes de recherche

Voir aussi