自定义Teams消息扩展添加Settings模块弹出错误如何解决

问题排查及修复步骤 #

1. 补充Manifest域名白名单配置 #

你遗漏了manifest.json中validDomains字段的配置，Teams会拦截所有不在白名单内的外域页面，直接触发你遇到的报错。

• 将process.env.PUBLIC_HOSTNAME对应的值（不带https前缀）添加到manifest的validDomains数组中，示例配置：

{
  ...
  "validDomains": [
    "xxx-yyy-zzz.ngrok.io"
  ],
  "canUpdateConfiguration": true
  ...
}

• 修改manifest后需要删除Teams中原有旁加载的应用，重新上传最新的manifest包，避免缓存导致配置不生效。

2. 完善配置页的Teams SDK初始化逻辑 #

你的settings.html必须完成Teams JS SDK的初始化，否则Teams无法和配置页通信，会判定页面不可用。最小可用的配置页结构如下：

<!DOCTYPE html>
<html>
<head>
    <title>扩展配置</title>
    <!-- 引入Teams JS SDK -->
    <script src="Teams JS SDK资源路径" crossorigin="anonymous"></script>
</head>
<body>
    <script>
        // 初始化SDK
        microsoftTeams.app.initialize().then(() => {
            // 标记配置页可用
            microsoftTeams.app.settings.setValidityState(true);
            // 注册配置保存事件
            microsoftTeams.app.settings.registerOnSaveHandler((saveEvent) => {
                // 处理你的自定义配置逻辑，例如获取表单值
                const customSettings = {
                    "yourConfigKey": "yourConfigValue"
                };
                // 保存配置到Teams
                microsoftTeams.app.settings.setSettings(customSettings);
                // 通知Teams保存完成
                saveEvent.notifySuccess();
            });
        });
    </script>
    <!-- 此处添加你的自定义配置表单 -->
</body>
</html>

3. 优化代码参数和返回结构 #

你的代码整体结构正确，补充类型声明和校验可以避免部分Teams版本的兼容问题：

import { ActionTypes, TurnContext, MessagingExtensionQuery, MessagingExtensionResponse } from "botbuilder";
import { TeamsActivityHandler } from "botbuilder-core";

export class MessageExtensionBot extends TeamsActivityHandler {
  // ...其他逻辑

  protected override async handleTeamsMessagingExtensionConfigurationQuerySettingUrl(
    context: TurnContext, 
    query: MessagingExtensionQuery
  ): Promise<MessagingExtensionResponse> {
    return {
      composeExtension: {
        type: "config",
        suggestedActions: {
          actions: [
            {
              title: "扩展配置",
              type: ActionTypes.OpenUrl,
              value: `https://${process.env.PUBLIC_HOSTNAME}/settings.html`
            }
          ]
        }
      }
    };
  }

  protected override async handleTeamsMessagingExtensionConfigurationSetting(
    context: TurnContext, 
    settings: Record<string, any>
  ): Promise<void> {
    // 此处可添加自定义逻辑，比如将用户保存的配置存储到数据库/状态存储中
    console.log("用户保存的配置：", settings);
    return Promise.resolve();
  }
}

4. 可选调试技巧 #

开启Teams开发者预览模式后，右键点击应用图标选择「获取日志」，可以查看更详细的错误信息，快速定位问题根因。

内容的提问来源于stack exchange，提问作者Serban