Использование диалоговых окон с ботами

Вызов диалоговых окон (называемых модулями задач в TeamsJS v1.x) из ботов Microsoft Teams с помощью TaskFetchAction кнопок на адаптивных карточках. Диалоговые окна обеспечивают целенаправленное взаимодействие, открывая для пользователя всплывающее окно, что делает их идеальными для сложных форм или многошаговых рабочих процессов.

Существует два способа вызова диалоговых окон.

• Новое сообщение task/fetchо вызове Action.Execute : Использование действия карты для адаптивных карточек с task/fetch, диалоговое окно на основе адаптивной карточки либо в формате HTML динамически извлекается из бота.
• URL-адреса прямой ссылки: используя синтаксис прямой ссылки для диалоговых окон, можно использовать Action.OpenUrl действие карты для адаптивных карточек. При использовании URL-адресов прямой ссылки URL-адрес диалогового окна или текст адаптивной карточки уже известны как позволяющие избежать кругового пути сервера относительно task/fetch.

Важно!

Каждый url и fallbackUrl должен реализовать протокол шифрования HTTPS.

Примечание.

В клиенте Teams версии 1 диалоговые окна назывались модулями задач. Иногда они могут использоваться как синонимы.

Создание средства вызова диалогового окна

Чтобы вызвать диалоговое окно из бота, отправьте адаптивную карточку с TaskFetchAction кнопками. Каждая кнопка содержит данные, которые бот использует, чтобы определить, какое содержимое диалогового окна следует вернуть.

Предупреждение

Облачные службы Майкрософт, включая веб-версии доменов Teams, Outlook и Microsoft 365, мигрируют в *.cloud.microsoft этот домен. Выполните следующие действия как можно скорее, чтобы ваше приложение продолжало отображаться на поддерживаемых узлах веб-клиентов Microsoft 365:

1. Обновите библиотеку TeamsJS до версии 2.19.0 или более поздней. Необходимо позвонить microsoftTeams.app.initialize() , чтобы не увидеть предупреждение в новом домене. Дополнительные сведения о последнем выпуске TeamsJS см. в клиентской библиотеке JavaScript Microsoft Teams.

2. Если вы определили заголовки политики безопасности содержимого (CSP) для своего приложения, обновите директиву frame-ancestors, чтобы включить домен.*.cloud.microsoft Чтобы обеспечить обратную совместимость во время миграции, сохраните существующие frame-ancestors значения в заголовках CSP. Такой подход гарантирует, что ваше приложение продолжит работать как с существующими, так и с будущими приложениями узла Microsoft 365 и сведет к минимуму необходимость последующих изменений.

Обновите следующий домен в frame-ancestors директиве заголовков CSP вашего приложения:

https://*.cloud.microsoft

Следующие шаги содержат инструкции по вызову диалогового окна (называемого модулем задач в TeamsJS v1.x) с помощью task/fetch:

1. На этом изображении показана адаптивная карточка с действием "КупитьAction.Execute" карта. Значение свойства type является task/fetch и остальная часть объекта data может быть на ваш выбор.

2. Бот получает card.action действие. В пакете SDK для Teams это можно сделать с помощью обработчика OnAdaptiveCardAction . Дополнительные сведения см. в разделе Выполнение действий.

3. Бот создает ActionResponse объект и возвращает его. Дополнительные сведения о схеме ответов см . в обсуждении task/submit. В следующем коде представлен пример текста ответа, содержащего объект TaskInfo , внедренный в объект-оболочку:

   {
     "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"
       }
     }
   }
   

   Событие task/fetch и ответ на него для ботов аналогичны microsoftTeams.tasks.startTask() функции в клиентской библиотеке JavaScript Microsoft Teams (TeamsJS).

4. Microsoft Teams отобразит диалоговое окно.

В следующем разделе приведены сведения об отправке результатов диалогового окна.

Отправка результата диалогового окна

Когда пользователь завершит работу с диалоговым окном, результат будет отправлен обратно в ваше приложение. То, как происходит отправка, зависит от типа содержимого диалогового окна:

• Адаптивная карточка (TaskInfo.карта): когда пользователь нажимает Action.Submit кнопку, Teams отправляет диалоговое событие отправки в ваше приложение. Обработчик отправки диалогового окна получает данные формы из карт. В C# используйте атрибут.[TaskSubmit] В TypeScript используйте app.on('dialog.submit', ...). В Python используйте @app.on_dialog_submit.
• Веб-страница (TaskInfo.url): веб-страница вызывает microsoftTeams.tasks.submitTask(formData) клиентскую библиотеку TeamsJS, которая запускает то же событие отправки диалогового окна в приложении.

Обработка событий отправки в диалоговом окне

Когда пользователь отправляет диалоговое окно, бот получает сообщение о вызове task/submit . У вас есть несколько вариантов ответа:

Тип ответа	Сценарий
Без ответа	Самый простой отклик — это отсутствие отклика. Бот не обязан отвечать, когда пользователь заканчивает работу с диалоговым окном.
MessageTask	Teams отобразит сообщение во всплывающем окне сообщения в диалоговом окне.
ContinueTask	Позволяет соединять последовательности адаптивных карточек в мастере или в многоэтапном действии.

На следующих вкладках показано, как обрабатывать события отправки диалоговых окон в .NET, TypeScript и Python:

C# SDK версии 2.1

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.TaskModules;

teams.OnTaskSubmit(async (context, cancellationToken) =>
{
  var data = context.Activity.Value?.Data as JsonElement?;
    if (data == null)
    {
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("No data found in the activity value")
      .Build();
    }

    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 context.SendAsync($"Hi {name}, thanks for submitting the form!", cancellationToken);
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Form was submitted")
              .Build();
        default:
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Unknown submission type")
              .Build();
    }
      });

C# SDK<2.1 (устаревшая версия)

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"))
        )

Многошаговая цепочка диалоговых окон

Адаптивные карточки можно объединить в многошаговый мастер, вернув ContinueTask ответ от обработчика отправки. Каждый шаг возвращает новую карта, а последний шаг возвращает новую MessageTask для закрытия диалогового окна.

C# SDK версии 2.1

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Apps.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");

    TeamsAttachment nextStepAttachment = TeamsAttachment.CreateBuilder()
      .WithAdaptiveCard(JsonSerializer.SerializeToElement(nextStepCard))
      .Build();

    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Continue)
      .WithTitle($"Thanks {nameStep1} - Get Email")
      .WithCard(nextStepAttachment)
      .Build();

case "webpage_dialog_step_2":
    var nameStep2 = GetFormValue("name") ?? "Unknown";
    var emailStep2 = GetFormValue("email") ?? "No email";
    await context.SendAsync($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}", cancellationToken);
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("Multi-step form completed successfully")
      .Build();

C# SDK<2.1 (устаревшая версия)

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)
            )
        )
    )
)

Действия карточки Bot Framework и действие адаптивной карточки Action.Submit

Схема действий карт платформы ботов отличается от действий адаптивной карточкиAction.Submit, а также способ вызова диалоговых окон. Объект data в Action.Submit содержит объект, msteams поэтому он не мешает другим свойствам в карте. В следующей таблице показан пример каждого действия карточки:

Действие карточки Bot Framework	Действие адаптивной карточки Submit action
{ "type": "invoke", "title": "Buy", "value": { "type": "task/fetch", <...> } }	{ "type": "Action.Submit", "id": "btnBuy", "title": "Buy", "data": { <...>, "msteams": { "type": "task/fetch" } } }

Пример кода

Название примера	Описание	.NET	Node.js	Манифест	Python
Диалоговое окно Примеры ботов-V4	В этом примере приложения показано, как использовать диалоговые окна (называемые модулями задач в TeamsJS v1.x) с помощью Bot Framework v4.	Просмотр	Просмотр	Н/Д	Просмотр

См. также

• Карточки и диалоговые окна
• Обзор диалоговых окон пакета SDK для Teams
• Адаптивные карточки пакета SDK для Teams — выполнение действий
• Миграция из BotBuilder в Teams SDK