Embed Interviews on Your Website or App

Embedded Interviews let you deploy Perspective AI anywhere your users are—on marketing pages, inside product flows, or on support portals. Instead of sending participants to a separate link, the interview lives directly in your experience.

How to Embed an Interview#

1. Open the Embed Panel#

Open a Perspective and select Invite participants in the header. If you are on the Design page, use Next: Invite participants after the outline exists. Then choose Embed from the invitation options.

Embed option in the invite participants menu

2. Choose Your Embed Type#

Perspective offers five embed categories:

Full Page – Displays the interview as a full-viewport experience. Best for standalone pages where the conversation is the primary content.

Inline Widget – Drops the interview directly into your page content. Ideal for contextual placement within articles, product pages, or dashboards.

Button – Triggers the interview in one of three styles:

• Popup: Modal overlay centered on screen
• Slider: Side panel that slides in from the edge
• Float: Floating bubble anchored to the corner

Choose Button for unobtrusive placement that doesn't interrupt page flow.

Auto Trigger – Opens a popup automatically after a timeout or on exit intent. You can choose whether it appears every time, once per session, or once per visitor.

Card – Shows a clickable preview card that opens the interview in a new tab. Useful for resource centers or when you want users to opt into a full-screen experience.

Five embed type options with Full Page selected

3. Copy the Embed Code#

Once you select a type, Perspective generates the embed code automatically. You can copy:

• React code using @perspective-ai/sdk-react
• NPM/TypeScript code using @perspective-ai/sdk
• Script code using the hosted perspective.js script and data attributes
• HTML card code for the Card option

Preview before deploying: You can test Full Page, Inline, Popup, Slider, Float, and Auto Trigger directly from the embed panel using the preview and demo options. This lets you verify the experience before adding code to your site.

Inline embed preview showing interview in page

Button embed previews cycling through Popup, Slider, and Float styles

For technical teams using AI-assisted development tools, you can integrate via the Perspective AI MCP server. This lets you add embed code directly from Cursor, Codeium, Claude Code, or any IDE supporting custom MCPs.

Visual Options#

For SDK-based embeds, the embed panel can generate appearance parameters for:

• Showing or hiding conversation progress
• Showing or hiding the welcome greeting
• Showing or hiding the logo and brand header
• Allowing or hiding the fullscreen button

Float embeds also support launcher customization:

• Default icon, brand avatar, or custom image URL
• Launcher size
• Launcher shape

Auto Trigger embeds support:

• Timeout delay from 1 to 60 seconds
• Exit-intent trigger
• Show every time, once per session, or once per visitor

Click Publish after changing visual options if you want those embed settings saved with the conversation. The generated snippets also include the relevant SDK parameters so your developer can paste them directly.

Passing Participant Context#

Embeds can pass participant context the same way public links can.

For script embeds, use data-perspective-params:

<div  data-perspective-widget="RESEARCH_ID"  data-perspective-params="source=homepage,campaign=q2,user_id=123"></div><script src="https://getperspective.ai/v1/perspective.js"></script>

For React or TypeScript SDK embeds, pass a params object. Custom params are stored as participant metadata and can be used by the agent, results, analysis, and automations. System params such as hideProgress, hideGreeting, hideBranding, and enableFullScreen control the experience and are not stored as participant metadata.

For the full parameter reference, see Embed API and Track Participant Context.

Best Practices#

• Match embed type to context: Use Inline when the interview relates to specific page content. Use Button with Float style for persistent access across multiple pages.
• Test button styles: Try Popup, Slider, and Float styles to see which fits your site's interaction patterns.
• Preview before deploying: Use the "Open Demo" link to test the embed experience before adding it to your site.
• Track by placement: Use URL parameters such as source=pricing_page or placement=footer_float to compare which placements drive the most engagement.
• Use the SDK when possible: The SDK handles sizing, navigation, callbacks, theming, and lifecycle events. Direct iframe embeds require more manual handling.
• Handle redirects in apps: In single-page apps, use SDK callbacks such as onNavigate if you need to route without a full page reload.

Common Pitfalls & Fixes#

Embed code not rendering on site#

Verify the script tag is placed before the closing </body> tag and that no ad blockers are interfering with the Perspective domain.

Button embed doesn't match site styling#

Button embeds inherit basic styling. For custom button appearance, use the generated data attributes and apply your own CSS to the button element.

Card preview appears blank#

Card embeds generate a preview image when you first create the outline. If the preview is missing, re-save the outline to regenerate it.

Redirects do not work in a direct iframe#

Prefer the SDK. If you must use a direct iframe, add the postMessage listener shown in the Embed API.

Params are not reaching the agent#

Make sure you are using data-perspective-params or SDK params for custom context. Reserved system params control the embed and are not stored as participant metadata.