Overview
Rival Discussions allows you to direct participants from a Rival chat into Qualzy activities and back to your chat as part of your study flow. This enables you to combine conversational research in Rival with deeper qualitative activities in Qualzy.
How it works
When a participant reaches a specific point in your Rival chat:
their information is securely sent to Qualzy through API
a participant profile is created (or matched) in the Qualzy project
they are redirected to the relevant Qualzy activity
they continue their experience in Qualzy
This ensures the participant arrives in the correct project with the context needed for the activity.
What information can be shared
To enable a seamless transition, key participant data can be passed from Rival to Qualzy, such as:
email address
name
participant ID
profile variables (for example, age or gender)
custom attributes
previous responses from the chat
The exact data passed can be customized based on your study needs.
Setting up the flow
Setting up Rival Discussions involves configuring how participant data is sent to Qualzy and how participants are redirected into the correct activity.
Step 1: Create a hidden variable for the token
Create a hidden variable in your Rival chat to store the Qualzy authentication token returned by the script.
This token is required to securely redirect participants into the correct Qualzy project.
Step 2: Configure the participant creation script
Add a script that:
sends participant data from Rival to Qualzy
creates (or matches) the participant in the Qualzy project
returns an authentication token for redirect
Below is a generalized sample script for reference:
qualzyAPIUrl = "<your_qualzy_api_url>"
qualzyProjectId = "<your_project_id>"
local payload = {}
local participant = getParticipant()
local pId = participant.participantId
-- Example fields (customize based on your study)
payload["EmailAddress"] = pId .. "@example.com"
payload["FirstName"] = gDBL("<your_field_name>").Value
local tags = {}
tags[1] = "RivalId:" .. pId
payload["Tags"] = tags
local jsonPayload = encodeJSON(payload)
local headers = {}
headers["Content-Type"] = "application/json"
headers["x-account-token"] = '{{{secrets.Qualzy_API_AuthToken}}}'
result = putHttp(
qualzyAPIUrl .. "/api/MyAccount/Projects/" .. qualzyProjectId .. "/members",
decodeJSON(jsonPayload),
headers
)
return result.data
You will need to replace:
<your_qualzy_api_url><your_project_id><your_field_name>
We recommend working with your Customer Success lead to:
finalize the script based on your study
confirm the correct variables are passed
validate the token is stored correctly
Once set up, this script can be reused across multiple chats.
Step 3: Get your Qualzy API and Project details
To configure the script, you will need:
Project ID
Navigate to your Qualzy project dashboard
Copy the 36-character ID from the URL
Account Auth (API) Key
Go to Settings → Platforms → Secret Keypairs
Locate your API key
Reference it using the key label in your script
API URL
Go to Settings → Platforms → Whitelisted Domains
Copy the Domain URL for the Qualzy API URL Domain
Step 4: Add the redirect in your chat
Use a Redirect Card to send participants to Qualzy.
You have two options:
Redirect out and return to chat
Participant completes the Qualzy activity
Returns to Rival to continue the study
Redirect out and end chat
Participant is sent to Qualzy
Study continues fully in Qualzy and ends there
In both cases:
Pass the Auth token stored in your hidden variable
Ensure the redirect URL includes the token with URL variable label as
id
Testing your setup
Before launching, test the full flow end-to-end. Check that the:
participant is successfully created in Qualzy
correct data is passed
redirect lands in the correct Qualzy activity
return flow works (if enabled)
These test runs create real participant records. Before going live, remove test participants to keep your data clean:
go to the People section in Qualzy
find the test participant
use the menu to update their status to Declined
This ensures test responses are excluded from your live study data.