Customize Amazon Quick embedded chat into your application

Amazon Quick embedded chat provides a conversational AI interface that you can integrate directly into your web application. Your users can ask questions, explore data, and get insights without leaving your application. However, a generic chat interface creates a disjointed experience. The chat interface must look and feel like a natural part of your application, not an external addition. With Quick customization capabilities, you can extend your organization’s visual theming and brand voice to match your application’s look and feel, providing a consistent and branded experience.

In this post, we walk through the configuration options for customizing Quick embedded chat to deliver a consistent, branded experience within your application.

Overview

Customization requirements typically fall into two key areas. The first is visual theming to match the company’s brand. Your organization has established brand guidelines, and the embedded chat must reflect these guidelines. The second is tone to match the company’s voice because visual consistency alone isn’t enough. The way the chat communicates must also reflect your organization’s personality.

The following example uses a financial analysis assistant embedded in a finance performance dashboard to demonstrate how to configure visual theming and tone customization.

Figure 1: Financial analysts dashboard with embedded Quick chat

Configure visual theming

When you first embed the Quick chat into your application, the chat interface uses its default styling. This creates a visual mismatch. The chat looks like an external tool bolted onto your application rather than a native component. Notice the mismatched color palette, generic branding, and lack of visual integration with the surrounding finance dashboard.

Apply visual theming so the embedded chat feels like a natural part of the finance dashboard. Embedded chat visual theming operates at two levels. The first is container and layout styling, which is the CSS you control around the chat iframe. The second is SDK frame options, which is the configuration passed to the embedding SDK that controls the iframe behavior and branding elements.

Because the chat renders inside an iframe, you can’t style its internal elements directly. Instead, you style the container that wraps the iframe and use SDK options to remove default branding elements that conflict with your design.

Frame options configuration

The frameOptions parameter controls how the iframe behaves within your container:

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk'; const embeddingContext = await createEmbeddingContext();

const frameOptions = { url: chatEmbedUrl, container: document.getElementById('chat-container'), height: '100%', width: '100%', // Apply a custom CSS class directly to the iframe element. // Use this for border-radius, positioning, or z-index adjustments // to match your application's component design. className: 'anycompany-chat-iframe', // Display a loading placeholder while the chat content loads, // preventing a blank white rectangle during initialization. withIframePlaceholder: true, // Enable clipboard access so users can copy responses // or paste content into the chat input. framePermissions: { clipboardRead: true, clipboardWrite: true, }, };

Container and layout CSS

Style the container that wraps the chat to match your application’s design system. In our finance dashboard example, the chat appears as a side panel that slides in from the right.

/* Position the chat as a fixed side panel */ .chat-side-panel { position: fixed; top: 0; right: 0; bottom: 0; width: 400px; z-index: 997; box-shadow: -4px 0 20px rgba(0, 0, 0, 0.15); animation: slideInRight 0.3s ease-out; }

/* Brand-colored header matching the dashboard's gradient */ .chat-panel-header { background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 12px 16px; }

/* Target the iframe via the custom className from frameOptions */ .anycompany-chat-iframe { border-radius: 0 0 12px 12px; }

/* Responsive: full-width on mobile */ @media (max-width: 900px) { .chat-side-panel { width: 100%; } }

Remove default branding

By default, the embedded chat displays an Amazon Quick brand attribution and a usage policy link in the footer. For a brand theme experience where the chat appears as a native part of your application, remove these elements:

const contentOptions = { footerOptions: { showBrandAttribution: false, showUsagePolicy: false, }, };

After applying the container styling, custom CSS class, and branding removal, the embedded chat now looks like a natural extension of the finance dashboard. The panel uses the same color gradient, the footer is clean, and the overall appearance is consistent with the application’s design system.

Figure 2: Financial analysts dashboard with visually matching embedded Quick chat

The following table provides a reference for the visual theming options and what each one controls.

Option What it controls

className CSS class on the iframe (border-radius, shadows, z-index)

width / height Iframe dimensions (use “100%” for responsive layouts)

withIframePlaceholder Loading spinner while content loads

footerOptions.showBrandAttribution Show or hide the “Powered by” text

footerOptions.showUsagePolicy Show or hide the usage policy link

Container CSS Panel positioning, borders, shadows, header styling

Configure chat persona and tone

In addition to visual theming, the chat’s communication style must reflect your organization’s personality. Without persona configuration, the embedded chat responds with generic, broad answers that don’t match your company’s communication style or domain expertise.

Figure 3: Financial analysts dashboard with embedded Quick chat showing a chat response

Without a custom chat agent, responses lack organizational context. For example, in the finance dashboard, the question “What was our revenue last quarter?” produces a response like the following:

“Revenue is a measure of income generated from business operations. To find your company’s revenue for last quarter, you would typically look at your financial statements or accounting system. Revenue can be broken down by product line, region, or time period.”

This response lacks specific context about your organization and uses a tone that doesn’t match how your finance team communicates. With the Quick custom chat agent, you can define a persona that controls the tone, language style, and response behavior. You configure this through SDK content options and agent persona instructions. SDK content options control what UI elements appear and direct users to your custom agent. Agent persona instructions define the personality, response style, and knowledge boundaries (configured in the Quick console when you create the chat agent).

SDK content options

const contentOptions = { // Lock to your custom finance agent --- removes the generic agent selector // so users only interact with your purpose-built assistant agentOptions: { fixedAgentId: 'your-finance-agent-id', }, promptOptions: { // Auto-send a contextual greeting on first load. // The assistant proactively shares relevant insights // rather than waiting passively for a question. initialPrompt: 'What are the key financial highlights this quarter?', // Hide the user message bubble for the initial prompt. // This makes it appear as if the assistant initiated the conversation, // creating a more natural "advisor" experience. showInitialPromptMessage: false, // Enable file attachments --- users can upload spreadsheets // or reports for the assistant to analyze allowFileAttachments: true, // Show web search for supplementary market research showWebSearch: true, // Show chat history so users can resume prior conversations showChatHistory: true, // Display knowledge boundary indicator --- builds trust by showing // users what data sources the assistant can access showAgentKnowledgeBoundary: true, }, };

Agent persona instructions (Quick console)

When configuring your custom chat agent in the Amazon Quick console on the Chat Agents page, you define persona instructions that shape how the agent responds. The following example shows a persona instruction block you can use in your agent’s configuration:

You are the AnyCompany Finance Assistant, an AI embedded in AnyCompany's Finance Performance Dashboard.

Your Role

You help executive leadership, finance teams, and business leads explore financial data, understand performance trends, and take action on insights --- all without leaving the dashboard.

Response Style

• Lead with the direct answer and the key number
• Provide context and comparison to prior period
• Cite the source document when referencing qualitative information
• Use bullet points for multi-part answers
• Keep responses concise --- executives want the insight, not the explanation

Boundaries

• Only discuss AnyCompany financial data and business context
• Do not speculate about future performance beyond stated targets
• For questions outside your knowledge, direct users to [email protected]

Figure 4: Embedded Quick chat showing a response that follows the configured communication style

With the custom finance agent configured, the same question “What was our revenue last quarter?” now produces a response that matches your organization’s communication style: direct, data-driven, and contextual.

“Q2 2025 revenue was $8.89M, up 12.5% vs Q2 2024 ($7.05M). Growth was driven by consistent month-over-month momentum across all regions:

April: $2.89M

May: $2.95M

June: $3.05M

North America led with 15% growth, followed by EMEA at 9%.”

Figure 5: Quick chat response with the configured persona

The following table lists the persona customization options that you can configure while using the SDK.

Option Effect on persona/tone

fixedAgentId Locks to your custom agent with a specific personality

initialPrompt Sets the conversational opening: proactive or reactive

showInitialPromptMessage: false The assistant appears to initiate, creating an “advisor” feel

showAgentKnowledgeBoundary Transparency about what the assistant knows

Agent persona instructions Defines tone, vocabulary, response structure, and boundaries

Programmatic interaction

Beyond visual theming and persona, the SDK provides the sendPrompt() method. With this method, your application can trigger contextual questions from UI interactions. For example, when a user selects a chart metric, the application sends a related question to the assistant. This connects your dashboard visuals with the conversational interface.

// Store the experience reference after embedding const chatExperience = await embeddingContext.embedQuickChat( frameOptions, contentOptions );

// When a user selects a revenue metric card in your dashboard: chatExperience.sendPrompt( 'Explain the revenue trend this quarter and what is driving it.' );

In the finance dashboard example, quick-action buttons in the chat panel header implement this pattern:

const askAboutMetric = (metricName) => { chatExperience.sendPrompt( Explain the trend for ${metricName} and what's driving it. ); };

// Quick-action buttons const metrics = [ { metric: 'revenue', label: 'Revenue' }, { metric: 'profit margin', label: 'Margins' }, { metric: 'expenses', label: 'Expenses' } ];

const container = document.getElementById('quick-actions'); metrics.forEach(({ metric, label }) => { const button = document.createElement('button'); button.type = 'button'; button.textContent = label; button.setAttribute('aria-label', Ask about ${metric}); button.addEventListener('click', () => askAboutMetric(metric)); container.appendChild(button); });

Figure 6: Quick chat with a Revenue action button

Conclusion

In this post, we showed how to customize the Quick embedded chat interface to deliver a consistent, branded experience within your application. By configuring CSS, you align the chat panel visually with your design system so it appears as a native component rather than an external widget. By defining agent persona instructions and SDK prompt options, you can shape the chat’s communication style to match your brand voice. The sendPrompt() method bridges your application’s UI with the conversational interface by triggering contextual questions from user interactions like button clicks and chart selections.

Next steps

To put these customizations into practice, start by embedding the Quick chat into your application. Apply your brand’s color palette, typography, and layout through container CSS and SDK frame options so the chat feels like a native component. Next, create a custom chat agent in the Quick console with persona instructions that define your domain expertise and communication style.

About the authors