Touchpoint is a drop-in conversational UI and SDK for Amazon Connect Customer — a single widget for chat, voice, and voice-mini, plus Live Sync, the native technology that keeps a voice or chat conversation in sync with your on-screen interface.
npm i @amazon-connect-touchpoint/webTo run Touchpoint you need an Amazon Connect Customer instance with a contact
flow, plus a browser-facing endpoint that mints the contact credentials. Gather
the following before you call create():
| What you need | Where it comes from |
|---|---|
| StartChatContact endpoint (chat) | An API Gateway/Lambda route that calls Amazon Connect's StartChatContact and returns participant credentials. Deploy the StartChatContact API. Required for input: "text". Passed as config.chatEndpoint. |
| StartWebRTCContact endpoint (voice) | An endpoint that calls StartWebRTCContact and returns the Chime connection data. Deploy the StartWebRTCContact sample. Required for input: "voice" and input: "voiceMini". Passed as config.voiceEndpoint. |
| Instance ID | The Amazon Connect Customer instance (UUID) the contact is created in. config.instanceId. |
| Contact Flow ID | The contact flow (UUID) that handles the contact. config.contactFlowId. |
| Region | AWS region of your instance, e.g. us-west-2. config.region. |
That's everything you need for chat and voice. Live Sync is optional — it additionally requires an Agentic CX designer (ACXD) application; see below.
- Create a contact flow in your Amazon Connect Customer instance that handles the contact; note the instance ID and contact flow ID.
- Stand up the browser endpoints so the page can create a contact — the StartChatContact (chat) and StartWebRTCContact (voice) endpoints above.
Live Sync keeps the conversation in sync with your on-screen interface. It's the only feature that requires ACXD; plain chat and voice work without it. To enable it:
-
Build the ACXD application. In the ACXD Canvas, wire
Start→ a Live Sync node →Exit application. On the Live Sync node, declare the actions and scopes the assistant may use (or define them on the fly with this SDK for rapid prototyping — see Live Sync below).
-
Publish it and copy your keys. Deploy the application, then copy the deployment key and API key from its settings.
-
Route your contact flow into it so contacts reach the ACXD application, and pass the keys as
liveSync.deploymentKey/liveSync.apiKey.
The interactive playground lets you plug these values into a form and launch a live instance without writing any code.
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",
contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
region: "us-east-1",
},
input: "text",
});A compact, floating voice widget. Voice modes connect through your
StartWebRTCContact endpoint. On mobile it stacks vertically, and a drag handle
lets the customer move it out of the way of the page.
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 controls how the expanded experience is presented (applies to chat
and full-screen voice; voiceMini is always a compact floating widget):
half(default) — overlay with the panel on the right and the rest of the page dimmed.full— overlay covering the whole viewport.floating— a detached, rounded panel that hovers over the page without dimming it, so the site stays visible and interactive.side-by-side— a panel docked to the right edge for the full height; on wider viewports the page is narrowed by the panel's width so nothing is hidden behind it and both can be used at once.
floating and side-by-side are ideal for chatting while browsing — the way
voice conversations already run alongside the page.
const touchpoint = await create({
config: {
/* … */
},
input: "text",
windowSize: "side-by-side",
});Pass a partial theme to match your brand. The accent color drives prominent
elements — the send button, loader, selected states, and the voice
audio-signaling ripple — and defaults to black/white so setting a brand accent is
immediately visible. A contrasting foreground on the accent (e.g. the send arrow)
is derived automatically.
const touchpoint = await create({
config: {
/* … */
},
theme: {
accent: "#22c55e",
// Optional overrides: primary, secondary, background, fontFamily, …
},
});For text conversations, the opening assistant message is presented as an immersive welcome screen: the greeting (and any choices) is centered vertically, and the connecting/thinking state is centered where the message will appear. The input stays hidden until the first message arrives; if the message has choices, the input is pulled up beneath the greeting with the choices below. It persists until the customer sends or selects something, then the conversation continues as a normal transcript. If the first message carries modalities or a guide, the normal transcript is used instead.
It's enabled by default. Set welcomeScreen: false to render a top-anchored
transcript from the first message. When a brandIcon is set, it appears at the
top of the welcome screen; set welcomeScreenLogo: false to hide it.
const touchpoint = await create({
config: {
/* … */
},
input: "text",
welcomeScreen: false, // opt out of the immersive welcome screen
});When participant info is shown (showParticipantInfo: true), the automated
assistant is labeled "AI" with a default icon. Override both to match your
brand with assistantName (the displayed name) and assistantIcon (an image URL
used as the assistant's avatar). avatarShape controls whether participant
avatars are "round" (default) or "square".
const touchpoint = await create({
config: {
/* … */
},
input: "text",
showParticipantInfo: true,
assistantName: "Ada",
assistantIcon: "https://example.com/assistant.png",
avatarShape: "square",
});Live Sync is native Amazon Connect Customer technology that synchronizes a voice (or chat) conversation with a digital, on-screen interface. Customers see options, next steps, and confirmations in real time while an AI agent guides them — no app, no channel switch — unlocking complex, multi-step tasks that voice or chat alone can't handle, where customers need to see, choose, and complete actions in a single continuous conversation.
In Touchpoint, the AI agent drives the page through custom actions: you register a named action with a JSON Schema, the agent resolves what the customer said into typed arguments, and your handler applies them to the page.
import { create } from "@amazon-connect-touchpoint/web";
const touchpoint = await create({
config: {
chatEndpoint: "REPLACE_WITH_START_CHAT_ENDPOINT",
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),
},
],
});Actions can also be configured in
Agentic CX designer (ACXD)
on the Live Sync node; defining them here is useful for rapid prototyping. To
notify a Live Sync script that the user reached a step, call
touchpoint.sendStep({ stepId, scriptId, apiKey, context }).
Use input: "external" to run Touchpoint with no rendered UI. It opens no
chat or voice contact of its own — it only connects Live Sync to an existing
live contact (identified by liveSync.contactId) so that contact can drive your
digital asset in real time. A common case is a phone call: the caller talks
to the agent while the page updates alongside them. No chatEndpoint or
voiceEndpoint is needed; only the Live Sync credentials.
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: [/* … */] });Touchpoint also registers a <connect-touchpoint> custom element. Set its
writeable touchpointConfiguration property to the same object you would pass to
create() and it starts in embedded mode: no launch button,
and the UI fills the container you place it in, so it drops into an existing page
layout.
<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",
instanceId: "REPLACE_WITH_INSTANCE_ID",
contactFlowId: "REPLACE_WITH_CONTACT_FLOW_ID",
region: "us-east-1",
},
input: "text",
};
</script>The element sizes itself with low-specificity defaults — display: block; height: 350px for text and voice, display: inline-block for voiceMini —
which you can override to fit your layout:
connect-touchpoint {
height: 100%;
}When the underlying Amazon Connect contact ends — the voice call is disconnected
(including after an escalated agent resolves and hangs up) or the chat contact is
closed — Touchpoint fires onContactEnded. For voice inputs the default action
collapses the widget back to the launcher; chat keeps the ended transcript
visible. The event is cancelable, so you can take over:
const touchpoint = await create({
config: {
/* … */
},
input: "voice",
onContactEnded: (event) => {
// Keep the widget open and handle the end yourself:
// event.preventDefault();
console.log("contact ended");
},
});Running the project locally launches an interactive playground covering every capability (chat, voice, voice-mini, and Live Sync):
npm install
npm run dev
# then open http://localhost:5173The full SDK specification — every configuration option, type, and modality
component — is generated from source and lives under
docs/.
Common entry points:
create(config)— create and mount a Touchpoint instance.TouchpointConfiguration— top-level options (config,input,colorMode,windowSize,theme,liveSync,brandIcon,onContactEnded,welcomeScreen,welcomeScreenLogo,showParticipantInfo,assistantName,assistantIcon,avatarShape, …).ConnectConfig— Amazon Connect Customer connection details.LiveSyncConnection/LiveSyncContextInput— Live Sync connection and the actions / scopes / destinations you advertise to the AI agent.