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

Вызов диалоговых окон (называемых модулями задач в TeamsJS версии 1.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 версии 1.x) с помощью task/fetch:

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

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

3. Бот создает ActionResponse объект и возвращает его. Дополнительные сведения о схеме ответов см. в обсуждении задачи или отправки. В следующем коде приведен пример текста ответа, содержащего объект 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:

.NET

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 для закрытия диалогового окна.

.NET

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

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

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

Пример кода

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

См. также

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