Customize Amazon Quick embedded chat into your application

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Quick 임베디드 채팅을 컨테이너 CSS, SDK 옵션, 맞춤 에이전트 페르소나, sendPrompt()로 조정해 금융 대시보드와 시각·언어·상호작용이 일관된 경험으로 통합하는 방법을 설명한다.

📌 핵심 요약

• Amazon Quick 임베디드 채팅의 사용자 지정은 회사 브랜드에 맞춘 시각 테마와 조직의 목소리를 반영하는 대화 톤이라는 두 축으로 구성되며, 금융 성과 대시보드의 금융 분석 도우미가 예시로 사용된다.
• 채팅은 iframe 안에서 렌더링되므로 내부 요소를 직접 스타일링할 수 없으며, 외부 컨테이너 CSS와 SDK의 frameOptions를 함께 사용해 레이아웃·동작·브랜딩을 제어한다.
• className, width, height, 로딩 자리표시자, 클립보드 권한, 푸터 옵션을 설정하고, 400px 측면 패널을 900px 이하 화면에서 100% 너비로 전환해 반응형 시각 통합을 구현한다.
• fixedAgentId, initialPrompt, 파일 첨부, 웹 검색, 채팅 기록, 지식 경계 표시와 에이전트 페르소나 지침을 결합해 일반적인 답변을 직접적이고 데이터 중심이며 조직 맥락을 반영하는 답변으로 바꾼다.
• sendPrompt()는 차트 지표나 매출·이익률·비용 빠른 동작 버튼에서 맥락 질문을 전송해 금융 대시보드의 시각 요소와 대화형 분석을 연결한다.

🧩 주요 포인트

1. iframe 내부 직접 스타일링 불가 → 컨테이너 CSS는 패널 배치와 외형을, frameOptions는 프레임 동작과 브랜딩 요소를 담당하는 이중 구성이 필요하다.
2. fixedAgentId와 에이전트 페르소나 지침 적용 → 일반적이고 광범위한 설명을 조직의 금융 데이터에 한정된 직접적·간결한 답변으로 전환한다.
3. sendPrompt()와 대시보드 UI 연결 → 사용자의 지표 선택을 해당 지표의 추세와 원인을 묻는 맥락 질문으로 이어 준다.

🧠 상세 정리

1. 임베디드 채팅 사용자 지정의 목적

Amazon Quick 임베디드 채팅은 웹 애플리케이션에 직접 통합되어 사용자가 애플리케이션을 떠나지 않고 질문하고, 데이터를 탐색하며, 인사이트를 얻도록 하는 대화형 AI 인터페이스다. 그러나 기본형 채팅은 주변 화면과 색상, 브랜드 표현, 말투가 어긋나 외부 도구를 덧붙인 듯한 단절된 경험을 만들 수 있다. 글은 사용자 지정 요구를 회사 브랜드 지침에 맞추는 시각 테마와 조직의 성격을 반영하는 대화 톤이라는 두 영역으로 나누며, 시각적 일관성만으로는 충분하지 않다고 설명한다. 이를 보여 주기 위해 금융 성과 대시보드 안에 금융 분석 도우미를 넣은 사례를 사용하고, 화면 구성과 답변 방식이 모두 애플리케이션의 일부처럼 느껴지도록 설정하는 과정을 다룬다.

2. iframe 제약과 이중 스타일링 구조

Amazon Quick 채팅을 처음 삽입하면 기본 스타일이 사용되기 때문에 금융 대시보드의 색상 체계, 브랜드 표현, 주변 구성요소와 시각적으로 맞지 않을 수 있다. 시각 테마는 채팅 iframe을 감싸는 컨테이너와 레이아웃을 CSS로 꾸미는 층, 임베딩 SDK에 전달하는 frameOptions로 프레임의 동작과 요소를 제어하는 층으로 나뉜다. 채팅 내부는 iframe 안에서 렌더링되므로 애플리케이션 CSS로 내부 요소를 직접 변경할 수 없고, 대신 바깥 컨테이너와 iframe 요소에 부여한 사용자 지정 클래스를 활용해야 한다. frameOptions에는 임베드 URL, 컨테이너 요소, 100% 높이와 너비, className, 로딩 자리표시자, 클립보드 읽기·쓰기 권한을 지정할 수 있다. 이 구조를 통해 내부 구현을 직접 건드리지 않으면서도 테두리 반경, 위치, 쌓임 순서, 초기 로딩 경험 같은 프레임 수준의 표현을 애플리케이션에 맞출 수 있다.

3. 측면 패널과 반응형 레이아웃 구성

금융 대시보드 사례에서는 채팅 컨테이너를 화면 오른쪽에서 나타나는 고정 측면 패널로 구성한다. .chat-side-panel은 위·오른쪽·아래쪽을 0으로 고정하고 너비를 400px, z-index를 997로 지정하며, 왼쪽 방향 그림자와 0.3초 슬라이드 애니메이션을 적용한다. 패널 헤더에는 #667eea와 #764ba2를 연결한 그라데이션 배경, 흰색 글자, 12px·16px 안쪽 여백을 사용해 대시보드의 브랜드 표현과 맞춘다. frameOptions의 className으로 연결된 .anycompany-chat-iframe에는 아래쪽 모서리의 12px 반경을 적용하고, 화면 너비가 900px 이하이면 패널 너비를 100%로 바꾼다. 이 조합은 데스크톱에서는 오른쪽 보조 패널을 유지하고 모바일에서는 화면 전체 너비를 사용하도록 시각적 배치를 조정한다.

4. 기본 브랜딩 제거와 옵션별 역할

기본 임베디드 채팅의 푸터에는 Amazon Quick 브랜드 표기와 사용 정책 링크가 표시되며, 애플리케이션 고유의 브랜드 경험에서는 이 요소들이 주변 디자인과 충돌할 수 있다. contentOptions.footerOptions에서 showBrandAttribution과 showUsagePolicy를 각각 false로 지정하면 두 요소를 숨길 수 있다. 컨테이너 스타일, 사용자 지정 className, 푸터 브랜딩 제거를 함께 적용한 예시에서는 금융 대시보드와 같은 그라데이션을 사용하고 푸터를 단순화해 전체 디자인 체계와의 일관성을 높인다. 옵션별로 보면 className은 iframe의 테두리 반경·그림자·쌓임 순서를, width와 height는 크기를, withIframePlaceholder는 로딩 중 표시를 담당한다. 컨테이너 CSS는 패널 위치·테두리·그림자·헤더 스타일을 맡고, 푸터 옵션은 기본 브랜드 표기와 정책 링크의 노출 여부를 제어한다.

5. 일반 답변과 맞춤 금융 에이전트의 차이

시각 테마를 맞추더라도 채팅의 의사소통 방식이 조직의 말투와 전문 영역을 반영하지 못하면 통합된 경험이 완성되지 않는다. 맞춤 채팅 에이전트가 없는 상태에서 지난 분기 매출을 질문한 예시는 매출의 일반적 정의를 설명하고 재무제표나 회계 시스템을 확인하라고 안내할 뿐, 해당 조직의 구체적인 금융 맥락을 제시하지 못한다. Amazon Quick 맞춤 채팅 에이전트는 SDK 콘텐츠 옵션과 Quick 콘솔의 에이전트 페르소나 지침을 통해 톤, 언어 스타일, 답변 행동, 지식 범위를 설정한다. SDK 콘텐츠 옵션은 사용자에게 보이는 UI 요소와 사용할 에이전트를 정하고, 페르소나 지침은 에이전트의 성격과 응답 구조 및 허용 범위를 정의한다. 따라서 화면의 외형뿐 아니라 질문에 답하는 방식까지 금융팀과 경영진이 사용하는 커뮤니케이션 방식에 맞출 수 있다.

6. SDK 콘텐츠 옵션과 대화 시작 방식

agentOptions.fixedAgentId를 금융 전용 에이전트 ID로 설정하면 일반 에이전트 선택기를 제거하고 사용자가 목적에 맞게 구성된 에이전트와만 상호작용하도록 고정할 수 있다. initialPrompt에는 이번 분기의 핵심 금융 하이라이트를 묻는 질문을 넣어 첫 로드 시 자동 전송하고, showInitialPromptMessage: false를 사용해 사용자 질문 말풍선을 숨길 수 있다. 이 설정은 사용자가 먼저 질문한 모습 대신 도우미가 관련 인사이트를 선제적으로 제시하는 조언자 형태의 대화 시작을 만든다. allowFileAttachments는 스프레드시트나 보고서 첨부를, showWebSearch는 보충 시장 조사를 위한 웹 검색 표시를, showChatHistory는 이전 대화 재개를 지원한다. showAgentKnowledgeBoundary는 에이전트가 접근할 수 있는 데이터 범위를 표시해 사용자가 답변의 지식 경계를 확인하도록 한다.

7. 페르소나 지침과 데이터 중심 답변

Quick 콘솔의 Chat Agents 페이지에서 설정하는 예시 페르소나는 에이전트를 AnyCompany Finance Assistant로 정의하고, 경영진·금융팀·사업 책임자가 대시보드를 떠나지 않고 금융 데이터와 성과 추세를 탐색하도록 역할을 제한한다. 답변 지침은 직접적인 답과 핵심 수치를 먼저 제시하고, 이전 기간과의 비교를 제공하며, 정성적 정보를 인용할 때 출처 문서를 밝히고, 여러 항목은 글머리표로 간결하게 구성하도록 요구한다. 경계 조건으로는 AnyCompany의 금융 데이터와 사업 맥락만 논의하고, 명시된 목표를 넘어 미래 성과를 추측하지 않으며, 지식 범위를 벗어난 질문은 [email protected]으로 안내하도록 정한다. 같은 지난 분기 매출 질문에 대한 맞춤 답변 예시는 Q2 2025 매출을 $8.89M, Q2 2024의 $7.05M 대비 12.5% 증가로 제시하고 4월 $2.89M, 5월 $2.95M, 6월 $3.05M을 나열한다. 또한 북미 성장률 15%와 EMEA 성장률 9%를 제시해 일반적인 매출 설명 대신 수치·기간 비교·지역별 맥락이 포함된 답변 형식을 보여 준다.

8. sendPrompt()를 통한 UI 연동

SDK의 sendPrompt() 메서드를 사용하면 애플리케이션의 UI 상호작용에서 맥락에 맞는 질문을 채팅으로 직접 전송할 수 있다. 먼저 embeddingContext.embedQuickChat(frameOptions, contentOptions)의 결과를 chatExperience로 보관하고, 사용자가 매출 지표 카드를 선택하면 이번 분기 매출 추세와 그 원인을 설명하라는 질문을 chatExperience.sendPrompt()에 전달한다. 금융 대시보드 예시는 채팅 패널 헤더에 Revenue, Margins, Expenses 빠른 동작 버튼을 만들고 각각 매출, 이익률, 비용 지표와 연결한다. 버튼을 누르면 선택한 지표의 추세와 원인을 설명하라는 동일한 형식의 질문이 생성되며, 각 버튼에는 해당 지표를 묻는다는 의미의 aria-label도 지정된다. 이 방식은 차트나 지표 카드에서 발생한 사용자의 선택을 대화형 분석 요청으로 이어 주어 대시보드 시각 요소와 채팅 인터페이스를 연결한다.

🧾 핵심 주장 / 시사점

• Amazon Quick의 브랜드 통합은 색상과 배치만 맞추는 작업이 아니라 답변의 어휘·구조·지식 경계까지 조직의 커뮤니케이션 방식에 맞추는 구성이다.
• iframe이라는 기술적 경계 때문에 스타일 책임이 컨테이너 CSS와 SDK 옵션으로 분리되며, 각 층이 제어할 수 있는 범위를 구분해야 한다.
• initialPrompt와 sendPrompt()는 채팅을 독립된 질문창으로 두지 않고 대시보드의 초기 맥락과 사용자의 지표 선택에 반응하는 인터페이스로 연결한다.

✅ 액션 아이템

• Amazon Quick 채팅에 컨테이너 CSS와 frameOptions를 함께 적용해 금융 대시보드와 iframe의 시각·동작 일관성 확보.
• fixedAgentId와 에이전트 페르소나 지침을 결합해 답변을 조직의 금융 데이터에 한정된 직접적·간결한 형식으로 전환.
• sendPrompt()를 매출·이익률·비용 빠른 동작 버튼과 연결해 UI 선택에 따른 맥락 질문 전송.

❓ 열린 질문

• Amazon Quick의 iframe 제약에서 컨테이너 CSS와 frameOptions는 각각 어떤 시각·동작 범위를 담당하는가?
• fixedAgentId와 에이전트 페르소나 지침은 일반적인 답변을 직접적이고 데이터 중심인 금융 답변으로 어떻게 바꾸는가?
• sendPrompt()를 금융 대시보드의 매출·이익률·비용 UI 선택과 연결하면 어떤 맥락 질문이 전송되는가?