Note
本文介绍了由 标准线束驱动的代理或代理流中使用的功能。
代理画布控制代理向用户显示的方式。 可以通过两种方式自定义画布:
在网站中使用 JavaScript 和 CSS 自定义默认画布。 使用此选项进行简单更改。
使用基于Bot Framework Web 聊天的自定义画布。 此选项需要开发体验并支持完全自定义。
还可以将自定义画布与配置 自动对话启动相结合。
可以在 门户中更改代理名称和图标。
发布代理后,用户可以通过 Web 聊天 canvas 与之交互。
Important
可以安装和使用本文中包含的示例代码,仅用于 Copilot Studio。 此示例代码按“原样”提供,且不包含在任何服务级别协议或支持服务范围内。 你承担使用它的风险。
Microsoft 不提供任何明示担保、保证或条件,并且不提供任何默示担保,包括适销性、特定用途适用性以及不侵犯他人权利的默示担保。
更改智能体的名称和图标
Important
- 更新代理的图标后,新图标可能需要长达 24 小时才能随处显示。
- 如果您的代理连接到 用于客户服务的 Omnichannel,则在 Azure 门户中注册的 “显示名称” 属性会定义其名称。
- 如果您的应用程序旨在发布到 Teams,请查看 Microsoft Teams 开发人员文档中的图标要求。
转到代理的 “概述 ”页。
选择详情旁的编辑。
根据需要更改代理的名称和图标。
选择“保存”。
自定义默认画布(简单)
使用 JavaScript 和 CSS 调整默认画布。
首先,配置你部署代理画布的位置。
将示例 HTML 代码复制到一个名为
index.html的文件中。 还可以使用 HTML 试用编辑器。<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="description" content="Contoso Web Chat Assistant" /> <title>Contoso Sample Web Chat Test</title> <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script> <script> let webChatInstance = null; let directLineUrl = null; // Replace with your token endpoint const tokenEndpoint = "<YOUR TOKEN ENDPOINT>"; const styleOptions = { "accent": "#0078D4", "autoScrollSnapOnPage": true, "autoScrollSnapOnPageOffset": 0, "avatarBorderRadius": "7%", "avatarSize": 31, "backgroundColor": "#e8e9eb", "botAvatarBackgroundColor": "#ffffff00", "botAvatarImage": "https://powercatexternal.blob.core.windows.net/creatorkit/Assets/ChatbotLogoBlue.png", "botAvatarInitials": "B", "bubbleAttachmentMaxWidth": 480, "bubbleAttachmentMinWidth": 250, "bubbleBackground": "#f0eded", "bubbleBorderColor": "#f5f5f5", "bubbleBorderRadius": 41, "bubbleBorderStyle": "solid", "bubbleBorderWidth": 1, "bubbleFromUserBackground": "#ebefff", "bubbleFromUserBorderColor": "#f5f5f5", "bubbleFromUserBorderRadius": 41, "bubbleFromUserBorderStyle": "solid", "bubbleFromUserBorderWidth": 1, "bubbleFromUserNubOffset": 0, "bubbleFromUserNubSize": 0, "bubbleFromUserTextColor": "#242424", "bubbleImageHeight": 10, "bubbleImageMaxHeight": 240, "bubbleImageMinHeight": 240, "bubbleMessageMaxWidth": 480, "bubbleMessageMinWidth": 120, "bubbleMinHeight": 50, "bubbleNubOffset": 0, "bubbleTextColor": "#242424", "emojiSet": true, "fontSizeSmall": "70%", "hideUploadButton": false, "messageActivityWordBreak": "break-word", "monospaceFont": "Consolas", "paddingRegular": 10, "paddingWide": 10, "primaryFont": null, "sendBoxBackground": "#e8e9eb", "sendBoxBorderTop": "solid 1px #808080", "sendBoxButtonColor": "#0078d4", "sendBoxButtonColorOnHover": "#006cbe", "sendBoxButtonShadeBorderRadius": 40, "sendBoxButtonShadeColorOnHover": "", "sendBoxHeight": 60, "sendBoxPlaceholderColor": "#171616", "sendBoxTextColor": "#2e2d2d", "showAvatarInGroup": "status", "spinnerAnimationHeight": 16, "spinnerAnimationPadding": 12, "spinnerAnimationWidth": 16, "subtleColor": "#000000FF", "suggestedActionBackgroundColor": "#006FC4FF", "suggestedActionBackgroundColorOnHover": "#0078D4", "suggestedActionBorderColor": "", "suggestedActionBorderRadius": 10, "suggestedActionBorderWidth": 1, "suggestedActionLayout": "flow", "suggestedActionTextColor": "#FFFFFFFF", "typingAnimationBackgroundImage": "url('https://wpamelia.com/wp-content/uploads/2018/11/ezgif-2-6d0b072c3d3f.gif')", "typingAnimationDuration": 5000, "typingAnimationHeight": 20, "typingAnimationWidth": 64, "userAvatarBackgroundColor": "#222222", "userAvatarImage": "https://avatars.githubusercontent.com/u/8174072?v=4&size=64", "userAvatarInitials": "U" }; const backgroundImage = ""; document.addEventListener('DOMContentLoaded', () => { const root = document.documentElement; root.style.setProperty('--primary-color', createGradient(styleOptions.accent)); root.style.setProperty('--header-textColor', styleOptions.suggestedActionTextColor); if (backgroundImage) { const webchatElement = document.getElementById('webchat'); webchatElement.style.backgroundImage = `url(${backgroundImage})`; webchatElement.style.backgroundSize = 'cover'; webchatElement.style.backgroundPosition = 'center'; webchatElement.style.backgroundRepeat = 'no-repeat'; const overlay = document.createElement('div'); overlay.className = 'webchat-overlay'; webchatElement.appendChild(overlay); } }); function createGradient(baseColor) { const r = parseInt(baseColor.slice(1, 3), 16); const g = parseInt(baseColor.slice(3, 5), 16); const b = parseInt(baseColor.slice(5, 7), 16); const lighterColor = `#${Math.min(255, r + 30).toString(16).padStart(2, '0')}${Math.min(255, g + 30).toString(16).padStart(2, '0')}${Math.min(255, b + 30).toString(16).padStart(2, '0')}`; const darkerColor = `#${Math.max(0, r - 30).toString(16).padStart(2, '0')}${Math.max(0, g - 30).toString(16).padStart(2, '0')}${Math.max(0, b - 30).toString(16).padStart(2, '0')}`; return `linear-gradient(135deg, ${lighterColor}, ${baseColor}, ${darkerColor})`; } const environmentEndPoint = tokenEndpoint.slice( 0, tokenEndpoint.indexOf("/powervirtualagents") ); const apiVersion = tokenEndpoint .slice(tokenEndpoint.indexOf("api-version")) .split("=")[1]; const regionalChannelSettingsURL = `${environmentEndPoint}/powervirtualagents/regionalchannelsettings?api-version=${apiVersion}`; function showChat() { const popup = document.getElementById("chatbot-popup"); const openButton = document.getElementById("open-chat"); popup.classList.add("visible"); openButton.classList.add("hidden"); } function hideChat() { const popup = document.getElementById("chatbot-popup"); const openButton = document.getElementById("open-chat"); popup.classList.remove("visible"); openButton.classList.remove("hidden"); } function createCustomStore() { return window.WebChat.createStore( {}, ({ dispatch }) => (next) => (action) => { if (action.type === "DIRECT_LINE/CONNECT_FULFILLED") { dispatch({ type: "DIRECT_LINE/POST_ACTIVITY", meta: { method: "keyboard" }, payload: { activity: { channelData: { postBack: true }, name: "startConversation", type: "event", }, }, }); } return next(action); } ); } async function restartConversation() { try { if (!directLineUrl) { console.error("DirectLine URL not initialized"); return; } const response = await fetch(tokenEndpoint); const conversationInfo = await response.json(); if (!conversationInfo.token) { throw new Error("Failed to get conversation token"); } const newDirectLine = window.WebChat.createDirectLine({ domain: `${directLineUrl}v3/directline`, token: conversationInfo.token, }); const webchatElement = document.getElementById("webchat"); webChatInstance = window.WebChat.renderWebChat( { directLine: newDirectLine, styleOptions, store: createCustomStore(), }, webchatElement ); } catch (err) { console.error("Failed to restart conversation:", err); } } async function initializeChat() { try { const response = await fetch(regionalChannelSettingsURL); const data = await response.json(); directLineUrl = data.channelUrlsById.directline; if (!directLineUrl) { throw new Error("Failed to get DirectLine URL"); } const conversationResponse = await fetch(tokenEndpoint); const conversationInfo = await conversationResponse.json(); if (!conversationInfo.token) { throw new Error("Failed to get conversation token"); } const directLine = window.WebChat.createDirectLine({ domain: `${directLineUrl}v3/directline`, token: conversationInfo.token, }); webChatInstance = window.WebChat.renderWebChat( { directLine, styleOptions, store: createCustomStore(), }, document.getElementById("webchat") ); } catch (err) { console.error("Failed to initialize chat:", err); } } initializeChat(); </script> <style> :root { --primary-gradient: var(--primary-color); --chat-width: 450px; --chat-height: 520px; --header-height: 56px; --border-radius: 16px; --transition-speed: 0.3s; } * { margin: 0; padding: 0; box-sizing: border-box; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; } body { min-height: 100vh; background-color: #f3f4f6; } #chatbot-popup { display: none; position: fixed; bottom: 32px; right: 32px; width: var(--chat-width); height: var(--chat-height); background: white; border-radius: var(--border-radius); box-shadow: 0 18px 40px -5px rgba(0, 0, 0, 0.2), 0 15px 20px -5px rgba(0, 0, 0, 0.1); overflow: hidden; opacity: 0; transform-origin: bottom right; transform: scale(0.95); transition: all var(--transition-speed) ease-in-out; z-index: 999; } #chatbot-popup.visible { display: block; opacity: 1; transform: scale(1); } #chatbot-header { background: var(--primary-color); padding: 16px 20px; height: var(--header-height); display: flex; justify-content: space-between; align-items: center; color: var(--header-textColor); } .header-title { display: flex; align-items: center; gap: 12px; font-size: 16px; font-weight: 500; } .header-buttons { display: flex; gap: 12px; align-items: center; } .icon-button { background: none; border: none; color: var(--header-textColor); cursor: pointer; padding: 8px; border-radius: 8px; display: flex; align-items: center; justify-content: center; transition: all 0.2s ease; } .icon-button:hover { color: var(--header-textColor); background: rgba(255, 255, 255, 0.1); } .icon-button:focus { outline: 2px solid rgba(255, 255, 255, 0.5); outline-offset: 2px; } #webchat { height: calc(100% - var(--header-height)); background-color: #f9fafb; position: relative; } .webchat-overlay { position: absolute; top: 0; left: 0; right: 0; bottom: 0; background: rgba(255, 255, 255, 0.85); pointer-events: none; z-index: 1; } #webchat > div { position: relative; z-index: 2; } #webchat .webchat__basic-transcript__content { white-space: pre-wrap !important; word-break: break-word !important; } #webchat .webchat__bubble__content { padding: 8px 12px !important; } #webchat .webchat__bubble { max-width: 85% !important; margin: 8px !important; } #webchat .webchat__basic-transcript__content ul, #webchat .webchat__basic-transcript__content ol, #webchat .webchat__bubble__content ul, #webchat .webchat__bubble__content ol { padding-left: 24px !important; margin: 8px 0 !important; list-style-position: outside !important; } #webchat .webchat__basic-transcript__content li, #webchat .webchat__bubble__content li { margin: 4px 0 !important; padding-left: 4px !important; } #open-chat { position: fixed; bottom: 32px; right: 32px; width: 64px; height: 64px; border-radius: 50%; background: var(--primary-gradient); border: none; cursor: pointer; display: flex; align-items: center; justify-content: center; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1); transition: all var(--transition-speed) ease-in-out; z-index: 998; } #open-chat.hidden { opacity: 0; transform: scale(0.95) translateY(10px); pointer-events: none; } #open-chat:hover { transform: translateY(-4px); box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); } #open-chat:focus { outline: 3px solid rgba(79, 70, 229, 0.5); outline-offset: 2px; } #open-chat svg { width: 28px; height: 28px; color: white; transition: transform 0.2s ease; } .main-content { max-width: 1200px; margin: 0 auto; padding: 48px 24px; } .main-content h1 { font-size: 36px; color: #111827; text-align: center; } .main-content p { font-size: 18px; color: #4b5563; line-height: 1.6; margin-bottom: 48px; text-align: center; max-width: 800px; margin-left: auto; margin-right: auto; } .content-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 32px; margin-bottom: 32px; } .content-box { background: linear-gradient(135deg, #e6e6e6, #c4c4c4, #9f9f9f); padding: 32px; border-radius: 12px; box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06); min-height: 300px; display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center; position: relative; overflow: hidden; } .content-box::before { content: ''; position: absolute; top: 0; left: 0; right: 0; height: 4px; } .content-box.featured { grid-column: span 2; min-height: 350px; background: linear-gradient(135deg, #e6e6e6, #c4c4c4, #9f9f9f); color: #000000; } .content-box h2 { font-size: 24px; margin-bottom: 16px; position: relative; } .content-box p { font-size: 16px; color: #6b7280; margin-bottom: 0; } .content-box.featured p { color: #000000; } @media (max-width: 768px) { .content-grid { grid-template-columns: 1fr; } .content-box.featured { grid-column: span 1; } .main-content { padding: 24px 16px; } .main-content h1 { font-size: 28px; } #chatbot-popup { width: 100%; height: 100%; bottom: 0; right: 0; border-radius: 0; } } </style> </head> <body> <div class="main-content"> <h1>Header</h1> <p>Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat.</p> <div class="content-grid"> <div class="content-box featured"> <h2>Featured Content</h2> <p>Primary content area with custom styling and gradient background</p> </div> <div class="content-box"> <h2>Section One</h2> <p>Content box with minimal design</p> </div> <div class="content-box"> <h2>Section Two</h2> <p>Another content section with consistent styling</p> </div> </div> </div> <div id="chatbot-popup" role="complementary" aria-label="Chat Assistant"> <div id="chatbot-header"> <div class="header-title"> <svg class="chat-icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" > <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" ></path> </svg> <span>Contoso Assistant</span> </div> <div class="header-buttons"> <button class="icon-button" id="restart-button" onclick="restartConversation()" aria-label="Restart Conversation" > <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" > <path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" ></path> <path d="M3 3v5h5"></path> </svg> </button> <button class="icon-button" id="close-button" onclick="hideChat()" aria-label="Close Chat" > <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" > <line x1="18" y1="6" x2="6" y2="18"></line> <line x1="6" y1="6" x2="18" y2="18"></line> </svg> </button> </div> </div> <div id="webchat" role="main"></div> </div> <button id="open-chat" onclick="showChat()" aria-label="Open Chat Assistant" > <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" > <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" ></path> </svg> </button> </body> </html>在
index.html中,替换:const tokenEndpoint = "<YOUR TOKEN ENDPOINT>";使用您的令牌终结点。
在新式浏览器中打开
index.html,例如Microsoft Edge。测试代理。
如果代理未响应:
- 确保代理已发布。
- 验证令牌终结点值。
- 确认令牌终结点在
=后面,并以双引号"括住。
检索智能体的令牌终结点
无论您使用的是默认画布还是连接的自定义画布,都需要智能体的令牌端点。
在 “设置”中,选择 “频道”。
选择电子邮件。
在 令牌终结点旁边,选择“ 复制”。
自定义智能体图标、背景颜色和名称
使用 styleOptions 对象配置预定义样式。
有关可自定义的内容和指向 defaultStyleOptions.js 文件的链接的详细信息,请参阅 Web 聊天自定义。
更改智能体图标
使用以下示例代码更新
index.html文件:const styleOptions = { "accent": "#00809d", "botAvatarBackgroundColor": "#FFFFFF", "botAvatarImage": "https://learn.microsoft.com/azure/bot-service/v4sdk/media/logo_bot.svg", "botAvatarInitials": "BT", "userAvatarImage": "https://avatars.githubusercontent.com/u/661465", "userAvatarInitials": "U" };将两个头像图片替换为您的公司图像。 如果你没有图片网址,建议使用Base64编码的图片字符串。
更改背景颜色
在
index.html中为backgroundColor定义添加一个styleOptions元素:const styleOptions = { "backgroundColor": "lightgray", // ... };换
backgroundColor成你喜欢的任何颜色。 使用标准的CSS颜色名称、RGB值或HEX格式。
更改智能体名称
用以下代码更新
<h1>文件中的index.html头部文本:<body> <div id="banner"> <h1><img src="contoso-agent.png"> Contoso agent name</h1> </div> <!-- ... -->将此文本更改为要用于称呼智能体的任何内容。 你也可以插入图片,但可能需要调整样式使其适合标题部分。
自定义和托管聊天区域(高级)
您可以将 Copilot Studio 智能体与作为独立 Web 应用托管的自定义画布连接起来。 如果你需要在多个网页上嵌入定制的 iFrame,这个选项效果最佳。
Note
托管自定义画布需要进行软件开发。 本指南适用于经验丰富的 IT 专业人员,例如对开发人员工具、实用工具和集成开发环境(IDE)有充分了解的 IT 管理员或开发人员。
从以下示例之一开始,这些示例是自定义生成的,适用于 Copilot Studio:
完整组件包 是一个能够显示所有来自 Copilot Studio 的丰富内容的自定义画布。 例如:
位置和文件上传是一个自定义画布,能够获取用户位置并将其发送到 Copilot Studio 代理。 例如:
或者,可以尝试 Bot Framework 中的其他一些示例 Web 聊天 画布。
和默认画布一样,你可以用 styleSetOptions 来调整自定义画布。 所有可自定义属性都列在 defaultStyleOptions.js中。 有关可自定义的内容的详细信息,请参阅 Web 聊天 自定义。
支持在自定义画布中设置连接
当由标准 harness 驱动的代理需要用户连接时,聊天画布会收到要求连接的自适应卡片。 你的定制画布必须能处理卡片的 Action.OpenUrlDialog 操作。 没有这种处理,选择连接不会打开当前获得焦点的连接窗口。
打开连接窗口
- 在你的 自适应卡片 渲染器中注册
Action.OpenUrlDialog并读取其url属性。 只接受绝对http://或https://URL。 - 在打开目标源之前,请先确定其是否可信。 只信任你控制的来源,或者你的安全团队审核并列入允许列表的来源。
- 使用
window.open(url, "_blank", "popup")直接打开用户所选内容中的 URL。 通过用户操作打开窗口可以降低浏览器屏蔽它的可能性。 - 对于受信任的目的地,在
window.open的windowFeatures参数中,省略noopener和noreferrer,以便连接窗口可将结果返回给window.opener。 对于其他目的地,请使用noopener,noreferrer,且不要接受返回消息。 - 保留返回的
Window引用和需要连接的卡片的活动 ID。 如果弹出窗口被阻止,或者用户在未获得有效结果的情况下关闭了,请确保提供继续或其他恢复操作。 不要把关闭窗口当作连接已成功建立。
自适应卡片 JavaScript SDK 默认不实现Action.OpenUrlDialog。 通过 SerializationContext.actionRegistry注册动作,或者直接在你拥有的渲染器中处理动作。
Action.OpenUrl 备用方案可以在不支持对话框操作的客户端中打开目标,但该备用方案无法返回弹出窗口的结果。
Important
具有 window.opener 访问权限的连接窗口可以导航或以其他方式影响聊天页面。 请与你的网络安全团队核对目的地及其重定向。 不要让可信的目的地重定向到不可信的网站,同时保留 opener 访问权限。
如果你嵌入了 Bot Framework Web 聊天,对 Action.OpenUrlDialog 的处理会打开连接窗口。 同源窗口默认被信任。 对于已审核的跨源目标,请将 styleOptions.callURLActionTrustedOrigin 设置为确切的允许源。 用逗号分隔多个起源。 你也可以设置 callURLActionPopupWindowHeight 和 callURLActionPopupWindowWidth。 请勿添加未经审核的源。
连接设置成功后继续(预览)
[此部分是预发布文档,需要更改。]
Important
本文包含 Microsoft Copilot Studio 预览版文档,有可能会有变动。
预览功能不适合生产使用且功能可能受限。 这些功能在正式发布之前可用,以便你可以提前访问并提供 反馈。
如果您在构建可投入生产的代理,请参阅 Microsoft Copilot Studio 概述。
可信连接窗口可以通过 window.opener.postMessage 向聊天页面发送完成结果。 请使用聊天页面的确切源作为目标源,而非 *。
在聊天页面:
如果
window.open返回了null,不要接受该次尝试的消息。 否则,只有当消息的event.source与保留的弹出窗口引用匹配,且event.origin与预期来源匹配时,才接受该消息。验证消息数据是否包含
type: "postback",且其值符合你的代理或运行时预期的格式。以下示例向代理发送带有“hello-world”文本的消息。 在聊天界面里看不到。
{ "type": "postback", "value": { hello: "World!" } }以下示例向代理发送带有 JSON
{ hello: "World!" }的消息。{ "type": "postback", "value": { hello: "World!" } }通过 Bot Framework 的 postback 机制发送已接受的值。 将保留的活动 ID 用作
replyToId;不要接受来自弹窗的回复活动 ID。每个弹窗最多接受一个结果。 在接受结果、拒绝受信任弹窗的错误消息、检测弹窗关闭或达到时间限制后,移除事件监听器并清除其计时器。 Web 聊天 有五分钟限制。
请与智能体或运行时协调,将回传与最初需要连接的交互相关联,并精确地恢复该轮交互一次。
浏览器消息采用尽力而为的方式传递。 弹出窗口拦截器、导航、跨源打开者策略或已关闭的窗口都可能阻止自动继续。 请确保继续或其他恢复路径可用,且不要将消息缺失视为成功。
部署您自定义的画布
若要托管自定义画布,请将所有文件部署到 Web 应用。