MercuryIQ embeds an AI-powered interviewer into your survey. After a respondent submits their initial answer, the AI conducts a follow-up conversation — probing for depth, flagging incoherent or off-topic responses — before handing control back to your survey platform.
Setup
Load the script on any page that contains a MercuryIQ question:
<script src="https://workbench.mercuryanalytics.com/api/conversations.js"></script>
Add two meta tags to identify the respondent and the question:
<meta name="hg rid" content="{respondent_id}">
<meta name="hg question" content="{project}/{question}">
{respondent_id}— a unique identifier for the current respondent{project}/{question}— the fully-qualified question name provided by Mercury Analytics
Note: the name attributes above contain a space (hg rid, hg question) — this is intentional and required.
The script initializes automatically on page load. No additional JavaScript is required.
The script attaches to the first <form> on the page — ensure the MercuryIQ question form is the first form in your document.
HTML Requirements
The script attaches to the first <form> on the page. That form must include:
- A
<textarea>for the respondent’s answer, with an associated<label>(the label text is updated with follow-up questions as the conversation progresses) - At least one submit button
Minimal example:
<form>
<label for="answer">What are your thoughts on this topic?</label>
<textarea id="answer" name="answer" required></textarea>
<button type="submit">Next</button>
</form>
If the form contains multiple textareas, the last one is used as the response input. Submit buttons are disabled while the script is waiting for a response.
Conversation Lifecycle
When the respondent submits the form, the script intercepts the submission and sends the answer to MercuryIQ. The API returns one of three response types:
continue — The AI has a follow-up question. The label text is updated with the new question and the textarea is cleared. The respondent answers and submits again.
warn — The response was flagged (irrelevant, incoherent, or evasive). A native browser validation message is shown on the textarea. The respondent must revise their answer before resubmitting.
terminate — The conversation is over. The form is submitted automatically. The termination reason (complete, unresponsive, or bot) determines what is stored in the textarea (see below).
End-of-Conversation Behavior
When the conversation ends, the script submits the form programmatically. The value stored in the textarea depends on how the conversation ended:
| Reason | Textarea value |
|---|---|
complete |
The AI’s closing message (text color set to transparent) |
unresponsive |
UNRESPONSIVE |
bot |
BOT |
For complete, the textarea value is set to the AI’s closing message; the text color is set to transparent so it is not visible to the respondent. Your platform may store or discard this value.
For unresponsive and bot, the uppercase sentinel values indicate that the respondent’s MercuryIQ interview was terminated for the given reason. Check for these values if you need to route or handle these respondents differently.
Error Handling
The script displays a browser alert for the following conditions:
| HTTP Status | Meaning |
|---|---|
| 400 | The conversation could not be created |
| 404 | No question found for the given {project}/{question} value |
| 503 | The question or project is not properly configured |
Contact Mercury Analytics if you encounter persistent 404 or 503 errors.
If initialization fails because the required meta tags or form are missing, the script exits silently and the form behaves normally.