触点

触点是亚马逊连通客户端的即时对话UI和SDK——a 用于聊天、语音和语音-mini,加 现场同步,则 保持语音或聊天对话与您同步的本地技术 屏幕界面.

npm i @amazon-connect-touchpoint/web

先决条件

要运行触点, 您需要使用 Amazon 连接客户 实例 与联系 流程,加上一个浏览器-显示端点来薄荷联系人证书。 聚集起来 在您拨打电话之前,以下 create()数字 :

这就是你需要的 聊天和语音. 现场同步是可选的 - 这个 还需要一个代理CX设计器(ACXD)应用程序;见下文.

建立亚马逊连接客户端

1. 创建联系人流程 在您的亚马逊连接客户实例中 处理联系人; 注意 实例标识 财务报告和审定财务报表 联系流程 ID。 。 。 .
2. 站起浏览器端点 因此,页面可以创建一个联系人—— 启动聊天联系 (聊天)和 开始WebRTC 联系 以上(声)端.

添加 Live 同步( 可选)

Live Sync使对话与屏幕界面同步. 这是 只有需要 ACXD 的特性;没有它便可以进行简单的聊天和语音工作。 启用 内容:

1. 构建ACXD应用程序. 在ACXD Canvas, 有线 Start − a 个 现场同步 节点 Exit application。在现场同步节点上,宣布 助手可以使用的动作和范围(或用此定义在苍蝇上) 用于快速原型的SDK——见 现场同步 页:1.

   

2. 出版并复制您的密钥. 部署应用程序,然后复制 部署密钥 财务报告和审定财务报表 API 密钥 从它的设置.

3. 联系方式进入其中 因此联系人到达ACXD应用程序, 并传递密钥为 liveSync.deploymentKey 编号 : liveSync.apiKey。 。 。 .

这个 互动操场 让您插入这些值 进入一个形式,并启动一个现场实例 不写任何代码.

实例

聊天

import { create } from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: {
    // Your StartChatContact endpoint (e.g. an API Gateway route) that mints a
    // participant token.
    chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT",
    instanceId: "REPLACE_WITH_INSTANCE_ID",
    participantDisplayName: "REPLACE_WITH_PARTICIPANT_DISPLAY_NAME",
    contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
    region: "us-east-1",
  },
  input: "text",
});

自定义聊天客户端( 高级)

默认情况下, Touchpoint 直接与 Amazon 连接参与者服务交谈 从使用参与者符号的浏览器中获取。 路由每个参与者服务 使用自己的后端调用(所以符号从未到达浏览器), 扩展 ChatClient 并通过一个实例作为 customChatClient。 。 。 . ChatClient 实值 从 amazon 连接聊天室· ; 参见其执行方法的文件.

import { create, ChatClient } from "@amazon-connect-touchpoint/web";

class MyChatClient extends ChatClient {
  createParticipantConnection(participantToken, type, acknowledgeConnection) {
    /* TODO: call your backend */
  }
  disconnectParticipant(connectionToken) {
    /* TODO: disconnect participant */
  }
  sendMessage(connectionToken, content, contentType, clientToken) {
    /* TODO: send message */
  }
  sendEvent(connectionToken, contentType, content, clientToken) {
    /* TODO: send event */
  }
  getTranscript(connectionToken, args) {
    /* TODO: get transcript */
  }
  // Other optional properties
}

const touchpoint = await create({
  config: {
    customChatClient: new MyChatClient(),
    chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT", // The chat endpoint does not need to return a `participantToken`
    instanceId: "REPLACE_WITH_INSTANCE_ID",
    participantDisplayName: "REPLACE_WITH_PARTICIPANT_DISPLAY_NAME",
    contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
    region: "us-east-1",
  },
  input: "text",
});

否时 customChatClient 提供聊天细节时没有 participantToken警告记录在控制台上.

语音迷你

一个紧凑而活泼的声音部件。 语音模式通过您的 StartWebRTCContact 终点 在移动时, 它垂直堆放, 一个拖动柄 让客户把它移出页面.

import { create } from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: {
    voiceEndpoint: "REPLACE_WITH_START_WEBRTC_ENDPOINT",
    instanceId: "REPLACE_WITH_INSTANCE_ID",
    contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
    region: "us-east-1",
  },
  input: "voiceMini", // or "voice" for the full-screen experience
});

布局

windowSize 控制如何显示扩展的经验(适用于聊天) 和全屏声音; voiceMini 总是紧凑的浮动部件 :

• half (默认) 右侧和其余部分与小组重叠 页面已淡出.
• full ——覆盖整个景区.
• floating ——一个被剥离的圆形面板,在页面上徘徊而无 淡化它,所以网站保持可见性和互动性.
• side-by-side ——一面板对接右边缘进行全高;更宽 取景口 页面被面板宽度所收缩,所以没有隐藏 它可以同时使用.

floating 财务报告和审定财务报表 side-by-side 用于浏览时聊天的理想方式——方式 语音对话已经在页面旁边运行 .

const touchpoint = await create({
  config: {/* … */},
  input: "text",
  windowSize: "side-by-side",
});

他们

传递部分 theme 来配合你的品牌。 这个 口音 颜色驱动器突出 元素 — 发送按钮、 加载器、 选定状态和语音 音频信号波纹 和默认为黑/白 所以设置一个品牌口音是 立即可见 口音上的对比前景( 如发出箭头) 自动生成.

const touchpoint = await create({
  config: {/* … */},
  theme: {
    accent: "#22c55e",
    // Optional overrides: primary, secondary, background, fontFamily, …
  },
});

容器样式

将扩大的面板置于或大小与 windowSize 预设 允许,通过 containerStyle触点使一个封闭的阴影根内,所以 在主机页面上写入的 CSS 无法到达它—— 样式对象是支持的方式 ,并应用在预设自身样式上.

它只适用于整个谈话容器——扩大的聊天和 全屏语音体验. 发射图标和 voiceMini 部件是 定位为自身紧凑的浮动元素,不受影响.

const touchpoint = await create({
  config: {/* … */},
  windowSize: "floating",
  containerStyle: {
    borderLeft: "1px solid #efefef",
  },
});

配置可按 JSON 提供 configuration 属性 <connect-touchpoint> 元素,所以它不被认为可信: 容器级别属性(位置、大小、间隔、边框、阴影、变换、, ) 被接受,以及负载远程资源的值(.)url(), (中文(简体) ), image-set(), (中文(简体) ), element())或试图偷运额外申报,用控制台投放 警告 警告他们 使用 theme 以重排容器内的内容.

消息发泡

转写信息可以作为气泡,独立地为每一边提供: userMessageBubble 给客户留言和 agentMessageBubble 联 合 国 帮办的 随着气泡的关闭,信息 变成简单的文本 背景.

然后每个气泡都可以用 userMessageBubbleStyle 编号 : agentMessageBubbleStyle。这些仅在匹配时应用 *MessageBubble 启用了旗帜——一个样式对象自己不会转弯 泡泡开来.

const touchpoint = await create({
  config: {/* … */},
  input: "text",
  userMessageBubble: true,
  agentMessageBubble: true,
  userMessageBubbleStyle: {
    backgroundColor: "#e8f0fe",
    color: "#102a43",
    borderRadius: "20px",
  },
  agentMessageBubbleStyle: {
    backgroundColor: "#f3f3f3",
    color: "#102a43",
    borderRadius: "20px",
  },
});

气泡样式使用与 containerStyle (共享资源) CustomStyle 类型,包括文本 color: 仅限 所支持的属性被保存,任何包含 url(), (中文(简体) ), image-set(), (中文(简体) ), element(),评论,或附加声明 控制台警告,因为配置可能以无人信任的JSON方式到达 configuration 属性 <connect-touchpoint> 键.

图标

每个内置图标都可以被替换为 icons 选项。 钥匙是名字 触点导出为 Icons (例如:. Close, (中文(简体) ), Send, (中文(简体) ), Mic, (中文(简体) ), Restart; 值是反应组件。 你离开的图标 保持他们的默认, 并覆盖到任何地方 触点使图标。 可能是这样 后来更改为 touchpoint.update({ icons })。 。 。 .

制作图标的最简单方式是 createIcon,则使用 SVG 内容 :

import { create, createIcon, html } from "@amazon-connect-touchpoint/web";

// Create icons once, outside of any render, so their identity stays stable.
const Send = createIcon(html`<path d="M3 20L21 12L3 4V10L15 12L3 14V20Z" />`);

const touchpoint = await create({
  config: {/* … */},
  icons: { Send },
});

createIcon 处理内置图标所依赖的细节,所以您只使用 SVG 需要形状 :

• 24×24集装箱. SVG是用 viewBox="0 0 24 24"绘制 您的路径在 24x24 网格。 通过第二个论点来改变它,例如. createIcon(children, { viewBox: "0 0 16 16" })。 。 。 .
• currentColor。 。 。 . 形状充满 currentColor 默认,所以 图标来取取它所在的按钮或标签的文本颜色,包括 徘徊和残疾状态。 避免路径中的硬编码颜色 。 对于 基于中风的艺术作品, 设定 fill: "none" 财务报告和审定财务报表 stroke: "currentColor" 输入 第二个论点: createIcon(<path d="…" />, { fill: "none", stroke: "currentColor", strokeWidth: 2 })。 。 。 .
• 大小和 className。 。 。 . 这个 size (以像素计)和 className 道具是: 道具是: 适用于 <svg> 给你的 没有 size 图标填入容器.
• 无障碍. 图标从辅助技术中隐藏 可访问名称总是来自周围的按钮或文本.

您也可以通过任何接受的 React 组件 size 财务报告和审定财务报表 className 相反,比如说,它使一个图标从你自己的设计系统中产生。 没错 然后负责这些道具,以及使用 currentColor 如果它应该 遵循周围的文字颜色.

欢迎屏幕

对于文字对话,开口助理信息作为 浸润 欢迎屏幕: 问候(和任何选择)是中心 垂直, 连接/ 思考状态以信件所在位置为中心 出现。 输入会一直隐藏到第一个消息到达; 如果信件 有选择, 输入被拉起 在问候下面 有选择下面. 它一直持续到客户发送或选择的东西,然后对话 继续作为正常记录。 如果第一个信息包含模式或 向导,则使用普通记录.

默认启用. 设定 welcomeScreen: false 来制造一个头痛 从第一个消息。 当a brandIcon 设定, 它出现在 欢迎屏幕上方; 设置 welcomeScreenLogo: false 藏起来.

const touchpoint = await create({
  config: {/* … */},
  input: "text",
  welcomeScreen: false, // opt out of the immersive welcome screen
});

隐藏和添加元素

内建的UI可以调取两个元素标识符列表. 使用导出 enums,或无类型环境中的平面字符串.

hiddenElements 省去默认元素 :

addedElements 选择默认关闭的元素 :

import {
  create,
  HiddenElement,
  AddedElement,
} from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: {/* … */},
  input: "text",
  hiddenElements: [HiddenElement.HeaderRestart],
  addedElements: [AddedElement.HeaderClose], // or ["header.close"]
});

未知值被忽略 。 两种列表可以稍后更改 update()。 。 。 . welcomeScreenLogo: false 为了躲藏而堕落 HiddenElement.WelcomeScreenLogo。 。 。 .

助理身份

显示参与者信息时(showParticipantInfo: true),自动 助手被标签 "AI" (英语) 带有默认图标。 覆盖两者以匹配您的 品牌为 assistantName (显示名称)和 assistantIcon (图像 URL) )作为助手的外形. avatarShape 控制参与者是否 阿凡达人 "round" (违约)或 "square"。 。 。 .

const touchpoint = await create({
  config: {/* … */},
  input: "text",
  showParticipantInfo: true,
  assistantName: "Ada",
  assistantIcon: "https://example.com/assistant.png",
  avatarShape: "square",
});

现场同步

Live Sync是本地的亚马逊连接客户端技术同步 与数字、屏幕接口进行语音(或聊天)对话。 顾客看 选项、下一步和实时确认,同时由AI代理指导 ——没有应用,没有频道开关——解锁语音或语音的复杂多步任务 单独聊天不能处理 顾客需要看到 选择 完成行动 在一次持续的对话.

在触点,AI代理驱动页面通过 自定义动作: 您 : 在 JSON Schema 中注册一个命名动作, 代理解决客户 输入输入的参数,您的处理器将其应用到页面中.

import { create } from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: {
    chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT",
    participantDisplayName: "REPLACE_WITH_PARTICIPANT_DISPLAY_NAME",
    instanceId: "REPLACE_WITH_INSTANCE_ID",
    contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
    region: "us-east-1",
  },
  input: "voiceMini",
  liveSync: {
    deploymentKey: "REPLACE_WITH_DEPLOYMENT_KEY",
    apiKey: "REPLACE_WITH_API_KEY",
    // `contactId` is optional — defaults to the active session's contact. Set it
    // to bind a separate contact (e.g. an inbound phone call) to this page.
  },
});

// Advertise the actions the AI agent may take (sent once a contact exists):
await touchpoint.sendContext({
  actions: [
    {
      action: "set_cabin_class",
      description: "Choose the cabin class",
      schema: {
        type: "object",
        properties: {
          cabin: { type: "string", enum: ["economy", "business", "first"] },
        },
        required: ["cabin"],
      },
      handler: ({ cabin }) => setCabinClass(cabin),
    },
  ],
});

动作也可以配置在 代理 CX 设计器( ACXD) 在 Live Sync 节点上; 在此定义它们对于快速原型化有用 。 改为: 通知 Live 同步脚本, 用户到达一步, 呼叫 touchpoint.sendStep({ stepId, scriptId, apiKey, context })。 。 。 .

外部( 无用户界面)

使用 input: "external" 切入点 没有实现 UI打开 聊天或语音联系——它只连接 Live Sync 到已有的 现场接触(由 liveSync.contactId这样联系人就可以驱动您 数字资产实时. 常见情况是 电话:呼叫者说话 在页面同时更新时插入代理服务器。 没有 chatEndpoint 或者说 voiceEndpoint 需要; 只有 Live Sync 证书.

import { create } from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: { region: "us-east-1" },
  input: "external",
  liveSync: {
    deploymentKey: "REPLACE_WITH_DEPLOYMENT_KEY",
    apiKey: "REPLACE_WITH_API_KEY",
    contactId: "REPLACE_WITH_CONTACT_ID", // the contact to sync with
  },
});

// Advertise your actions, then drive the page as the agent invokes them.
await touchpoint.sendContext({ actions: [/* … */] });

自定义模式

除正则模式外,还可以在代码片段中直接定义完全自定义模式为React组件. 如果应用程序消息包含这种模式,则组件会用有效载荷数据以及使与对话互动变得容易的对话处理器来提供.

为了使编写这些反应组件变得简单,并消除汇编JSX的需要,软件包输出为: html 标记模板文字 a'la 开发/htm。 。 。 . html 还预装了一系列组件和图标 触点已经用于渲染它的UI,这样你就可以轻松地创建并作好与"触点"在风格上相匹配的标记. 完整列表可见于 导出定义,而一个更视觉的指南 将很快提供.

下面是一个完整的例子:

import { create, html } from "@amazon-connect-touchpoint/web";

const touchpoint = await create({
  config: {
    // Your StartChatContact endpoint (e.g. an API Gateway route) that mints a
    // participant token.
    chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT",
    participantDisplayName: "REPLACE_WITH_PARTICIPANT_DISPLAY_NAME",
    instanceId: "REPLACE_WITH_INSTANCE_ID",
    contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
    region: "us-east-1",
  },
  input: "text",
  modalityComponents: {
    MyModality: ({ data, conversationHandler }) => {
      return html`
        <div>
          <p>Are you sure?</p>
          <IconButton
            type="main"
            label="Yes"
            onClick=${() => {
              conversationHandler.sendText("yes");
            }}
            icon="{Check}"
          />
          <IconButton
            type="ghost"
            label="No"
            onClick=${() => {
              conversationHandler.sendText("no");
            }}
            icon="{Close}"
          />
        </div>
      `;
    },
  },
});

嵌入模式( 高级)

触点还登记a <connect-touchpoint> 自定义元素。 设定其 可写入 touchpointConfiguration 属性到您将传递给的同一对象 create() 开始于 嵌入模式没有发射按钮, 并 UI 填入您放入的容器, 因此它会掉入已有的页面 设置.

<div class="my-grid-layout">
  <main>
    <!-- Main page content -->
  </main>
  <aside>
    <connect-touchpoint></connect-touchpoint>
  </aside>
</div>
<script>
  document.querySelector("connect-touchpoint").touchpointConfiguration = {
    config: {
      // Your StartChatContact endpoint (e.g. an API Gateway route) that mints a
      // participant token.
      chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT",
      participantDisplayName: "REPLACE_WITH_PARTICIPANT_DISPLAY_NAME",
      instanceId: "REPLACE_WITH_INSTANCE_ID",
      contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
      region: "us-east-1",
    },
    input: "text",
  };
</script>

元素大小本身带有低特异性默认—— display: block; height: 350px 页:1 text 财务报告和审定财务报表 voice, (中文(简体) ), display: inline-block 页:1 voiceMini —— 说 以适应您的布局 :

connect-touchpoint {
  height: 100%;
}

结束联系

当基本的亚马逊连接连接结束时——语音呼叫断开 (包括在升级的代理解决并挂起之后)或聊天联系人是 关闭——触点起火 onContactEnded。对于语音输入,默认动作 将部件折叠回发射台; 聊天保存结束的记录 可见。 此事件可取消, 您可以接管 :

const touchpoint = await create({
  config: {/* … */},
  input: "voice",
  onContactEnded: (event) => {
    // Keep the widget open and handle the end yourself:
    // event.preventDefault();
    console.log("contact ended");
  },
});

互动操场

本地运行项目启动一个互动游乐场,涵盖每个 能力(聊天、语音、语音小声和现场同步):

npm install
npm run dev
# then open http://localhost:5173

API 参考

SDK的全部规格——每个配置选项、类型和模式 构成部分——来源和生活 docs/。 。 。 .

共同切入点:

• create(config) 创建并挂起触点实例.
• TouchpointConfiguration ——顶级选项(config, (中文(简体) ), input, (中文(简体) ), colorMode, (中文(简体) ), windowSize, (中文(简体) ), theme, (中文(简体) ), containerStyle, (中文(简体) ), liveSync, (中文(简体) ), brandIcon, (中文(简体) ), onContactEnded, (中文(简体) ), userMessageBubble, (中文(简体) ), agentMessageBubble, (中文(简体) ), userMessageBubbleStyle, (中文(简体) ), agentMessageBubbleStyle, (中文(简体) ), welcomeScreen, (中文(简体) ), welcomeScreenLogo, (中文(简体) ), hiddenElements, (中文(简体) ), addedElements, (中文(简体) ), showParticipantInfo, (中文(简体) ), assistantName, (中文(简体) ), assistantIcon, (中文(简体) ), avatarShape, (中文(简体) ), icons(中文(简体) ).
• ConnectConfig ——亚马逊连接客户端连接细节.
• LiveSyncConnection 编号 : LiveSyncContextInput ——现场同步连接和 动作 / 范围 / 目的地 , 您向 AI 代理公司 发布广告 .

许可证

麻省理工学院