Introduction
Rival chats can be embedded directly into external websites, apps, or popups, without redirecting participants to a standalone chat link. This is useful for in-context research experiences where you want respondents to complete a chat without leaving your site or product.
To enable embedding, you need to whitelist the domain where the chat will be hosted, then use a specially formatted distribution link that tells the Rival system the chat is running in an embedded context.
Prerequisites
Admin-level access to your Rival Research Domain Settings
The domain URL where you intend to embed the chat
A published Rival chat
Step 1: Whitelist Your Domain
Before a chat can be embedded, the target domain must be whitelisted in your Research Domain settings.
1. Open Domain Settings
Log in to your Rival account and navigate to the relevant Research Domain.
Click the Settings tab in the top navigation bar.
In the left sidebar, click Platforms.
2. Navigate to Whitelisted Domains
Click the Whitelisted Domains tab (alongside Recruitment Platforms and Secret Key Pairs).
3. Add a Whitelisted Domain
Click the blue + button in the top right corner.
A drawer will open titled Add Whitelisted Domain.
Fill in the following fields:
Field | What to Enter |
Label | A descriptive name for this domain (e.g., "Brand Site – Popup") |
Domain URL / IP Range | The full domain where the chat will be embedded (e.g., |
Purpose | Select Embedded Responding |
Click Save. The domain will now appear in your Whitelisted Domains list.
Step 2: Create and Publish Your Chat
If you haven't already, create the chat you want to embed:
Build your chat flow in Rival as normal.
Publish the chat
Step 3: Generate an Embedded Distribution Link
Standard distribution links will not work in an embedded context. You need to format the link specifically for embedding.
1. Create a Distribution Link
In your chat, go to the Distribute tab.
Click Create to open the new distribution link flow and generate a link.
2. Update the Link to the Embedded Format
Replace the standard distribution link format with the following embedded URL format:
https://chat.rivaltech.io/embed/c/{id}Replace {id} with the chat ID from your standard distribution link.
Example:
Standard Link | |
Embedded Link |
This format signals to the Rival system that the chat is loading inside an embedded frame and adjusts its behavior accordingly.
3. Use the Embedded Link in Your Implementation
Paste the embedded distribution link as the src attribute of an <iframe> in your website or popup:
<iframe src="https://chat.rivaltech.io/embed/c/{id}" width="400" height="600" frameborder="0"> </iframe>Adjust width and height to match your popup or container dimensions.
Best Practices
Test before going live. Load the embedded link in your target environment before deploying to respondents to confirm it renders correctly.
Use Embedded Responding as the purpose. Other purpose options will not enable the chat to load in an iframe, selecting the wrong purpose is the most common setup error.
One whitelist entry per distinct domain. Subdomains are treated as separate domains; whitelist them individually if needed.